Integrate SDK for React application

Mount, manage, and control Revolut ID authentication buttons in React applications.

React button component

Basic React component with button mounting:

import { useEffect, useRef, useState } from 'react'
import { RevolutIdLoader, ButtonClient, ButtonStyle } from '@revolut/revolut-id'

type Props = {
  buttonStyle: ButtonStyle
}

export function RevolutAuthButton({ buttonStyle }: Props) {
  const containerRef = useRef<HTMLDivElement>(null)
  const buttonClientRef = useRef<ButtonClient | null>(null)
  const [isLoading, setIsLoading] = useState(true)
  const [error, setError] = useState<string | null>(null)

  useEffect(() => {
    async function mountButton() {
      if (!containerRef.current) return

      try {
        const revolutId = await RevolutIdLoader({ mode: 'production' }) // mode is optional, defaults to 'production'; use 'sandbox' for testing

        const { mountButton } = revolutId.initialise({
          clientId: 'your-client-id',
          redirectUri: window.location.origin + '/auth/callback',
          scope: ['profile', 'email'],
          displayMode: 'popup', // Explicit popup mode
          onAuthSuccess: ({ code, codeVerifier }) => {
            // exchange code for user token on your BE side
          },
          onAuthFailure: (e) => {
            console.error('Authentication failed:', e.error)
          },
        })

        buttonClientRef.current = mountButton(
          containerRef.current,
          buttonStyle
        )
        setIsLoading(false)
      } catch (e) {
        setError('Failed to load revolut-id-sdk')
        setIsLoading(false)
      }
    }

    mountButton()

    // Cleanup on unmount
    return () => {
      if (buttonClientRef.current) {
        buttonClientRef.current.unmount()
      }
    }
  }, [buttonStyle])

  if (isLoading) return <div>Loading authentication...</div>
  if (error) return <div>Error: {error}</div>

  return <div ref={containerRef} />
}

import { useEffect, useRef, useState } from 'react'
import { RevolutIdLoader, ButtonClient, ButtonStyle } from '@revolut/revolut-id'

type Props = {
  buttonStyle: ButtonStyle
}

export function RevolutAuthButton({ buttonStyle }: Props) {
  const containerRef = useRef<HTMLDivElement>(null)
  const buttonClientRef = useRef<ButtonClient | null>(null)
  const [isLoading, setIsLoading] = useState(true)
  const [error, setError] = useState<string | null>(null)

  useEffect(() => {
    async function mountButton() {
      if (!containerRef.current) return

      try {
        const revolutId = await RevolutIdLoader({ mode: 'production' }) // mode is optional, defaults to 'production'; use 'sandbox' for testing

        const { mountButton } = revolutId.initialise({
          clientId: 'your-client-id',
          redirectUri: window.location.origin + '/auth/callback',
          scope: ['profile', 'email'],
          displayMode: 'popup', // Explicit popup mode
          onAuthSuccess: ({ code, codeVerifier }) => {
            // exchange code for user token on your BE side
          },
          onAuthFailure: (e) => {
            console.error('Authentication failed:', e.error)
          },
        })

        buttonClientRef.current = mountButton(
          containerRef.current,
          buttonStyle
        )
        setIsLoading(false)
      } catch (e) {
        setError('Failed to load revolut-id-sdk')
        setIsLoading(false)
      }
    }

    mountButton()

    // Cleanup on unmount
    return () => {
      if (buttonClientRef.current) {
        buttonClientRef.current.unmount()
      }
    }
  }, [buttonStyle])

  if (isLoading) return <div>Loading authentication...</div>
  if (error) return <div>Error: {error}</div>

  return <div ref={containerRef} />
}

API reference

The Revolut ID Web SDK provides the RevolutId interface, which is returned by RevolutIdLoader (NPM installation) or available in the global window scope via window.revolut.revolutId (CDN script).

export interface ButtonClient {
  mount: (container: HTMLElement, params?: ButtonStyle) => ButtonClient
  unmount: () => void
}

export interface RevolutId {
  initialise: (config: Config) => {
    mountButton: (container: HTMLElement, params?: ButtonStyle) => ButtonClient
  }

  processRedirectParams: () => SuccessResult | ErrorResult | null
}

export interface ButtonClient {
  mount: (container: HTMLElement, params?: ButtonStyle) => ButtonClient
  unmount: () => void
}

export interface RevolutId {
  initialise: (config: Config) => {
    mountButton: (container: HTMLElement, params?: ButtonStyle) => ButtonClient
  }

  processRedirectParams: () => SuccessResult | ErrorResult | null
}

Config - initialisation parameters (required)

Parameter	Type	Description	Required
`clientId`	`string`	Your Revolut application client ID	Yes
`redirectUri`	`string`	URI to redirect to after authentication	Yes
`scope`	`OpenIdScope[]`	Array of requested OpenID scopes (`openid` included by default)	Yes
`displayMode`	`popup \| redirect`	Authentication display mode	No (defaults to `redirect`)
`mode`	`production \| sandbox`	Environment mode	No (defaults to 'production')
`uiColorScheme`	`light \| dark \| system`	UI theme preference	No
`uiBackground`	`blue \| deep-blue \| green \| orange \| teal \| purple \| holo \| minimal`	Authentication page background	No
`countryCodes`	`string[]`	Array of allowed country codes	No
`locale`	`string`	Language/locale code	No
`onAuthSuccess`	`(result: SuccessResult) => void`	Success callback function	Yes (popup mode only)
`onAuthFailure`	`(result: ErrorResult) => void`	Error callback function	No (popup mode only)

For complete configuration documentation and advanced options, see Config API reference.

ButtonStyle - button styling parameters (optional)

Parameter	Type	Description	Default	Required
`kind`	`continue \| sign_in \| sign_up \| verify \| icon`	Button text and purpose	`sign_in`	No
`size`	`large \| small`	Button size	`large`	No
`variant`	`dark \| light \| light-outlined`	Visual style	`dark`	No
`radius`	`none \| default \| round`	Corner rounding	`default`	No

For complete button styling documentation and usage examples, see ButtonStyle API reference.

Environment setup

The environment you use must match your client environment configuration.

Use production mode with your production client ID for live applications
Use sandbox mode with your sandbox client ID for development and testing

See environment configuration for more details.

React integration best practices

Use useEffect cleanup: Always return cleanup functions from useEffect
Manage refs properly: Use useRef for DOM elements and button clients
Handle loading states: Show loading indicators while the SDK Initialises
Error boundaries: Wrap components in error boundaries to catch SDK failures
Memoize callbacks: Use useCallback for functions passed to useEffect dependencies
Custom hooks: Create reusable hooks for common authentication patterns
TypeScript: Use proper typing for better development experience

Next steps

Learn how to exchange code for user ID token - code exchange.

Integrate SDK for React application

React button component​

API reference​

Config - initialisation parameters (required)​

ButtonStyle - button styling parameters (optional)​

Next steps​

React button component

API reference

Config - initialisation parameters (required)

ButtonStyle - button styling parameters (optional)

Next steps