From e6a9debbe97dfdc1b1b5596725b8ea3a2eb0c2be Mon Sep 17 00:00:00 2001 From: vi Date: Fri, 13 Dec 2024 14:24:47 -0500 Subject: [PATCH] update --- docs/references/vue/use-auth.mdx | 63 ++++++++++++------- docs/references/vue/use-clerk.mdx | 18 +++--- docs/references/vue/use-sign-in.mdx | 95 +++++++++++++++++++++-------- docs/references/vue/use-user.mdx | 76 +++++++++++++---------- 4 files changed, 166 insertions(+), 86 deletions(-) diff --git a/docs/references/vue/use-auth.mdx b/docs/references/vue/use-auth.mdx index e76bc31795..b08a0e9778 100644 --- a/docs/references/vue/use-auth.mdx +++ b/docs/references/vue/use-auth.mdx @@ -1,102 +1,121 @@ --- title: '`useAuth()`' -description: Clerk's useAuth() composable is a convenient way to access the current auth state. +description: Access and manage authentication state in your Vue application with Clerk's useAuth() composable. --- -The `useAuth()` composable provides information about the current auth state, as well as helper methods to manage the current active session. +The `useAuth()` composable provides access to the current authentication state and methods to manage the active session in your Vue application. -## `useAuth()` returns +## Usage + +```vue + +``` + +## Return values - - `isSignedIn` + - `isLoaded` - `Ref` - A boolean that returns true if the user is signed in. + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. --- - - `isLoaded` + - `isSignedIn` - `Ref` - A boolean that until Clerk loads and initializes, will be set to `false`. Once Clerk loads, `isLoaded` will be set to `true`. + A boolean that indicates whether a user is currently signed in. --- - `userId` - `Ref` - The current user's ID. + The unique identifier of the current user. --- - `sessionId` - `Ref` - The current user's session ID. + The unique identifier of the current session. --- - `orgId` - `Ref` - The current user's active organization ID. + The unique identifier of the user's active organization. --- - `orgRole` - `Ref` - The current user's active organization role. + The current user's role in their active organization. --- - `orgSlug` - `Ref` - The current user's organization slug. + The URL-friendly identifier of the user's active organization. --- - `signOut()` - `Ref<(options?: SignOutOptions) => Promise>` - A function that signs the user out. See the [reference documentation](/docs/references/javascript/clerk/clerk#sign-out) for more information. + A function that returns a promise that resolves when the current user is signed out. See the [reference doc](/docs/references/javascript/clerk/clerk#sign-out). --- - `getToken()` - `Ref<(options?: GetTokenOptions) => Promise>` - A function that returns a promise that resolves to the current user's session token. Can also be used to retrieve a custom JWT template. See the [reference documentation](/docs/references/javascript/session#get-token) for more information. + A function that returns a promise that resolves to the current user's session token. Can also retrieve a custom JWT template. See the [reference doc](/docs/references/javascript/session#get-token). --- - `has()` - `Ref<(isAuthorizedParams: CheckAuthorizationParamsWithCustomPermissions) => boolean>` - A function that returns a boolean based on the permission or role provided as parameter. Can be used for authorization. See the [reference documentation](/docs/references/nextjs/auth-object#has){{ target: '_blank' }} for more information. + A function that returns a boolean indicating whether the user has specific permissions or roles. See the [reference doc](/docs/references/javascript/auth-object#has). -## How to use the `useAuth()` composable +## Example -The following example demonstrates how to use the `useAuth()` composable to access the current auth state, like whether the user is signed in or not. It also demonstrates a basic example of how you could use the `getToken()` method to retrieve a session token for fetching data from an external resource. +The following example demonstrates how to use `useAuth()` to access the authentication state, protect a page, and fetch data from an external API: -```vue {{ filename: 'external-data-page.vue' }} +```vue {{ filename: 'App.vue' }} ``` diff --git a/docs/references/vue/use-clerk.mdx b/docs/references/vue/use-clerk.mdx index 1ff534cfd6..90521e9bdc 100644 --- a/docs/references/vue/use-clerk.mdx +++ b/docs/references/vue/use-clerk.mdx @@ -1,20 +1,16 @@ --- title: '`useClerk()`' -description: Clerk's useClerk() composable is used to access the Clerk object, which can be used to build alternatives to any Clerk Component. +description: Access and manage the Clerk instance in your Vue application with Clerk's useClerk() composable. --- -The `useClerk()` composable is a convenient way to access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object, giving you the ability to build alternatives to any Clerk Component. - > [!WARNING] -> This is intended to be used for advanced use cases, like building a completely custom OAuth flow or as an escape hatch for getting access to the `Clerk` object. - -## `useClerk()` returns +> This composable should only be used for advanced use cases, such as building a completely custom OAuth flow or as an escape hatch to access to the `Clerk` object. -The `useClerk()` composable returns the `Clerk` object, which includes all the methods and properties listed in the [`Clerk` reference](/docs/references/javascript/clerk/clerk). +The `useClerk()` composable provides access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object, giving you the ability to build alternatives to any [Clerk component](/docs/components/overview). -## How to use the `useClerk()` composable +## Usage -```vue {{ filename: 'home.vue' }} +```vue +``` + +```ts +function useSignIn(): { + isLoaded: Ref + signIn: Ref + setActive: Ref<(params: SetActiveParams) => Promise> +} +``` + +## Reference + +### Return values - `isLoaded` - `Ref` - A boolean that is set to `false` until Clerk loads and initializes. + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. --- @@ -28,7 +48,9 @@ The `useSignIn()` composable provides access to the [`SignIn`](/docs/references/ An object that contains the current sign-in attempt status and methods to create a new sign-in attempt. -### `SetActiveParams` +### Types + +#### `SetActiveParams` - `session` @@ -48,16 +70,55 @@ The `useSignIn()` composable provides access to the [`SignIn`](/docs/references/ - `beforeEmit?` - `(session?: Session | null) => void | Promise` - Callback run just before the active session and/or organization is set to the passed object. Can be used to composable up for pre-navigation actions. + Callback run just before the active session and/or organization is set to the passed object. Can be used to set up for pre-navigation actions. -## How to use the `useSignIn()` composable +#### `SignIn` status values + +The `status` property of the `SignIn` object can be one of the following values: + + + - `complete` + - `string` + + The user is signed in and the custom flow can proceed to `setActive()` to create session. + + --- -### Check the current state of a sign-in with `useSignIn()` + - `needs_first_factor` + - `string` -Use the `useSignIn()` composable to check the current state of a sign-in. + One of the following [first factor verification strategies](/docs/references/javascript/sign-in/first-factor) is missing: `email_link`, `email_code`, `phone_code`, `web3_metamask_signature`, `web3_coinbase_wallet_signature` or `oauth_provider`. + + --- -```vue {{ filename: 'pages/sign-in-step.vue' }} + - `needs_second_factor` + - `string` + + One of the following [second factor verification strategies](/docs/references/javascript/sign-in/second-factor) is missing: `phone_code` or `totp`. This value is optional. + + --- + + - `needs_identifier` + - `string` + + The user's identifier (e.g., email address, phone number, username) hasn't been provided. + + --- + + - `needs_new_password` + - `string` + + The user needs to set a new password. + + +## Example + +### Check and show sign-in status + +The following example checks the current sign-in status and displays the value in the UI. + +```vue {{ filename: 'SignInPage.vue' }} +``` - --- +```ts +function useUser(): { + isLoaded: Ref + user: Ref + isSignedIn: Ref +} +``` + +## Reference +### Return values + + - `isLoaded` - `Ref` - A boolean that until Clerk loads and initializes, will be set to `false`. Once Clerk loads, `isLoaded` will be set to `true`. + A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads. --- - `user` - Ref\<[User](/docs/references/javascript/user/user)> - The `User` object for the currently active user. If the user is not signed in, `user` will be `null`. - + The `User` object for the current active user. If the user is not signed in, `user` will be `null`. + + --- + + - `isSignedIn` + - `Ref` -## How to use the `useUser()` composable + A boolean that returns `true` if the user is signed in. + -### Retrieve the current user data with the `useUser()` composable +## Examples -The following example demonstrates how to use the `useUser()` composable to access the `user` object, which includes the current user's data, like the user's full name. The `isLoaded` and `isSignedIn` properties are used to handle the loading state and to check if the user is signed in, respectively. +### Get the current user -For more information on the `User` object, see the [`reference`](/docs/references/javascript/user/user). +Use `useUser()` to access the [`User`](/docs/references/javascript/user/user) object, which contains the current user's data like their full name. The `isLoaded` and `isSignedIn` value handle loading states and check authentication status. -```vue {{ filename: 'home.vue' }} +```vue {{ filename: 'GetCurrentUser.vue' }}