Usermatic Docs

Usermatic is the wrapper component for all Usermatic applications. Any part of your application that uses Usermatic components or hooks must be inside a <Usermatic> component.

Placing <Usermatic> in your _app.js file is usually the easiest way to set up Usermatic.

Properties:

{

appId:string

The ID of the Usermatic Application.

children:ReactNode

The React components within which Usermatic will be used. (Typically your entire application).

components?:Components

Provide custom display components to use when rendering Usermatic components. See "Customizing Usermatic" for more information

showDiagnostics?:boolean

If true, insert Usermatic diagnostics into your application. Defaults to false.

uri?:string

The URI of the Usermatic API endpoint. For development use only.

useBootstrapClasses?:boolean

If true, add bootstrap class names to Usermatic components. Use this if your application uses bootstrap. Defaults to true.

useUmClasses?:boolean

If true, add class names begining with the um- prefix to Usermatic HTML elements, so that you can style Usermatic with your own CSS. Defaults to false.

}

Examples

// Using Usermatic in a NextJS app.
// File: pages/_app.js
import { Usermatic } from '@usermatic/client'
function MyApp({ Component, pageProps }) {
  // Replace appId with your usermatic application id.
  return <Usermatic appId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx">
    <Component {...pageProps} />
  </Usermatic>
}

// Using Usermatic with Create React App.
// File: src/index.js
import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import { Usermatic } from '@usermatic/client'
// Replace appId with your usermatic application id.
ReactDOM.render(
  <React.StrictMode>
    <Usermatic appId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx">
      <App />
    </Usermatic>
  </React.StrictMode>,
  document.getElementById('root')
);

<LoginForm> allows users to log in to your application. It handles both password and Oauth logins. Oauth login buttons are automatically displayed for any Oauth provider that you have enabled for your Usermatic app.

Properties:

{

components?:Components

Display components for LoginForm. See 'Customizing Usermatic' for more information.

idPrefix?:string

onChangeMode?:(mode: LoginMode) => void

onChangeMode is called when the LoginForm switches "modes". For instance, if the user clicks the "Forgot Password" button, onChangeMode will be called with the 'forgotpw' argument.

onLogin?:() => void

onLogin is called after the user successfully logs in.

}

Preview

<LoginForm/>

<LoginForm/>

<AccountCreationForm> allows users to create accounts on your site.

Properties:

{

components?:Components

Display components for AccountCreationForm. See 'Customizing Usermatic' for more information.

idPrefix?:string

loginAfterCreation?:boolean

If true, the user will be automatically logged in as soon as their account has been created. Note that if you have set the "Require verified email for login" setting to true in your application settings, this option will not work.

onLogin?:() => void

onLogin() is called after the user is successfully logged in.

showPasswordScore?:boolean

If set, the strength of the user's password is displayed and automatically updated as they modify it.

}

Preview

<AccountCreationForm/>

<AccountCreationForm/>

<AddTotpForm> allows the user to configure time-based one time passwords (e.g. Google Authenticator) for their account.

Properties:

{

components:undefined | {}

idPrefix:undefined | string

onSuccess:undefined | () => void

}

Preview

<AddTotpForm/>

<AddTotpForm/>

<AccountCreationForm> allows users to create accounts on your site.

Properties:

{

components?:Components

Display components for AccountCreationForm. See 'Customizing Usermatic' for more information.

idPrefix?:string

loginAfterCreation?:boolean

onLogin?:() => void

onLogin() is called after the user is successfully logged in.

showPasswordScore?:boolean

If set, the strength of the user's password is displayed and automatically updated as they modify it.

}

Preview

<AccountCreationForm/>

<AccountCreationForm/>

<RequestPasswordResetForm> allows the user to request a password reset email. Normally, you do not need to embed this component directly, as <LoginForm> will display it when the user clicks "Forgot Password"

Properties:

{

components?:Components

Custom display components. See 'Customizing Usermatic' for more information.

idPrefix?:string

onCancel?:() => void

Called when the user clicks the cancel button instead of submitting their email.

}

Preview

<RequestPasswordResetForm/>

<RequestPasswordResetForm/>

Enter your email to get a password reset link.

<ResetPasswordForm> allows the user to reset their password using a reset token that they have obtained via email. This component should be placed at the location pointed to by the Reset Password URI setting in your Usermatic application settings.

Properties:

{

components?:Components

Display components for ResetPasswordForm. See 'Customizing Usermatic' for more information.

exposeLoginAfterReset?:boolean

If true, render the "login after reset" option. If the user checks this box, it has the same effect as if the loginAfterReset property had been set to true.

idPrefix?:string

loginAfterReset?:boolean

If true, the user will be automatically logged in after resetting their password. Note: This will not work if the user has enabled MFA on their account. In that case, they will have to log in via <LoginForm>

onLogin?:() => void

Called after the user is successfully logged in (which will only happen if the loginAfterReset property is true.)

redirectAfterReset?:boolean

If true, the user will be automatically redirected to the URI that has been configured the Usermatic application settings after resetting their password.

token?:string

The password-reset token, contained in the reset link that was sent to the user via email. If omitted, ResetPasswordForm attempts to find the token in window.location.href, in the 'token' query parameter.

}

Preview

<ResetPasswordForm token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InVzZXJAaG9zdC5jb20iLCJjcmVkZW50aWFsSWQiOiJlZGZlZjg3YS03YWViLTRlNjYtYmE3MS0yMGI0MGVmNmRlNWMiLCJpZCI6IjE5ZTFjODA0LTBiMzAtNDYyYS05ODFiLWU1Y2MxZDg1ZWIzZiIsImFwcElkIjoiZDQ0MWZjZWQtNTZjNy00NzVjLThjODctNjE3OWI2NDU2Mzk5IiwiYWN0aW9uIjoiUkVTRVRfUFciLCJpYXQiOjE1OTM3MDIyNzF9.B4jCukSRelG9X4tAGjBhkU2wjhdLwKOj9x2kvDladwg"/>

