Ory Elements

Ory Elements is a component library designed to simplify building authentication user interfaces (login, registration, account settings, verification, recovery, and consent) for Ory.

Key features include:

• Reduced Development Time: Pre-built components for complex flows like multi-factor authentication (MFA) and account recovery.
• Customization: Components are themeable and replaceable.
• Ecosystem Compatibility: Built for the React ecosystem, including support for Next.js.
• Dynamic Adaptation: The UI automatically adapts to your Ory identity schema and flow configurations.

The Next.js App Router example implements all self-service user flows supported by Ory, including:

• Login: /auth/login
• Registration: /auth/registration
• Recovery: /auth/recovery
• Verification: /auth/verification
• Settings: /settings
• Logout

The example uses the Next.js app/ directory structure to organize authentication and settings flows:

• app/auth: Contains page files for all user authentication flows (Login, Registration, etc.).
• app/settings: Contains the page file for the user settings flow.
• app: Contains the root layout and the main landing page.

You can replace specific sub-components within an Ory Element by using the components prop. This allows you to inject custom UI while maintaining the flow logic. You can also use the useOryFlow hook inside your custom components to access the current flowType.

import { Registration } from "@ory/elements-react/theme"

function CustomCardHeader() {
  const { flowType } = useOryFlow()
  return <div>My Custom {flowType} Card header</div>
}

export default async function RegistrationPage({ searchParams }: PageProps) {
  const flow = await getOrCreateRegistrationFlow(searchParams)

  return (
    <Registration
      flow={flow}
      config={oryConfiguration}
      components={{
        Card: {
          CardHeader: CustomCardHeader,
        },
      }}
    />
  )
}

You can customize the appearance of Ory Elements by overriding CSS variables in your global stylesheet. The variables are organized into a hierarchy:

1. Primitives: Base colors (e.g., --ui-100, --ui-500, --ui-black).
2. Brand: Brand-specific colors mapped from primitives (e.g., --brand-500).
3. Interface: Semantic groups for backgrounds, borders, and foregrounds (e.g., --interface-background-brand-primary).
4. Specific Elements: Component-level overrides (e.g., --button-primary-background-default).

Example of overriding primitives and brand colors:

:root {
  /* primitives */
  --ui-100: #f1f5f9;
  --ui-500: #64748b;
  --ui-900: #0f172a;
  /* ... */

  /* brand */
  --brand-100: var(--ui-100);
  --brand-500: var(--ui-500);
  --brand-900: var(--ui-900);
  /* ... */
}

The @ory/nextjs package includes middleware for both App Router and Pages Router. This middleware enables local development and preview environments to work correctly with Ory's cookie security model, eliminating the need for Ory Tunnel during development.

Refer to the following examples for implementation details:

• App Router middleware example
• Page Router middleware example

To ensure the translation system works correctly, follow these rules:

• Source of Truth: Always add or modify keys in en.json. Never modify keys directly in individual language files.
• Placeholders: The system automatically preserves placeholders (e.g., {provider}, {clientName}, {contactSupportEmail}) and date formats (e.g., {used_at, date, long}).
• HTML Tags: HTML tags (e.g., <a>, <strong>) are preserved during translation.
• Key Order: The script maintains the key order defined in en.json. Extra keys found in language files are removed during updates.
• Fallback: If a translation fails, the script adds an English fallback and logs the occurrence.

You can send analytics events from Ory Elements authentication flows to a Matomo instance by utilizing the onSuccess, onValidationError, and onError event handler callbacks available on every Ory Elements flow component.

To implement this, create a wrapper component that intercepts these callbacks and calls a tracking function (e.g., using Matomo's HTTP Tracking API via fetch). This allows you to track user behavior across flows like Login, Registration, and Recovery without adding heavy dependencies.

// Example of wrapping a flow component to add analytics
import OryFlowWithMatomo from "@/components/ory-flow-with-matomo"

// In your Next.js page component:
return <OryFlowWithMatomo flowType="login" flow={flow} />

To ensure components render correctly, you must import the default CSS file in your application. This should be included on all pages that utilize Ory Elements components.

import "@ory/elements-react/theme/styles.css"

The project uses API Extractor to ensure API contract stability. If your changes intentionally alter the API and you need to update the generated API reports, run the api-extractor-refresh command. Inspect the changes carefully before committing them to your PR.

pnpm exec nx api-extractor-refresh @ory/elements-react