Skip to main content

Bring your UI

Logto allows you to bring your own UI to completely replace the built-in sign-in experience interface, in addition to the pre-built UI customization options. This feature enables you to upload a zip file containing your custom UI assets (HTML, CSS, JavaScript, images, etc.), have it hosted on Logto Cloud servers, and use it as the sign-in experience for your tenant users.

note

This feature requires your custom UI to be Single Page Application (SPA) compatible, and it's recommended to always use a production build for optimal performance.

Explore the custom UI feature in Logto Console​

Get started with official project​

The fastest way to initiate a custom sign-in UI is to clone the Logto experience project. This is the built-in Logto Sign-in Experience UI that covers all features and Logto's best practices. You can customize it to fit your needs.

After checking out the code, just simply run the following command to build the project:

pnpm install && pnpm build
note

The whole Logto project is a pnpm monorepo, If you want to run the experience package standalone (without pnpm), replace workspace: dependencies in package.json with specific version numbers (like ^1.0.0).

After the build completes, you'll find all compiled assets in the dist directory. Then create a ZIP archive of the dist directory - this archive will be used for uploading to Logto Cloud later.

Custom UI assets requirements​

Before uploading your custom UI assets, make sure they meet the following requirements:

  • The upload assets should be packed as a single zip file.
  • The zip file should contain an index.html file in the root directory.
  • The zip file should not exceed 20MB in size.
  • The zip file should not contain any file that exceeds 10MB in size.
  • The zip file should not contain more than 200 files in total.

Upload your custom UI assets​

note

Proceed with caution when using this feature in production, since it will immediately affect your users' sign-in experience.

  1. Navigate to Console > Sign-in experience > Brandin > Bring your UI.
  2. Click to select or drag and drop your zip file created in the previous step, and the upload process will start automatically.
  3. Once the upload is complete, save the changes, and your custom UI will be served immediately.
  4. The "Sign-in preview" window will be disabled when you use your custom sign-in UI. However, you can still click the "Live preview" button to test your custom sign-in page in a new opened browser tab.

Develop your custom UI​

Interact with Experience API​

Your custom UI needs to interact with Experience API to perform various actions such as sign-in, sign-up, password reset, binding social accounts, enabling MFA, and more. To better understand the user flows and implementation details, we recommend checking out our Experience API design RFC which provides comprehensive technical specifications and examples.

You also need to access other Sign-in Experience configurations, such as branding colors, company logo, favicon, password policy, localized language phrases, even custom CSS, through the sign-in Experience API endpoint.

Sample projects​

We provide a collection of sample projects to help you understand and start implementing custom UI quickly. Please check out the Logto Experience project GitHub repo for details.

Moreover, we'll continue working on providing more simplified and scenario-based sample projects to cover the most common use cases. Stay tuned for our future updates!

Local development and debugging​

For local development and debugging, we provide the Logto Tunnel CLI tool to:

  • Proxy Experience API requests from your local machine to Logto Cloud endpoint.
  • Test your custom UI implementation locally.

This allows users to test and debug custom UI locally before uploading to Logto Cloud.

Please refer to Debug and test your custom UI locally for more details.

Upload your custom UI assets using the CLI​

In addition to uploading through the Console, you can also use the Logto CLI to upload custom UI assets. This is particularly useful for automated deployment workflows.

Please refer to Upload custom UI assets using CLI for more details.

Restore to Logto built-in sign-in experience​

If you wish to restore to Logto's built-in sign-in experience, simply click the delete button on the Bring your UI card. After saving the changes, the sign-in experience UI will be reverted back to Logto's default.

RFCS: Experience API

 Experience samples Bring your own sign-in UI to Logto Cloud