<ResetPasswordForm token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InVzZXJAaG9zdC5jb20iLCJjcmVkZW50aWFsSWQiOiJlZGZlZjg3YS03YWViLTRlNjYtYmE3MS0yMGI0MGVmNmRlNWMiLCJpZCI6IjE5ZTFjODA0LTBiMzAtNDYyYS05ODFiLWU1Y2MxZDg1ZWIzZiIsImFwcElkIjoiZDQ0MWZjZWQtNTZjNy00NzVjLThjODctNjE3OWI2NDU2Mzk5IiwiYWN0aW9uIjoiUkVTRVRfUFciLCJpYXQiOjE1OTM3MDIyNzF9.B4jCukSRelG9X4tAGjBhkU2wjhdLwKOj9x2kvDladwg"/>

ChangePasswordForm allows the user to change their password.

Properties:

{

components?:Components

Display components for ChangePasswordForm. See 'Customizing Usermatic' for more information.

idPrefix?:string

onSuccess?:() => void

Function to be called after password is successfully changed.

}

Preview

<ChangePasswordForm/>

<ChangePasswordForm/>

<PasswordScore> estimates the strength of the user's password using zxcvbn (https://github.com/dropbox/zxcvbn) and displays it using the customizable <PasswordScoreComponent>

You generally shouldn't use this compoment directly. All the relevant components (e.g. <AccountCreationForm>, <ChangePasswordForm>, etc) use it automatically.

Both the username and password properties are debounced at a default interval of 300ms.

Properties:

{

components?:Components

Custom display components. See 'Customizing Usermatic' for more information.

debounceMs?:number

Debounce time in ms for both the password and username. Defaults to 300ms.

password?:string

The user's prospective password.

username?:string

The user's email address.

}

Preview

<PasswordScore password="hunter2" username="joe@um"/>

<PasswordScore password="hunter2" username="joe@um"/>

<EmailVerifier> uses a email verification token from the URL to tell the Usermatic API server that the user's email address is now verified.

This component should be placed on the page located at the "Verification Target URI" setting in your Usermatic application settings.

Properties:

{

components:undefined | {}

tokenProp:undefined | string

}

<ReauthenticateGuard> is used to hide some sensitive action behind a reauthentication prompt. It first prompts the user for a password, and uses that password to obtain a reauthentication token from Usermatic.

Once the token has been obtained, <ReauthenticateGuard> renders the child components that you have passed to it, which presumably implement your sensitive action.

Those child components can obtain the reauthentication token by calling useReauthToken(). They should then send the token to your own application backend, which can use it to verify that the user successfully re-authenticated before performing the sensitive action.

<ReauthenticateGuard> automatically caches tokens that it obtains. The maxTokenAge property determines how long they are cached.

See "Reauthenticating before Sensitive actions" for more information.

Properties:

{

children:ReactNode

The components that are guarded by the ReauthenticateGuard. They will be displayed after reauthentication has occurred, and can obtain the resulting reauthentication token by called useReauthToken()

components?:Components

Display components for ReauthenticateGuard. See 'Customizing Usermatic' for more information.

maxTokenAge?:string

maxTokenAge limits how long a token will be cached in your application. The format is anything supported by https://github.com/vercel/ms, e.g. "5m" or "60s" or "2h", etc.

This only controls caching. It has no effect on the expiration time of the token signed by Usermatic. Reauthentication tokens never have an expiration time set. Your application backend must enforce its own expiration time by passing 'maxAge' when verifying the token.

See "Reauthenticating before Sensitive actions" for more information.

onClose?:() => void

onClose() can be used to hook ReauthenticateGuard up to a modal. It is calledl when the user clicks the "Close" button displayed by <ReauthenticateGuard>

prompt?:ReactNode

A prompt to diplay above the password input.

tokenContents:string | object

The contents of the token you wish Usermatic to sign. Please remember that the contents of the token can be set to anything by any user, and therefore the security of your application should not rely on the contents of the token. The only thing that the reauthentication token proves is that the tokenContents and a valid password were presented to the Usermatic backend at a certain time.

The purpose of tokenContents is simply to require a user to perform separate reauthentications for differing sensitive actions. For instance, Usermatic itself requires separate reauthentications when you export application data and when you delete an application. It does this by requiring a token with a specific value of tokenContents for each operation.

The rule to bear in mind is that anyone who knows the password can obtain a reauthenticationToken token with any conceivable tokenContents, simply by asking the Usermatic backend.

See "Reauthenticating before Sensitive actions" for more information.

}

Preview

const GuardedComponent = () => {
  const reauthToken = useReauthToken()
  return <div>
    The reauthentication token is <pre>{reauthToken}</pre>
    <br/>
    Send this token to your server to prove that the user entered their
    password.
  </div>
}

const Prompt = () => <div>
  Please enter your password to demonstrate how reauthentication
  tokens work.
</div>

render(
  <ReauthenticateGuard
    prompt={<Prompt/>}
    tokenContents={{ operations: ['my-operation'] }}
  >
    <GuardedComponent/>
  </ReauthenticateGuard>
)

const GuardedComponent = () => {
  const reauthToken = useReauthToken()
  return <div>
    The reauthentication token is <pre>{reauthToken}</pre>
    <br/>
    Send this token to your server to prove that the user entered their
    password.
  </div>
}
const Prompt = () => <div>
  Please enter your password to demonstrate how reauthentication
  tokens work.
</div>
render(
  <ReauthenticateGuard
    prompt={<Prompt/>}
    tokenContents={{ operations: ['my-operation'] }}
  >
    <GuardedComponent/>
  </ReauthenticateGuard>
)

Please enter your password to demonstrate how reauthentication tokens work.

<GenRecoveryCodesForm> allows the user to generate or re-generate MFA recovery codes.

<GenRecoveryCodesForm> is automatically guarded by <ReauthenticateGuard> which will prompt the user for their password, as generating new recovery codes is considered a sensitive action.

Properties:

{

components:undefined | {}

onClose:undefined | () => void

onSuccess:

onSuccess() => void

}

Preview

<GenRecoveryCodesForm/>

<GenRecoveryCodesForm/>

Please wait...

<ComponentProvider> allows you to override the default display components used by Usermatic. For instance if you wish to use a custom text input component in all Usermatic forms, you can use <ComponentProvider> to do so.

As a convenience, the <Usermatic> component also accepts all the properties of <ComponentProvider>. If you wish to use the same custom components everywhere in your app, you can simply pass them to <Usermatic>

