Branding

You can customize the look and feel of AuthKit via the Branding section of the WorkOS Dashboard.

The brand editor allows you to:

The AuthKit preview will update in real-time as you make changes and accurately reflect the available authentication methods, giving you a clear picture of the authentication experience with AuthKit.

WorkOS supports custom domains for both email and ACS URLs. For for information, see the custom domains documentation.

AuthKit supports both light and dark mode; each brand configuration option is split across both so that they can be configured independently. You can enforce a specific appearance, or allow the user’s OS system settings to determine which to use.

The corner radius applied to UI elements can also be configured; a lower value will result in a more formal aesthetic while a higher value has a more rounded, playful feel.

You can upload custom brand assets to display in AuthKit, transactional emails, and the Admin Portal.

There are three types of assets you can upload:

Either the logo or the logo icon can be displayed in AuthKit. To select which to use, click the logo in the AuthKit preview after uploading both assets.

You can control four colors across light and dark mode:

Other colors used in the UI, like the focus outline, hover styles, or borders, are created automatically based on the four colors you provide, ensuring a consistent look and feel.

The page title and alternate action link text on AuthKit pages can be customized to fit your brand’s tone of voice. They can be edited directly inside the AuthKit preview pane.

Start by selecting the page you want to edit. Then, click on the text you want to change from the preview pane.

AuthKit pages can optionally display a link to your app’s privacy policy and/or terms-of-service. The link will then appear below the authentication form.

AuthKit also allows you to choose whether or not first name and last names are required when signing up. To toggle either of these, select the Page Settings panel and update the respective field.

The layout for AuthKit pages can be customized to fit your brand’s needs. You can choose between a centered, one-column layout, or a two-column layout using custom HTML and CSS for the secondary column.

Split page layouts allow you to add a secondary panel on AuthKit pages that can be customized with HTML and CSS. This can be used to display marketing content or decorative elements on the page.

To enable this feature, select the page you want to customize. Then, select the Split layout option under Page Settings. The secondary panel can be displayed to the left or right of the primary panel, and optionally hidden on mobile devices.

Click on the secondary column from the preview pane. This will open a dialog where you can enter your HTML and CSS.

Any HTML and CSS entered into the custom code dialog will only be applied to the secondary column of the selected page. This allows you a high level of flexibility without impacting content elsewhere on the page.

For security purposes, all code input is sanitized and stripped of any potentially harmful elements. This means that you can’t use JavaScript or any other dynamic content in your HTML. This includes script, iframe, form, and object elements – as well as inline event handlers for any elements.

For example, the following code will be sanitized from this:

<h1 onclick="onClick()">Welcome to SuperApp</h1>
<script>
  const onClick = () => alert('Warning!');
</script>

…to this:

<h1>Welcome to SuperApp</h1>

HTML style elements will also be removed to prevent overriding any content outside of the secondary panel. All custom CSS should be entered into the CSS editor.

CSS selectors will be scoped to the secondary column via CSS nesting. For compatibility with older browsers, we use a light transform step to convert the nested CSS to a flat structure.

For example, the following CSS will be transformed from this:

h1 {
  color: var(--primary-color);
}

…to this:

:where([data-hak-custom-html]) h1 {
  color: var(--primary-color);
}