> For the complete documentation index, see [llms.txt](https://docs.startrail.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.startrail.io/startrail-sdk-js/login-providers/whitelabeling.md).

# Whitelabeling/Customizing

Brand the SDK's login modal and wallet UI from config — colours, logo, layout, wording

## Customize UI

* Everything is driven by the `customUi` config value — no CSS work in your app.
* **v2.3.0+:** `customUi.theme` styles the SDK's own login modal (colours, light/dark mode, radii, logo placement, button style) and is forwarded to the wallet UI, so both match.
* Here is the mapping between config values and the corresponding UI.

<figure><img src="https://3244648189-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOu6aN3RW264zdJsOQMJ2%2Fuploads%2Fgit-blob-0274c2a4efbb5d0ee64cb7be860b498702d377fc%2Fsdk-login-modal-brand-acme-light-dark.webp?alt=media" alt="The login modal branded for Acme Gallery, light and dark"><figcaption><p>Acme Gallery: accent, inline circular logo, left alignment, custom font and wording — all from <code>customUi</code>.</p></figcaption></figure>

{% hint style="success" %}
Design it visually: the [playground's brand studio](https://sdk.startrail.io/#brand) has presets and every option below with a live **Preview** of the real modal, and prints the config to paste into your app.
{% endhint %}

<figure><img src="https://3244648189-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOu6aN3RW264zdJsOQMJ2%2Fuploads%2Fgit-blob-53a725e22fe4e561c9283449a7d393ecad699bd8%2Fsdk-playground-brand.webp?alt=media" alt="The playground&#x27;s brand studio: presets, every customUi.theme option, wording and a per-site CSS override"><figcaption><p>The brand studio at <a href="https://sdk.startrail.io/#brand">sdk.startrail.io</a>.</p></figcaption></figure>

<figure><img src="https://3244648189-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOu6aN3RW264zdJsOQMJ2%2Fuploads%2FayD3EVtJnR98Im91ZwBB%2FTorusWhitelabelConfigInStartrailSdk.drawio%20(3).png?alt=media&amp;token=6fc180f8-019b-401a-851c-2e493d0ff147" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
`Guideline for the logoUrl` and`logoWhiteUrl`

* Logo must be hosted. If it is difficult, please contact us.

  e.g.: <https://static-files.startrail.io/startrail-black-logo.png>
* A square logo works best: the modal shows it in a rounded frame by default (`theme.logoShape` can make it a circle, a square, or drop the frame for a wide wordmark with `'plain'`).
* Logo must be either in PNG or JPG/JPEG format. Some E-Mail clients do not support certain formats such as SVG.
  {% endhint %}

## Properties

All the properties listed below are *optional*.

## CustomUI

<table><thead><tr><th width="184">Parameters</th><th>Example</th><th>Description</th></tr></thead><tbody><tr><td>logoUrl</td><td><code>string</code></td><td>App logo to be shown on the light background (light theme)</td></tr><tr><td>logoWhiteUrl</td><td><code>string</code></td><td>App logo to be shown on the dark background (dark theme)</td></tr><tr><td>serviceName</td><td><code>string</code></td><td>Applied to all service name in Startrail-sdk-js</td></tr><tr><td>contactUrl</td><td><code>string</code></td><td>Applied to the contact email in signup Email</td></tr><tr><td>verificationEmailTitle</td><td><code>string</code></td><td>Applied to the title of the verification email when you select email_password</td></tr><tr><td>theme</td><td><a href="#theme-v2.3.0"><code>Theme</code></a></td><td><strong>(v2.3.0+)</strong> Colours, light/dark mode, font, radii and layout of the login modal. See <a href="#theme-v2.3.0"><em>Theme</em></a> below.</td></tr><tr><td>words</td><td><pre class="language-json"><code class="lang-json">{
  en: CustomWords
  ja: CustomWords
}
</code></pre></td><td>either <code>en</code> or <code>ja</code> can be used. The value of each is defined in <a href="#customwords"><em>CustomWords</em></a></td></tr></tbody></table>

## Theme (v2.3.0+)

All properties are optional; one accent colour is enough to start.

<table><thead><tr><th width="176">Parameter</th><th width="150">Default</th><th>Description</th></tr></thead><tbody><tr><td>mode</td><td><code>'light'</code></td><td><code>'dark'</code>, or <code>'auto'</code> to follow the visitor's <code>prefers-color-scheme</code>.</td></tr><tr><td>accent</td><td>near-black</td><td>Primary button, links and focus rings (hex recommended). The text colour on it is picked by WCAG luminance — <code>#ffcc00</code> gets dark text, <code>#4a156c</code> gets white — and hover/pressed tints are derived.</td></tr><tr><td>accentDark</td><td>derived</td><td>Accent in dark mode. Defaults to <code>accent</code>; a near-black accent inverts to a light neutral instead of vanishing on the dark card.</td></tr><tr><td>fontFamily</td><td>Inter / Noto Sans JP</td><td>CSS <code>font-family</code> stack for the whole modal, with system fallbacks.</td></tr><tr><td>borderRadius</td><td><code>20</code></td><td>Dialog corner radius in px (0–40); buttons and inputs follow it, capped at 12.</td></tr><tr><td>controlRadius</td><td>follows <code>borderRadius</code></td><td>Radius of buttons and inputs in px (0–24), or <code>'50%'</code> for pill-shaped controls.</td></tr><tr><td>logoPlacement</td><td><code>'top'</code></td><td><code>'top'</code> centres the logo above the title, <code>'inline'</code> puts it beside the title on one row, <code>'none'</code> hides it.</td></tr><tr><td>logoSize</td><td><code>48</code></td><td>Size of the logo box in px (24–120); the artwork and corner radius scale with it.</td></tr><tr><td>logoShape</td><td><code>'rounded'</code></td><td><code>'rounded'</code>, <code>'circle'</code>, <code>'square'</code>, or <code>'plain'</code> for the artwork alone at <code>logoSize</code> height — for wordmarks and wide logos.</td></tr><tr><td>buttonStyle</td><td><code>'outline'</code></td><td>Provider buttons: <code>'outline'</code> (border), <code>'filled'</code> (tinted surface, no border) or <code>'accent'</code> (solid brand colour with contrasting text).</td></tr><tr><td>align</td><td><code>'center'</code></td><td>Alignment of the title, subtitle, logo and footer links; <code>'left'</code> reads well with <code>logoPlacement: 'inline'</code>.</td></tr></tbody></table>

{% tabs %}
{% tab title="Brand colour + dark mode" %}

```typescript
const sdk = new Startrail({
  customUi: {
    serviceName: 'PORT',
    theme: { mode: 'auto', accent: '#4a156c', accentDark: '#b8a5c4' },
  },
})
```

<figure><img src="https://3244648189-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOu6aN3RW264zdJsOQMJ2%2Fuploads%2Fgit-blob-188f449f373a7981b49cd1263ca8e8233c71da0d%2Fsdk-login-modal-brand-port-light-dark.webp?alt=media" alt="PORT theme"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Layout options" %}

```typescript
const sdk = new Startrail({
  customUi: {
    serviceName: 'Acme Gallery',
    logoUrl: 'https://acme.example/logo.png',
    logoWhiteUrl: 'https://acme.example/logo-white.png',
    theme: {
      mode: 'auto',
      accent: '#ff5a1f',
      fontFamily: "'Avenir Next', 'Segoe UI', system-ui, sans-serif",
      borderRadius: 10,
      controlRadius: '50%',     // pill-shaped buttons and inputs
      logoPlacement: 'inline',  // logo beside the title
      logoSize: 40,
      logoShape: 'circle',
      buttonStyle: 'filled',
      align: 'left',
    },
    words: {
      en: { modal: { title: 'Welcome to Acme', subtitle: 'Sign in to manage your collection', privacyPolicy: 'Privacy notice' } },
      ja: { modal: { title: 'Acme へようこそ', subtitle: 'ログインしてコレクションを管理' } },
    },
  },
})
```

{% endtab %}

{% tab title="Per-site CSS override" %}

```css
/* CSS custom properties on the modal container win over customUi.theme —
   for one site that needs a different accent than the shared config. */
#torus-social-login-modal-container {
  --startrail-modal-accent: #0c70b8;
  --startrail-modal-on-accent: #ffffff;
  --startrail-modal-accent-ring: rgba(12, 112, 184, 0.22);
  --startrail-modal-font: 'Inter', sans-serif;
  --startrail-modal-radius: 16px;
  --startrail-modal-control-radius: 8px;
  --startrail-modal-z-index: 9999;
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
`theme.mode` and `theme.accent` are also forwarded to the wallet iframe (its `mode` / `theme.primary`), so sign-confirmation and wallet screens match the modal — only when you configure them.
{% endhint %}

***CustomWords*** is an object consisting of the following optional attributes. Each of the are explained subsequently.

```json5
{
    emailAuthPopup:EmailAuthPopup,
    modal:WalletModal,
    signPopup:SignPopup,
    embed:Embed
}
```

### EmailAuthPopup

<table><thead><tr><th>Parameters</th><th>Example</th><th data-hidden>Example</th></tr></thead><tbody><tr><td>titleLogin</td><td></td><td><code>string</code></td></tr><tr><td>titleSignup</td><td></td><td><code>string</code></td></tr></tbody></table>

### WalletModal

<table><thead><tr><th width="260">Parameters</th><th width="380">Default</th><th data-hidden>Type</th></tr></thead><tbody><tr><td>continueLogin</td><td>"Continue with existing {verifier}" (wallet UI)</td><td><code>string</code></td></tr><tr><td>title <strong>(v2.3.0+)</strong></td><td>"Login" / "Sign up" per <code>authAction</code> ("ログイン" / "登録")</td><td><code>string</code></td></tr><tr><td>subtitle <strong>(v2.3.0+)</strong></td><td>"to continue to <em>serviceName</em>"</td><td><code>string</code></td></tr><tr><td>termsConditions</td><td>"Terms of Service" — label of the footer link</td><td><code>string</code></td></tr><tr><td>termsConditionsLinkUrl</td><td>Startrail's terms</td><td><code>string</code></td></tr><tr><td>privacyPolicy <strong>(v2.3.0+)</strong></td><td>"Privacy Policy" — label of the footer link</td><td><code>string</code></td></tr><tr><td>privacyPolicyLinkUrl</td><td>Startrail's privacy policy</td><td><code>string</code></td></tr></tbody></table>

{% hint style="info" %}
Provider buttons ("Continue with Google" / "Googleで続ける") and status messages are localised automatically from `lang`; only the title, subtitle and legal labels are yours to change.
{% endhint %}

### SignPopup

<table><thead><tr><th>Parameters</th><th>Example</th><th data-hidden>Type</th><th data-hidden>Mandatory<select><option value="0b53396cce3a44bbb3fc6b9705449928" label="Optional" color="blue"></option></select></th></tr></thead><tbody><tr><td>title</td><td></td><td><code>string</code></td><td><span data-option="0b53396cce3a44bbb3fc6b9705449928">Optional</span></td></tr><tr><td>requestFrom</td><td></td><td><code>string</code></td><td><span data-option="0b53396cce3a44bbb3fc6b9705449928">Optional</span></td></tr><tr><td>confirm</td><td></td><td><code>string</code></td><td><span data-option="0b53396cce3a44bbb3fc6b9705449928">Optional</span></td></tr><tr><td>cancel</td><td></td><td><code>string</code></td><td><span data-option="0b53396cce3a44bbb3fc6b9705449928">Optional</span></td></tr></tbody></table>

### Embed (Continue Alert Popup)

<table><thead><tr><th>Parameters</th><th>Example</th><th data-hidden>Type</th><th data-hidden>Mandatory<select><option value="b57b13ab0ccd46c690fb88143436a318" label="Optional" color="blue"></option></select></th></tr></thead><tbody><tr><td>continue</td><td></td><td><code>string</code></td><td><span data-option="b57b13ab0ccd46c690fb88143436a318">Optional</span></td></tr><tr><td>actionRequired</td><td></td><td><code>string</code></td><td><span data-option="b57b13ab0ccd46c690fb88143436a318">Optional</span></td></tr><tr><td>pendingAction</td><td></td><td><code>string</code></td><td><span data-option="b57b13ab0ccd46c690fb88143436a318">Optional</span></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.startrail.io/startrail-sdk-js/login-providers/whitelabeling.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.