<ComponentProvider> also allows you to enable or disable the use of bootstrap classes or usermatic classes (semantic class names beginning with um-) in default components. If you are using customized components, these settings have no effect.

See 'Customizing Usermatic' for more information.

Properties:

{

bootstrapClasses:undefined | boolean

children:undefined | null | string | number | {} | ReactElement<any, string | (props: P) => ReactElement | null | {}> | ReactNodeArray | ReactPortal | boolean

propComponents:undefined | {}

usermaticClasses:undefined | boolean

}

Preview

const InputComponent = ({
  labelText,
  ...props
}) => {
  return <div style={{
    backgroundColor: 'rgb(228, 27, 27, 0.5)'
  }}>
    { labelText &&
      <label htmlFor={props.id}>
        {labelText}
      </label>
    }
    <input {...props} autoFocus={false} />
  </div>
}

const components = { InputComponent }

render(
  <ComponentProvider components={components}>
    <LoginForm/>
  </ComponentProvider>
)

const InputComponent = ({
  labelText,
  ...props
}) => {
  return <div style={{
    backgroundColor: 'rgb(228, 27, 27, 0.5)'
  }}>
    { labelText &&
      <label htmlFor={props.id}>
        {labelText}
      </label>
    }
    <input {...props} autoFocus={false} />
  </div>
}
const components = { InputComponent }
render(
  <ComponentProvider components={components}>
    <LoginForm/>
  </ComponentProvider>
)

<UserAccountSettings> is essentially an auto-generated profile page for your users. Simply include it on some page (perhaps /profile), and your users will automatically have access to basic functionality such as password changes, MFA configuration, etc.

To customize the appearance of <UserAccountSettings>, you can provide overrides for the following components: UserAccountSettingsComponent, SecurityInfoComponent, EmailStatusComponent, PersonalDetailComponent, LoginMethodsComponent.

See 'Customizing Usermatic' for more information.

Properties:

{

propComponents:undefined | {}

}

Preview

<UserAccountSettings/>

<UserAccountSettings/>

Personal Details

Please wait...

Name

useAppId()

Gets the current application ID (as passed to the <Usermatic> component).

Signatures:

useAppId() => string

useAppConfig()

Returns the publicly visible configuration of the current app.

May briefly return a hard-coded default config while waiting to load the correct config from the Usermatic backend.

Signatures:

useAppConfig() => AppConfig

Preview

function AppConfigPreview () {
  const config = useAppConfig()
  return <pre>{JSON.stringify(config, null, '  ')}</pre>
}

render(<AppConfigPreview/>)

function AppConfigPreview () {
  const config = useAppConfig()
  return <pre>{JSON.stringify(config, null, '  ')}</pre>
}
render(<AppConfigPreview/>)

{
  "appName": "",
  "totpEnabled": false,
  "fbLoginEnabled": false,
  "fbLoginUrl": "https://usermatic.io/auth/facebook",
  "googleLoginEnabled": false,
  "googleLoginUrl": "https://usermatic.io/auth/google",
  "githubLoginEnabled": false,
  "githubLoginUrl": "https://usermatic.io/auth/github"
}

useToken()

Returns the logged-in user's user id, as well as their signed authentication token.

Signatures:

useToken() => AuthTokenData

Examples

const { userJwt } = useToken()
useEffect(() => {
  if (userJwt) {
    // Send a query to our backend and include the logged in user's authToken
    fetch('/api/hello', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': userJwt
      },
      body: JSON.stringify({query: "{ hello }"})
    }).then((result) => {
      return result.json()
    }).then((json) => {
      console.log('got response', json)
    })
  }
}, [userJwt])

Preview

function TokenPreview () {
  const { id, userJwt } = useToken()
  return <div>
    <div>id: <code>{id}</code></div>
    <div>userJwt: <code>{userJwt}</code></div>
  </div>
}

render(<TokenPreview/>)

function TokenPreview () {
  const { id, userJwt } = useToken()
  return <div>
    <div>id: <code>{id}</code></div>
    <div>userJwt: <code>{userJwt}</code></div>
  </div>
}
render(<TokenPreview/>)

id:

userJwt:

useGetRecoveryCodeCount()

Return the number of valid recovery codes remaining for the currently logged-in user.

Signatures:

useGetRecoveryCodeCount() => {
count?:number
error?:ApolloError
loading:boolean
}

Preview

function RecoveryCodeCountPreview () {
  const { loading, count } = useGetRecoveryCodeCount()
  if (loading) {
    return <div>Please wait...</div>
  } else {
    return <div>You have {count} recovery codes remaining.</div>
  }
}

render(<RecoveryCodeCountPreview/>)

function RecoveryCodeCountPreview () {
  const { loading, count } = useGetRecoveryCodeCount()
  if (loading) {
    return <div>Please wait...</div>
  } else {
    return <div>You have {count} recovery codes remaining.</div>
  }
}
render(<RecoveryCodeCountPreview/>)

Please wait...

useCreateRecoveryCodes()

useCreateRecoveryCodes is an Apollo mutation operation for generating new recovery codes for the logged in user.

Creating new codes invalidates all existing codes.

You should almost certainly use <GenRecoveryCodesForm> instead of using this hook directly.

Signatures:

useCreateRecoveryCodes(options: CreateRecoveryCodesOptions) => [submitWrapper, {
success:boolean
}]

useProfile()

Signatures:

useProfile() => {
error:undefined | ApolloError
loading:boolean
profile:undefined | {
__typename?:'User'
} & {
__typename:'User'
} & {} & {
credentials:Array<{
__typename?:'UserCredential'
} & {}>
name:{
__typename?:'Name'
} & {}
}
}

usePrimaryEmail()

Returns the primary email of the currently logged in user.

If the user has an email/password credential, this will return that email.

Otherwise, if they have only OAuth credentials, this will return the first email from their first OAuth credential.

Signatures:

usePrimaryEmail() => {
email?:string
error?:ApolloError
loading:boolean
}

Preview

function PrimaryEmailPreview () {
  const { loading, email } = usePrimaryEmail()
  if (loading) {
    return <div>Please wait...</div>
  } else {
    return <div>Hello {email}</div>
  }
}

render(<PrimaryEmailPreview/>)

