> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rownd.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Vue

> Easily add Rownd instant accounts and authentication to your Vue-based project.

## Installation

Simply run `npm install @rownd/vue` or `yarn add @rownd/vue`.

<Info>
  This plugin only works with Vue 3 and above! If you need support for Vue 2,
  please [get in
  touch](mailto:support@rownd.io?subject=Support%20for%20Vue%20v2).
</Info>

## Usage

The library provides a Vue plugin and injector hook for Vue-based apps.

In your app's main entrypoint, install the Rownd plugin like in the following
example:

```jsx theme={null}
import { createApp } from "vue";
import { RowndPlugin } from "@rownd/vue"; // Import the plugin

import App from "./App.vue";
import router from "./router";

const app = createApp(App);

// Initialize the plugin. Be sure to include your app key!
app.use(RowndPlugin, {
  appKey: "<your app key>",
});

app.use(router);

app.mount("#app");
```

### Plugin options

* `appKey` (required): This is the key generated by the
  [Rownd dashboard](https://app.rownd.io/).

* `rootOrigin` (optional): If you're using Rownd across multiple domains (e.g.,
  `rownd.io` and `app.rownd.io`), set this to the "root" *origin* (e.g.,
  [https://rownd.io](https://rownd.io)).

Later on within your app's components, you can use the Rownd injector/hook to
access the Rownd browser API:

```jsx theme={null}
<script setup lang="ts" type="application/javascript">
    import { RouterLink, RouterView } from "vue-router";
    import HelloWorld from "@/components/HelloWorld.vue";
    import { useRownd } from "@rownd/vue";

    const rownd = useRownd();
</script>

<template>
    <div v-if="rownd.is_authenticated">
        <h1>Welcome, {{ rownd.user.data.full_name }}!
        <strong>{{ rownd?.user?.data?.first_name }}</strong>
    </div>

    <div v-if="!rownd.is_authenticated">
        <button @click="rownd.requestSignIn({})">Sign in</button>
    </div>
</template>
```

### API reference

Most API methods are made available via the Rownd plugin and its associated
`useRownd` injector. Javascript will be used for most examples, but these should
work with Vue directives as well.

#### `requestSignIn()`

Trigger the Rownd sign in dialog. This can be used from a link/button or
programmatically, if you wanted to allow a user to use parts of your app without
signing in, but then trigger the sign-in prior to them doing something
important.

```jsx theme={null}
const rownd = useRownd();

rownd.requestSignIn({
  auto_sign_in: false, // optional
  identifier: "me@company.com" || "+19105551212", // optional
});
```

* `auto_sign_in: boolean` - when `true`, automatically trigger a sign-in
  attempt *if* `identifier` is included or an email address or phone number has
  already been set in the user data.

* `identifier: string` - an email address or phone number (in E164 format) to
  which a verification message may be sent. If the Rownd app is configured to
  allow unverified users, then sign-in will complete without verification if the
  user has not signed in previously.

**signOut()**

Sign out the user and clear their profile, returning them to a completely
unauthenticated state.

```jsx theme={null}
<script setup>
    const rownd = useRownd();
</script>

<template>
    <button v-if="rownd.is_authenticated" @click="rownd.signOut()">Sign out</button>
</template>
```

**getAccessToken()**

Retrieves the active, valid access token for the current user.

```jsx theme={null}
const rownd = useRownd();
let accessToken = await rownd.getAccessToken({
  waitForToken: false,
});
```

* `waitForToken: boolean` - when `true`, if no access token is present or if
  it's expired, the promise will not resolve until a valid token is available.
  While unlikely, this could result in waiting forever.

**is\_initializing**

`is_initializing` will be `true` until the Hub has fully loaded, recalled its
state, and resolved the current user's authentication status. This usually takes
only a few milliseconds, but if you make decisions that depend on the
`is_authenticated` flag while `is_initializing` is still `true`, your code/logic
may not work as you expect.

```jsx theme={null}
<script setup>
    const rownd = useRownd();
</script>

<template>
    <div v-if="rownd.is_initializing">Loading...</div>
    <div v-else>
        <p>Show some real content</p>
    </div>
</template>
```

**is\_authenticated**

Indicates whether the current user is signed in or not.

```jsx theme={null}
<script setup>
    const rownd = useRownd();
</script>

<template>
    <ProtectedComponent v-if="rownd.is_authenticated" />
    <PublicComponent v-else />
</template>
```

**access\_token**

Represents the current access token for the user.

```jsx theme={null}
<script setup>
    const rownd = useRownd();

    const resp = await fetch('/api/sessions', {
        method: 'post',
        headers: {
            authorization: `Bearer ${rownd.access_token}`
        }
    });

    const body = await resp.json();
</script>
```

**user**

Represents information about the current user, specifically their profile
information. In the example below, we use the existing data to display the
current value of `first_name` in a form field, and then immediately sync changes
to Rownd as the user updates the form field.

```jsx theme={null}
<script setup>
    const rownd = useRownd();
</script>

<template>
    <label for="first_name">
        <input
            id="first_name"
            type="text"
            v-model="rownd.user.data.first_name"
        />
    </label>
</template>
```

You might not want to sync changes to Rownd immediately, but rather wait for the
user to click a button, as in the following example:

```jsx theme={null}
<script setup>
    import { reactive } from 'vue';
    const rownd = useRownd();

    const userData = reactive(rownd.value.user.data);

    function onSubmit() {
        rownd.user.set(userData);
    }
</script>

<template>
    <form @submit.prevent="onSubmit">
        <label for="first_name">
            <input
                id="first_name"
                type="text"
                v-model="userData.first_name"
            />
        </label>
        <button type="submit">Save</button>
    </form>
</template>
</template\>
```

**Merge data into the user profile programmatically**

```jsx theme={null}
const rownd = useRownd();
rownd.user.set({
  first_name: "Juliet",
  last_name: "Rose",
});
```

Set a specific field in the user profile programmatically

```jsx theme={null}
const rownd = useRownd();
user.setValue('first_name', 'Alice');
```