Skip to main content

Custom UI with Ory Elements

Ory Elements is a component library designed to make building login, registration, and account pages for Ory quick and easy. Ory Elements is modular and customizable, which means that you can use only the views you need and style them to match your implementation's design.

The UI created with Ory Elements changes dynamically to adapt to your Ory Network configuration. For example, the sign-up form changes to after you edit the Identity Schema without the need for any additional action. The same is true for other options available in Ory Network, such as social sign-in connections or passwordless login.

The three available examples provide a closer look at integrating Ory Elements with React, Preact, and Next.js TypeScript single-page applications (SPA). By following the instructions you will:

  • Get the example app code from the Ory Elements repository.
  • Run the application on your machine.
  • Use Ory CLI to connect the application running on your machine to your Ory Network project's APIs.
  • Have a closer look at the code that's behind the dynamic Ory Elements UI.

Prerequisites​

Before you start, make sure to:

Run the sample application​

Follow these steps to get the sample application code and run it on your machine:

  1. Clone the example and prepare the code to run it:

    git clone --depth 1 git@github.com:ory/elements.git
    cd elements
    npm run initialize
    npm run build:clean
    cd examples/react-spa

    Running the application outside the ory/elements repository:

    git clone --depth 1 git@github.com:ory/elements.git
    cp -r elements/examples/react-spa .
    cd react-spa
    npm i @ory/elements @ory/client @ory/elements-test

  2. Export environment variable:

    # Unix
    export VITE_ORY_SDK_URL=http://localhost:4000
    # Windows
    $Env:VITE_ORY_SDK_URL = "http://localhost:4000"

  3. Start the application locally:

    # Start the app on port 3000
    npm run dev -- --port 3000

  4. In a new terminal window, run Ory Tunnel (part of the Ory CLI) to connect the application to your Ory Network project:

    # Run Ory Tunnel to connect to Ory APIs.
    # To get your project slug, go to 'Access & APIs' in Ory Console
    # at https://console.ory.sh/

    ory tunnel http://localhost:3000 --project {project-slug} --dev

  5. In your browser, go to http://localhost:3000 to access the application. From there, you can try registering and signing-in using the Ory Elements-powered pages.

Closer look at the code​

With the application running, let's have a closer look at the code and the way the application integrates with Ory Elements and Ory SDK.

Ory SDK instance​

The sdk.ts file is responsible for creating a new instance of the Ory SDK. This instance is used to interact with Ory APIs.

src/sdk.ts

see full code on GitHub

Application entry point​

This is the main entry point for the application. This file contains routes and themes for other pages used by the app. The application is wrapped with Ory Elements using <ThemeProvider />. You can change the theme colors by passing in a Theme object to the themeOverrides property on the <ThemeProvider /> component.

src/main.tsx

see full code on GitHub

Landing page​

This file defines the landing page of the application. If you want to protect access to an app, set up authentication to secure this page. In this implementation, the Dashboard component checks if the user has a session. If the user doesn't have a session, they are redirected to the login page. Additionally, the logout URL is initialized, which allows for a functional Log out button.

src/Dashboard.tsx

see full code on GitHub

Login and registration pages​

The login.tsx and register.tsx pages contain components that interact with Ory APIs to allow registering accounts and performing the login flow.

These pages are dynamic and will show relevant fields based on your Ory Network project configuration. To see the pages change, edit your project's Identity Schema or try changing adjusting project settings and enable passwordless flows.

Registration​

The registration page, defined in the register.tsx file:

  1. Gets the registration flow (if it exists in the URL) or fallback to start the registration flow to get the flow data on page load.
  2. Submits the registration form data the user provides when they click the Submit button,
tip

To learn more about the self-service registration flow, read this document

src/Registration.tsx

see full code on GitHub

Login​

The login page, defined in the login.tsx file:

  1. Gets the login flow (if it exists in the URL) or falls back to start the registration flow to get the flow data on page load.
  2. Submits the login form data the user provides when they click the Submit button.
tip

To learn more about the self-service login flow, read this document

src/Login.tsx

see full code on GitHub

Settings page​

The settings.tsx file defines the page of the application where users can change their account settings. This page changes dynamically based on the configuration of the Ory Network project.

For example, if you enable passwordless flows, users see the option to register a new hardware key. If passwordless flows are disabled, the option to add hardware keys is not visible in the UI.

src/Settings.tsx

see full code on GitHub

Verification page​

The verification.tsx file defines the page of the application where users verify newly created accounts.

src/Verification.tsx

see full code on GitHub

Recovery page​

The recovery.tsx file defines the page displayed to user that try to recover their accounts after forgetting a password or losing access to a second authentication factor.

src/Recovery.tsx

see full code on GitHub

End-to-end tests​

The examples provided by Ory Elements contain end-to-end tests through the @ory/elements-test library which provides convenience functions to test the login, registration, recovery, verification, and settings flows. In these examples, the tests are located in the e2e folder and are based on the Playwright library.

To run the tests, execute the npm run test command inside the example directory.

Learn more​

To learn more about Ory Elements, contribute to the project, and integrate with your application, visit the project's repository.