function PrimaryEmailPreview () {
  const { loading, email } = usePrimaryEmail()
  if (loading) {
    return <div>Please wait...</div>
  } else {
    return <div>Hello {email}</div>
  }
}
render(<PrimaryEmailPreview/>)

Please wait...

useCredentials()

Return all credentials associated with the currently logged-in user.

Signatures:

useCredentials() => {
credentials?:Credential[]
error?:ApolloError
loading:boolean
}

Preview

function CredentialPreview () {
  const { loading, credentials } = useCredentials()
  if (loading) {
    return <div>Please wait...</div>
  } else {
    return <pre>{JSON.stringify(credentials, null, '  ')}</pre>
  }
}

render(<CredentialPreview/>)

function CredentialPreview () {
  const { loading, credentials } = useCredentials()
  if (loading) {
    return <div>Please wait...</div>
  } else {
    return <pre>{JSON.stringify(credentials, null, '  ')}</pre>
  }
}
render(<CredentialPreview/>)

Please wait...

usePasswordCredential()

Return the password credential, if any, associated with the currently logged-in user.

Signatures:

usePasswordCredential() => {
error?:ApolloError
loading:boolean
passwordCredential?:PasswordCredential
}

Preview

function PasswordPreview () {
  const { loading, passwordCredential } = usePasswordCredential()
  if (loading) {
    return <div>Please wait...</div>
  } else if (!passwordCredential) {
    return <div>You have not added a password to this account</div>
  } else {
    return <pre>{JSON.stringify(passwordCredential, null, '  ')}</pre>
  }
}

render(<PasswordPreview/>)

function PasswordPreview () {
  const { loading, passwordCredential } = usePasswordCredential()
  if (loading) {
    return <div>Please wait...</div>
  } else if (!passwordCredential) {
    return <div>You have not added a password to this account</div>
  } else {
    return <pre>{JSON.stringify(passwordCredential, null, '  ')}</pre>
  }
}
render(<PasswordPreview/>)

Please wait...

useOauthCredentials()

Return all Oauth credentials that are associated with the currently logged-in user.

Signatures:

useOauthCredentials() => {
error?:ApolloError
loading:boolean
oauthCredentials?:OauthCredential[]
}

Preview

function OauthPreview () {
  const { loading, oauthCredentials } = useOauthCredentials()
  if (loading) {
    return <div>Please wait...</div>
  } else {
    return <pre>{JSON.stringify(oauthCredentials, null, '  ')}</pre>
  }
}

render(<OauthPreview/>)

function OauthPreview () {
  const { loading, oauthCredentials } = useOauthCredentials()
  if (loading) {
    return <div>Please wait...</div>
  } else {
    return <pre>{JSON.stringify(oauthCredentials, null, '  ')}</pre>
  }
}
render(<OauthPreview/>)

Please wait...

useTotpCredential()

Return the TOTP credential, if any, that is associated with the currently logged-in user.

Signatures:

useTotpCredential() => {
error?:ApolloError
loading:boolean
totpCredential?:TotpCredential
}

Preview

function TotpPreview () {
  const { loading, totpCredential } = useTotpCredential()
  if (loading) {
    return <div>Please wait...</div>
  } else if (!totpCredential) {
    return <div>You have not enabled TOTP</div>
  } else {
    return <pre>{JSON.stringify(credentials, null, '  ')}</pre>
  }
}

render(<TotpPreview/>)

function TotpPreview () {
  const { loading, totpCredential } = useTotpCredential()
  if (loading) {
    return <div>Please wait...</div>
  } else if (!totpCredential) {
    return <div>You have not enabled TOTP</div>
  } else {
    return <pre>{JSON.stringify(credentials, null, '  ')}</pre>
  }
}
render(<TotpPreview/>)

Please wait...

useProfilePhotos()

Return all profile photos from all Oauth credentials associated with the currently logged-in user.

Signatures:

useProfilePhotos() => {
error?:ApolloError
loading:boolean
photos?:string[]
}

Preview

function PhotoPreview () {
  const { loading, photos } = useProfilePhotos()
  if (loading) {
    return <div>Please wait...</div>
  } else {
    return <ul>{photos.map((photo, i) =>
      <li key={i}>
         <img src={photo} style={{ width: "64px", height: "64px" }}/>
      </li>
    )}</ul>
  }
}

render(<PhotoPreview/>)

function PhotoPreview () {
  const { loading, photos } = useProfilePhotos()
  if (loading) {
    return <div>Please wait...</div>
  } else {
    return <ul>{photos.map((photo, i) =>
      <li key={i}>
         <img src={photo} style={{ width: "64px", height: "64px" }}/>
      </li>
    )}</ul>
  }
}
render(<PhotoPreview/>)

Please wait...

useLogout()

Apollo mutation hook for logging out.

In many cases, you can use <LogoutButton> instead of using this hook directly.

Signatures:

useLogout() => [(options: MutationFunctionOptions<TData, TVariables>) => Promise<ExecutionResult<TData>>, {
success:boolean
}]

Preview

function LogoutPreview () {
  const [submit, { success }] = useLogout()
  if (success) {
    return <div>You have been logged out</div>
  }

  return <button
    className="btn btn-primary"
    onClick={(e) => {
      e.preventDefault()
      submit()
    }}
  >
   Logout
  </button>
}

render(<LogoutPreview/>)

function LogoutPreview () {
  const [submit, { success }] = useLogout()
  if (success) {
    return <div>You have been logged out</div>
  }
  return <button
    className="btn btn-primary"
    onClick={(e) => {
      e.preventDefault()
      submit()
    }}
  >
   Logout
  </button>
}
render(<LogoutPreview/>)

useResetPassword()

Apollo Mutation hook for resetting a user's password via a reset token delivered via email.

You should usually use <ResetPasswordForm> rather than calling this hook directly.

Signatures:

useResetPassword(options: ResetPasswordMutationOptions) => [submitWrapper, {
success:boolean
}]

useChangePassword()

Apollo Mutation hook for changing the user's password.

You should usually use <ChangePasswordForm> rather than calling this hook directly.

Signatures:

useChangePassword(options: ChangePwMutationOptions) => [submitWrapper, {
success:boolean
}]

useRequestPasswordResetEmail()

Apollo Mutation hook for requesting a password reset email.

