New Ory Agent Security is now live! Claim your complimentary test drive. Get Started!

Skip to main content

React Router Quickstart

This quickstart guides you through setting up Ory Elements in a React Router application in framework mode. It works with React Router 7.9 and later and React Router 8.

info

The code used in the following quickstart is available in the React Router example GitHub repository

Prerequisites​

  1. Create a new React Router application using your preferred package manager:

    npx create-react-router@latest

  2. Install the @ory/elements-react and @ory/react-router packages in your application.

    npm install @ory/elements-react @ory/react-router

  3. Add the configuration for Ory Elements. Create a new file named app/ory.config.ts and add the following code:

    app/ory.config.ts

    See full code on GitHub

  4. Add the proxy route. It serves the Ory APIs on your application's origin during local development and on preview deployments, so the browser sends Ory's cookies to your application. Create a new file named app/routes/ory-proxy.ts and add the following code:

    app/routes/ory-proxy.ts

    See full code on GitHub

    Set trustedOrigins to the origins your local development server and preview deployments serve. An entry is an origin without a path, such as http://localhost:5173. To match several origins, use * in the host as a glob, such as https://my-app-*-my-team.vercel.app for the Vercel preview deployments of the project "my-app" of the team "my-team". Each * matches one or more letters, digits, or hyphens and never a dot. createOryProxyHandler throws at startup when trustedOrigins is unset, empty, or has an invalid entry. The proxy serves only the origins in trustedOrigins. For any other origin, the flow helpers use ORY_SDK_URL and log a warning. See Trusted origins.

    The proxy is for local development and preview deployments. It isn't supported in production: through the proxy, Ory sees every request coming from your server's address instead of your users' browsers. In production, use a custom domain on Ory Network, or serve Ory on your own domain with the Ory Enterprise License (OEL), on the same site as your application, and set ORY_SDK_URL to it.

  5. Create the route modules in app/routes, one for each self-service flow, one for the error page, and one for the home page. Replace the home.tsx that the template created:

    • login.tsx
    • registration.tsx
    • recovery.tsx
    • verification.tsx
    • settings.tsx
    • error.tsx
    • home.tsx

    Each flow loader fetches the flow, which carries the URL the browser uses to reach Ory. Each component renders the respective Ory Elements component with the flow. The settings loader also returns getOryBaseUrl(request) for SessionProvider. The headers export keeps flow pages out of shared caches: they contain CSRF tokens and URLs resolved for the request, so a shared cache must never store them.

    app/routes/login.tsx

    See full code on GitHub

  6. Register the routes and the proxy routes in app/routes.ts:

    app/routes.ts

    See full code on GitHub

  7. Set the ORY_SDK_URL environment variable to your Ory project URL in your .env file:

    .env

    See full code on GitHub

    You can find your Ory Network project URL in the Get started section of the Ory Console.

    Set ORY_PROJECT_API_TOKEN to an API key of your project so that links in emails, social sign-in, and SAML return to your application. Put it in .env.local, and make sure .gitignore covers .env*.local, so the key stays out of commits:

    .env.local
    ORY_PROJECT_API_TOKEN=ory_pat_...

    For preview deployments, create a dedicated API key and set it only in the preview environment.

  8. Run the application and create your first user by navigating to http://localhost:5173/auth/registration.

    npm run dev

    After registration, you can sign in at /auth/login. The other self-service flows are at the following URLs:

    • Recovery: /auth/recovery
    • Verification: /auth/verification
    • Settings: /settings

Which URL the browser uses to reach Ory​

When Ory is on the same site as the app, the URL is ORY_SDK_URL. Otherwise it is the request's origin when the proxy route is registered and the origin is in trustedOrigins, and ORY_SDK_URL if not. The flow helpers and getOryBaseUrl(request) from @ory/react-router use the same URL. No environment name such as NODE_ENV changes the result, so a preview deployment, which runs a production build, resolves like local development.

The proxy is registered for the whole server process when React Router loads the proxy route module. A process has one proxy configuration. In the development server, the registration stays after you remove the proxy routes until you restart the server.

Troubleshooting​

When the browser would call Ory on another site, Ory's session cookies don't reach the app, and login or session checks fail. @ory/react-router then logs a warning once in the server log:

WarningFix
The Ory proxy handled a request for <origin>, which is not in trustedOriginsIn local development or a preview deployment, add the origin to trustedOrigins in app/routes/ory-proxy.ts. In production, use a custom domain on the app's site.
The app (<origin>) and Ory (<url>) are on different sitesThe proxy isn't registered. Create app/routes/ory-proxy.ts and register its routes in app/routes.ts.
The request's Host header is not a valid originConfigure the reverse proxy in front of the app to forward the Host header the browser sent.

Next steps​

Customize the components, add your own styles, and integrate them into your application. See Theming to customize the look and feel of the components.