> ## Documentation Index
> Fetch the complete documentation index at: https://docs.authsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom branding

> Customize the look and feel of the pre-built UI to match your app's brand.

For a more seamless user experience you can heavily customize the pre-built UI branding by providing your own theme.
Visit the [branding tab in the Authsignal Portal](https://portal.authsignal.com/organisations/tenants/customizations) to get started.

If you require a more bespoke branding experience then try out our [UI customization tool](https://portal.authsignal.com/organisations/tenants/customizations/advanced).
This tool allows you to change a wide range of design tokens (colors, borders, alignment, text) to tweak the look and feel of the entire pre-built UI.

<Frame caption="The advanced customization tool provides a preview of various pre-built UI screens.">
  <img src="https://mintcdn.com/authsignal-23/8bvDamO56aVu-Ay2/images/docs/customizations/colors.png?fit=max&auto=format&n=8bvDamO56aVu-Ay2&q=85&s=5ac2e36d11c74733b0c7b1ea4dd241b8" alt="" width="2613" height="1486" data-path="images/docs/customizations/colors.png" />
</Frame>

## Custom templates

To override the pre-built UI's layout you can provide a custom template.

Custom templates, at a bare minimum, must contain the following structure.

```html theme={null}
<html>
  <head>
    <authsignal-head></authsignal-head>
  </head>
  <body>
    <authsignal-widget></authsignal-widget>
  </body>
</html>
```

<Warning>
  The `authsignal-head` and `authsignal-widget` tags are required for the pre-built UI to function
  correctly.
</Warning>

To update your tenant's custom template, you can send the following payload to the [Update Theme endpoint](/api-reference/management-api/update-theme).

```json theme={null}
{
  "template": "<html><head><authsignal-head></authsignal-head></head><body><authsignal-widget></authsignal-widget></body></html>"
}
```

<Warning>The `template` string must have escaped special characters.</Warning>

## Adding custom HTML/CSS

Using a custom template allows you to add your own HTML/CSS.

For example, if you wanted to show an image next to the pre-built UI you could use the following template:

```html theme={null}
<html>
  <head>
    <authsignal-head></authsignal-head>
    <style>
      .wrapper {
        display: grid;
        grid-template-columns: 1fr 1fr;
      }
      .image {
        display: block;
        width: 100%;
        height: 100%;
        z-index: 10;
        background-size: cover;
        background-position: center;
        background-repeat: no-repeat;
        background-image: url(https:\/\/images.unsplash.com\/photo-1682685795579-37e731bfefab?q=80&w=1374&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDF8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D);
      }
    </style>
  </head>
  <body>
    <div class="wrapper">
      <authsignal-widget></authsignal-widget>
      <div class="image"></div>
    </div>
  </body>
</html>
```

Which would result in:

<img src="https://mintcdn.com/authsignal-23/8bvDamO56aVu-Ay2/images/docs/customizations/custom-template.png?fit=max&auto=format&n=8bvDamO56aVu-Ay2&q=85&s=b229faa45b88d5e4527099f71de63609" alt="" width="2403" height="1467" data-path="images/docs/customizations/custom-template.png" />

## Adding custom JavaScript

To add custom JavaScript to your custom template you can use the following structure:

```html theme={null}
<html>
  <head>
    <authsignal-head></authsignal-head>
    <script src="https://cdn.some-javascript.min.js"></script>
  </head>
  <body>
    <authsignal-widget></authsignal-widget>
  </body>
</html>
```