You should usually use <RequestPasswordResetForm> rather than calling this hook directly.

Signatures:

useRequestPasswordResetEmail(options: RequestPwResetEmailMutationOptions) => [submitWrapper, {
success:boolean
}]

useEmailVerifier()

Apollo Mutation hook for marking an email address as verified, using an email verification token that was delivered to the user's email address.

You should generally use the <EmailVerifier> component rather than calling this hook directly.

Signatures:

useEmailVerifier() => [(options: MutationFunctionOptions<TData, TVariables>) => Promise<ExecutionResult<TData>>, {
success:boolean
}]

useSendVerificationEmail()

Apollo Mutation hook for requesting a verification email.

The functionality exposed by this hook is also available via the <UserAccountSettings> component.

Signatures:

useSendVerificationEmail(email: string) => [(options: MutationFunctionOptions<TData, TVariables>) => Promise<ExecutionResult<TData>>, {
success:boolean
}]

useReauthToken()

Obtain the reauthentication token provided by <ReauthenticateGuard>.

This token can be sent to your application backend in order to guard sensitive actions, by proving that the user's password was entered within some recent period of time.

See the <ReauthenticateGuard> documentation for an example of how to use this hook.

Signatures:

useReauthToken() => string

useCachedReauthToken()

Return a cached reauthentication token, if one exists, which has the given contents and is no older than maxAge.

You should usually use <ReauthenticateGuard> instead of using this hook directly. <ReauthenticateGuard> will check for a cached token before prompting the user for their password.

Signatures:

useCachedReauthToken(contents: string | object, maxAge: undefined | string) => null | string

useReauthenticate()

Apollo Mutation hook for obtaining a reauthentication token by submitting the user's password.

You should usually use <ReauthenticateGuard> instead of using this hook directly.

Signatures:

useReauthenticate(contentsArg: string | object) => [submitWrapper, MutationResult<{
__typename?:'Mutation'
} & {
signReauthenticationToken?:Maybe<{
__typename?:'ReauthTokenPayload'
} & {}>
}>]

isPasswordCredential()

Type guard function to check if a credential is a password credential

Signatures:

isPasswordCredential(c: Credential) => c is PasswordCredential

isOauthCredential()

Type guard function to check if a credential is an Oauth credential

Signatures:

isOauthCredential(c: Credential) => c is OauthCredential

isTotpCredential()

Type guard function to check if a credential is a TOTP credential

Signatures:

isTotpCredential(c: Credential) => c is TotpCredential

AuthTokenData

Definition

{

error?:ApolloError

id?:string

The id of the user to whom this token pertains

loading:boolean

userJwt?:string

A JWT, signed with the application's secret key, which authenticates the bearer as the user with the id contained in the token.

}

ClientType

Definition

ApolloClient<NormalizedCacheObject> | ApolloClient<object>

UsermaticProps

Definition

{

appId:string

The ID of the Usermatic Application.

children:ReactNode

The React components within which Usermatic will be used. (Typically your entire application).

components?:Components

Provide custom display components to use when rendering Usermatic components. See "Customizing Usermatic" for more information

showDiagnostics?:boolean

If true, insert Usermatic diagnostics into your application. Defaults to false.

uri?:string

The URI of the Usermatic API endpoint. For development use only.

useBootstrapClasses?:boolean

If true, add bootstrap class names to Usermatic components. Use this if your application uses bootstrap. Defaults to true.

useUmClasses?:boolean

If true, add class names begining with the um- prefix to Usermatic HTML elements, so that you can style Usermatic with your own CSS. Defaults to false.

}

classNamesArg

Definition

Parameters<typeofclassNames>[unknown]

AddPasswordFormProps

Definition

BaseAddPasswordFormProps & {

emailInput:ReactNode

The text input for the email address, as rendered by <EmailAddressInput> or <InputComponent>

}

AddPasswordFormType

Definition

React.FC<AddPasswordFormProps>

AddTotpFormType

Definition

React.FC<{

error:ReactNode

The error message, if any, as rendered via <ErrorMessageComponent>.

loading:ReactNode

The message displayed while waiting for asynchronous actions (e.g. form submission) to complete, as rendered by <LoadingMessageComponent>

qrCode:ReactNode

An <img> element using a dataURI to display the QR code containing the TOTP secret key.

success:boolean

Set to true if TOTP setup has been completed successfully.

textCode:ReactNode

The text version of the TOTP secret key, for manual entry

totpTokenForm:ReactNode

The form in which the user must enter a TOTP code to confirm successful setup of their authenticator app.

AlertComponentType

Definition

React.FC<{

children:ReactNode

role:'success' | 'info' | 'warning' | 'error'

BaseAddPasswordFormProps

Definition

{

error:ReactNode

The error message, if any, as rendered via <ErrorMessageComponent>.

formProps:FormProps

Properties which must be passed into a <form> element.

newPasswordInput:ReactNode

The input for the new password, as rendered via <PasswordInput> or <InputComponent>

passwordScore:ReactNode

The password score display, as rendered via <PasswordScoreComponent>

submitButton:ReactNode

The submit button, as rendered via <Button>

}

ButtonName

Exact name of button. Used to identify specific uses of <Button> throughout usermatic so that special-cased styles can be applied, either by the default Button component or by one supplied by the user.

Definition

ButtonProps

Definition

Omit<ButtonHTMLAttributes<HTMLButtonElement> & {

disabled?:boolean

name:ButtonName

role:ButtonRole

}, 'className'>

ButtonRole

Semantic role of button. Used by the default Button component to choose the button style.

Definition

'submit' | 'secondary' | 'cancel' | 'dismiss' | 'danger'

ButtonType

Definition

React.FC<ButtonProps>

ChangePasswordFormComponentProps

Definition

BaseAddPasswordFormProps & {

oldPasswordInput:ReactNode

The text input for the email address, as rendered by <PasswordInput> or <InputComponent>

}

ChangePasswordFormType

Definition

React.FC<ChangePasswordFormComponentProps>

Components

Definition

Partial<DefiniteComponents>

ConciseError

Definition

{

appErrorCode?:string

code:string

message:string

}

CreateAccountFormType

CreateAccountFormType controls the layout of the account creation form.

Definition

React.FC<{

createAccountButton:ReactNode

The button that submits the form and creates the account, as rendered via <Button>

emailInput:ReactNode

The text input for the email address, as rendered by <EmailAddressInput> or <InputComponent>

error:ReactNode

The error message, if any, as rendered via <ErrorMessageComponent>.

formProps:FormProps

Properties which must be passed into a <form> element.

passwordInput:ReactNode

The text input for the password, as rendered by <PasswordInput> or <InputComponent>

passwordScore:ReactNode

The password score display, as rendered via <PasswordScoreComponent>

stayLoggedInInput:ReactNode

A checkbox as rendered by <CheckboxComponent>

CredentialListType

Definition

React.FC<{

credentials:ReactNode

error:ReactNode

The error message, if any, as rendered via <ErrorMessageComponent>.

loading:ReactNode

The message displayed while waiting for asynchronous actions (e.g. form submission) to complete, as rendered by <LoadingMessageComponent>

DefiniteComponents

Definition

{

AddPasswordFormComponent:AddPasswordFormType

Component for rendering the new password form used by <ChangePasswordForm> when it is used to add a password to an account that doesn't have one.

AddTotpFormComponent:AddTotpFormType

Component used by <AddTotpForm> for rendering a QR code, and verifying the authenticator app setup via code entry.

AlertComponent:AlertComponentType

Component for rendering alert messages.

Button:ButtonType

Button component.

ChangePasswordFormComponent:ChangePasswordFormType

Component for rendering the old/new password form used by <ChangePasswordForm>

CheckboxComponent:InputComponentType

Default component for rendering checkboxes in forms.

CreateAccountFormComponent:CreateAccountFormType

Component used by <CreateAccountForm> to render the form and its inputs.

CreateAccountSuccessComponent:LoginSuccessType

Component displayed after successful account creation

EmailAddressInput:InputComponentType

Component for rendering the email address input in <LoginForm> and <AccountCreationForm>. Uses the InputComponent component by default.

EmailStatusComponent:EmailStatusType

Component used by <UserAccountSettings> for displaying a user's email and its verification status, including a button for re-sending the verification email.

EmailVerificationComponent:EmailVerificationType

Component used by <EmailVerifier> when users are verifying their email via a link sent to that email address.

ErrorCaseComponent:ErrorCaseType

Component used to render specialized error messages for given application error codes.

ErrorMessageComponent:ErrorMessageType

Component used to render error messages.

FacebookButton:SocialButtonType

Component to render a facebook login button.

ForgotPasswordFormComponent:ForgotPasswordFormType

Component for rendering the form show by <LoginForm> * after user clicks 'forgot password'

GithubButton:SocialButtonType

Component to render a github login button.

GoogleButton:SocialButtonType

Component to render a google login button.

InputComponent:InputComponentType

Default component for rendering text inputs in forms.

LoadingMessageComponent:LoadingMessageType

Component to display when waiting for an asynchronous action to complete.

LoginMethodsComponent:LoginMethodsType

Component used by <UserAccountSettings> for displaying a user's login methods (e.g. password, oauth providers, etc), as well as allowing them to change their password, remove Oauth providers, etc.

LoginSuccessComponent:LoginSuccessType

Component displayed after successful login

MFAFormComponent:MFAFormType

Component used by <LoginForm> for rendering the MFA stage of the login process, including entry of a TOTP code and possible entry of a recovery code.

ModalComponent:ModalType

Component for rendering Modal dialogs.

PasswordFormComponent:PasswordFormType

Component for rendering the email/password entry form used by <LoginForm>

PasswordInput:InputComponentType

Component for rendering the password input in <LoginForm> and <AccountCreationForm>. Uses the InputComponent component by default.

PasswordScoreComponent:PasswordScoreType

Component used to display the strength of a prospective password to the user. It is used by <AccountCreationForm>, <ChangePasswordForm>, <ResetPasswordForm>, and any other components where a new password is entered.

PersonalDetailComponent:PersonalDetailType

Component used by <UserAccountSettings> for displaying a user's personal details.

PostRecoveryCodeFormComponent:PostRecoveryCodeType

Component renderd by <LoginForm> after successful entry of the a recovery code, which allows them to optionally disable MFA.

ReauthFormComponent:ReauthFormType

Component to render the re-authorization form used by <ReauthenticateGuard>, to obtain a user's password before sensitive actions are performed.

RecoveryCodeDisplayComponent:RecoveryCodeDisplayType

Component used to display new recovery codes to the user, after they are created. Used by <GenRecoveryCodesForm>

RecoveryCodeInputComponent:InputComponentType

Component for rendering the text input for 2FA recovery codes.

RecoveryCodeRegenerationPromptComponent:RecoveryCodeRegenerationPromptType

Component used by <GenRecoveryCodesForm> to warn the user that their pre-existing codes will be invalidated, and confirming that they wish to proceed and generate new codes.

ResetPasswordFormComponent:ResetPasswordFormType

Component for rendering the new password form used by <ResetPasswordForm> when resetting a password via a password-reset link delivered via email.

SecurityInfoComponent:SecurityInfoType

Component used by <UserAccountSettings> for displaying a user's 2FA settings, including recovery code generation.

SocialButtonsComponent:SocialButtonComponentType

Component for rendering social login buttons, used by <LoginForm> and <CreateAccountForm>

StayLoggedInInput:InputComponentType

Component for rendering the "stay logged in" checkbox in <LoginForm> and <AccountCreationForm>. Uses the CheckboxComponent component by default.

TotpInputComponent:InputComponentType

Component for rendering the text input for TOTP codes.

UserAccountSettingsComponent:UserAccountSettingsType

Component used by <UserAccountSettings> to render the user's profile page and various account settings components.

}

EmailInfoType

Definition

React.FC<{

changePassword:ReactNode

credential:PasswordCredential

EmailStatusType

Definition

React.FC<{

email:string

emailIsVerified:boolean

resendSuccess:boolean

resendVerificationEmailButton:ReactNode

EmailVerificationType

Definition

React.FC<{

error:ReactNode

The error message, if any, as rendered via <ErrorMessageComponent>.

redirectUri?:string

The URI that the user will be redirected to now that verification is complete. It is passed here so that it can be displayed, e.g. "If you are not redirected, click here"

success:boolean

Set to true if verification has completed successfully.

ErrorCaseType

Definition

React.FC<{

children:ReactNode

code?:string

ErrorMessageType

Definition

React.FC<{

errors:ConciseError[]

ForgotPasswordFormType

Definition

React.FC<{

cancelButton:ReactNode

The cancel button, as rendered via <Button>

emailInput:ReactNode

The text input for the email address, as rendered by <EmailAddressInput> or <InputComponent>

error:ReactNode

The error message, if any, as rendered via <ErrorMessageComponent>.

formProps:FormProps

Properties which must be passed into a <form> element.

submitButton:ReactNode

The submit button, as rendered via <Button>

successMessage:ReactNode

The message displayed to the user after success.

FormProps

Definition

React.ComponentPropsWithoutRef<'form'>

InputComponentProps

Definition

InputHTMLAttributes<HTMLInputElement> & {

labelText?:ReactNode

}

InputComponentType

Definition

React.FC<InputComponentProps>

LoadingMessageType

Definition

React.FC<{}>

LoginMethodsType

Definition

React.FC<{

changePassword:ReactNode

oauthCredentials:{

credential:OauthCredential

removeButton:ReactNode

}[]

passwordCredential?:PasswordCredential

LoginSuccessType

Definition

React.FC<{

appName:string

The application name, as configured in the Usermatic dashboard.

email:string

The email of the newly-created user.

MFAFormType

Definition

React.FC<{

enterRecoveryModeButton:ReactNode

The button which allows the user to switch from TOTP code entry to recovery code entry, as rendered by <Button>

error:ReactNode

The error message, if any, as rendered via <ErrorMessageComponent>.

exitRecoveryModeButton:ReactNode

The button which allows the user to switch back to TOTP code entry from recovery code entry, as rendered by <Button>

loading:ReactNode

The message displayed while waiting for asynchronous actions (e.g. form submission) to complete, as rendered by <LoadingMessageComponent>

recoveryCodeInput:ReactNode

The text input for entering a recovery code, as rendered by <RecoveryCodeInputComponent>

recoveryMode:boolean

Set to true if the user has clicked "i need to enter a recovery code"

totpTokenInput:ReactNode

The text input for entering a TOTP code, as rendered by <TotpInputComponent>

ModalType

Definition

React.FC<{

children:ReactNode

The body of the modal.

footer?:ReactNode

Text and other elements to display in the Modal's footer area.

isOpen:boolean

If true, the modal will be rendered and the rest of the page content obscured.

onRequestClose:() => void

Must be called whenever the user attempts to close the modal, e.g. by clicking outside of it, hitting esc, etc.

title:ReactNode

Text and other elements to display in the Modal's title area.

OauthInfoType

Definition

React.FC<{

credentials:{

credential:OauthCredential

removeButton:ReactNode

}[]

PasswordFormType

Definition

React.FC<{

emailInput:ReactNode

The text input for the email address, as rendered by <EmailAddressInput> or <InputComponent>

error:ReactNode

The error message, if any, as rendered via <ErrorMessageComponent>.

forgotPasswordButton:ReactNode

The "forgot password?" button as rendered by <Button>

formProps:FormProps

Properties which must be passed into a <form> element.

passwordInput:ReactNode

The text input for the password, as rendered by <PasswordInput> or <InputComponent>

signinButton:ReactNode

The signin/submit button as rendered by <Button>

stayLoggedInInput:ReactNode

A checkbox as rendered by <CheckboxComponent>

PasswordScoreType

Definition

React.FC<{

minPasswordStrength:number

The minimum requried score set in the Usermatic application settings. If passwordScore.score is less than minPasswordStrength, the password will be rejected by Usermatic.

passwordScore:PwScoreRecord

The current score of the password.

PersonalDetailType

Definition

React.FC<{

email:string

emailVerificationStatus:ReactNode

error:ReactNode

The error message, if any, as rendered via <ErrorMessageComponent>.

loading:ReactNode

The message displayed while waiting for asynchronous actions (e.g. form submission) to complete, as rendered by <LoadingMessageComponent>

name:{

family?:string

full?:string

given?:string

}

PostRecoveryCodeType

Definition

React.FC<{

dismissButton:ReactNode

Button which dismisses the post recovery code flow.

dontResetButton:ReactNode

The button which, when pressed, dismisses the dialog without disabling MFA.

error:ReactNode

The error message, if any, as rendered via <ErrorMessageComponent>.

mfaDisabled:boolean

True if the user chose to disable MFA after entering their recovery code.

recoveryCodesRemaining?:number

The number of valid recovery codes that the user still has.

resetButton:ReactNode

The button which, when pressed, disables MFA.

PwScoreRecord

ZXCVBNResult is defined at https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/zxcvbn/index.d.ts

Definition

ZXCVBNResult

ReauthFormType

Definition

React.FC<{

cancelButton:ReactNode

The cancel button, as rendered via <Button>

error:ReactNode

The error message, if any, as rendered via <ErrorMessageComponent>.

formProps:FormProps

Properties which must be passed into a <form> element.

passwordInput:ReactNode

The text input for the password, as rendered by <PasswordInput> or <InputComponent>

prompt:ReactNode

The prompt which will be provided to the user, e.g. "Please enter your password to perform action X".

submitButton:ReactNode

The submit button, as rendered via <Button>

RecoveryCodeDisplayType

Definition

React.FC<{

codes?:string[]

error:ReactNode

The error message, if any, as rendered via <ErrorMessageComponent>.

RecoveryCodeRegenerationPromptType

Definition

React.FC<{

confirmButton:ReactNode

The button which, when pressed, confirms regeneration of recovery codes and invalidation of all previously generated codes.

ResetPasswordFormComponentProps

Definition

BaseAddPasswordFormProps & {

loginAfterResetInput:ReactNode

A checkbox as rendered by <CheckboxComponent>

stayLoggedInInput:ReactNode

A checkbox as rendered by <CheckboxComponent>

successMessage:ReactNode

The message displayed to the user after success.

}

ResetPasswordFormType

Definition

React.FC<ResetPasswordFormComponentProps>

SecurityInfoType

Definition

React.FC<{

codeCount:number

configureTotp:ReactNode

generateNewRecoveryCodes:ReactNode

totpEnabled:boolean

SocialButtonComponentType

Definition

React.FC<{

facebookButton:ReactNode

githubButton:ReactNode

googleButton:ReactNode

SocialButtonType

Definition

React.FC<{

onClick:ButtonProps['onClick']

TotpInfoType

Definition

React.FC<{

credential:TotpCredential

UserAccountSettingsType

A component of UserAccountSettingsType is used to customize the user's account settings display.

Definition

React.FC<{

accountSecurity:ReactNode

The account security section, as rendered by <SecurityInfoComponent>

loginMethods:ReactNode

The login methods section, as rendered by <LoginMethodsComponent>

personalDetails:ReactNode

The personal details section, as rendered by <PersonalDetailComponent>

Preview

const UserAccountSettingsComponent = ({
  personalDetails,
  loginMethods,
  accountSecurity
}) => {
  return <div>
    {personalDetails}
    <hr/>
    {loginMethods}
    <hr/>
    {accountSecurity}
  </div>
}

render(<UserAccountSettings components={{
 UserAccountSettingsComponent
}}/>)

const UserAccountSettingsComponent = ({
  personalDetails,
  loginMethods,
  accountSecurity
}) => {
  return <div>
    {personalDetails}
    <hr/>
    {loginMethods}
    <hr/>
    {accountSecurity}
  </div>
}
render(<UserAccountSettings components={{
 UserAccountSettingsComponent
}}/>)

Personal Details

Please wait...

Name

AccountCreationFormProps

Definition

{

components?:Components

Display components for AccountCreationForm. See 'Customizing Usermatic' for more information.

idPrefix?:string

loginAfterCreation?:boolean

onLogin?:() => void

onLogin() is called after the user is successfully logged in.

showPasswordScore?:boolean

If set, the strength of the user's password is displayed and automatically updated as they modify it.

}

ChildWindow

Definition

{

close:() => void

open:(url: string) => void

}

LoginFormProps

Definition

{

components?:Components

Display components for LoginForm. See 'Customizing Usermatic' for more information.

idPrefix?:string

onChangeMode?:(mode: LoginMode) => void

onChangeMode is called when the LoginForm switches "modes". For instance, if the user clicks the "Forgot Password" button, onChangeMode will be called with the 'forgotpw' argument.

onLogin?:() => void

onLogin is called after the user successfully logs in.

}

LoginMode

Definition

'login' | 'forgotpw' | 'totp'

LoginSubmitArgs

Definition

typeofloginInitialValues

OauthLoginProps

Definition

LoginFormProps & {

children:ReactNode

}

LogoType

Definition

React.FC<{

color?:string

size?:string | number

ModalOptions

Definition

{

initialState?:boolean

resetOnClose?:boolean

}

ChangePasswordFormProps

Definition

{

components?:Components

Display components for ChangePasswordForm. See 'Customizing Usermatic' for more information.

idPrefix?:string

onSuccess?:() => void

Function to be called after password is successfully changed.

}

PasswordScoreProps

Definition

{

components?:Components

Custom display components. See 'Customizing Usermatic' for more information.

debounceMs?:number

Debounce time in ms for both the password and username. Defaults to 300ms.

password?:string

The user's prospective password.

username?:string

The user's email address.

}

PwScoreRecord

Definition

ZXCVBNResult

RequestPasswordResetFormProps

Definition

{

components?:Components

Custom display components. See 'Customizing Usermatic' for more information.

idPrefix?:string

onCancel?:() => void

Called when the user clicks the cancel button instead of submitting their email.

}

ResetPasswordFormProps

Definition

{

components?:Components

Display components for ResetPasswordForm. See 'Customizing Usermatic' for more information.

exposeLoginAfterReset?:boolean

If true, render the "login after reset" option. If the user checks this box, it has the same effect as if the loginAfterReset property had been set to true.

idPrefix?:string

loginAfterReset?:boolean

onLogin?:() => void

Called after the user is successfully logged in (which will only happen if the loginAfterReset property is true.)

redirectAfterReset?:boolean

If true, the user will be automatically redirected to the URI that has been configured the Usermatic application settings after resetting their password.

token?:string

}

UseOrChangeVariables

Definition

ChangePwMutationVariables & AddPasswordMutationVariables

ReauthenticateGuardProps

Definition

{

children:ReactNode

components?:Components

Display components for ReauthenticateGuard. See 'Customizing Usermatic' for more information.

maxTokenAge?:string

maxTokenAge limits how long a token will be cached in your application. The format is anything supported by https://github.com/vercel/ms, e.g. "5m" or "60s" or "2h", etc.

See "Reauthenticating before Sensitive actions" for more information.

onClose?:() => void

onClose() can be used to hook ReauthenticateGuard up to a modal. It is calledl when the user clicks the "Close" button displayed by <ReauthenticateGuard>

prompt?:ReactNode

A prompt to diplay above the password input.

tokenContents:string | object

The rule to bear in mind is that anyone who knows the password can obtain a reauthenticationToken token with any conceivable tokenContents, simply by asking the Usermatic backend.

See "Reauthenticating before Sensitive actions" for more information.

}

ConciseError

Definition

{

appErrorCode?:string

code:string

message:string

}

ErrorMessageCaseProps

Definition

{

children:ReactNode

code:string

components?:Components

}

ErrorProps

Definition

{

children?:ReactElement[] | ReactElement

components?:Components

error:ApolloError | undefined

}

CsrfData

Definition

{

csrfToken?:string

}

CacheEntry

Definition

{

iat:number

token:string

}

CreateRecoveryCodesOptions

Definition

MutationHookOptions<CreateRecoveryCodesMutation, CreateRecoveryCodesMutationVariables>

AddTotpMutationOptions

Definition

MutationHookOptions<AddTotpMutation, AddTotpMutationVariables>

GetTotpKeyOptions

Definition

QueryHookOptions<GetTotpKeyQuery, GetTotpKeyQueryVariables>

Credential

Definition

PasswordCredential | OauthCredential | TotpCredential

OauthCredential

Definition

{

email?:string

id:string

photoURL?:string

provider:string

providerID:string

type:string

}

PasswordCredential

Definition

{

email:string

emailIsVerified:boolean

id:string

type:string

}

TotpCredential

Definition

{

id:string

type:string

}