> 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/startrail-powered-by-web3auth-torus.md).

# Interface

UI of the SDK

## Login modal (v2.3.0)

When `loginProvider` offers a choice — several providers, or none (= all of them) — `login()` opens the SDK's **own login modal**. It is rendered by the SDK in a Shadow DOM, so your page's CSS never affects it and its CSS never leaks out, and it is fully white-label (see [Whitelabeling](/startrail-sdk-js/login-providers/whitelabeling.md)).

<figure><img src="https://3244648189-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOu6aN3RW264zdJsOQMJ2%2Fuploads%2Fgit-blob-c6fec297915325ef4941efd5b24168c6db8a89fb%2Fsdk-login-modal-default-light-dark.webp?alt=media" alt="The default login modal in light and dark mode"><figcaption><p>Brand-neutral default — light and dark mode.</p></figcaption></figure>

### When does the modal open?

| Configuration                                               | What `login()` does                                                                                                                                |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `loginProvider: ['google']` (one social provider)           | Signs in with that provider directly — **no modal**                                                                                                |
| `loginProvider: ['email_passwordless']` + valid `loginHint` | Sends the one-time code to that email — **no modal** (v2.2.0+)                                                                                     |
| `loginProvider: ['email_passwordless']` without `loginHint` | Modal with just the email field                                                                                                                    |
| `loginProvider: ['google', 'apple', 'line']`                | Modal limited to those providers, in that order                                                                                                    |
| `loginProvider` not set                                     | Modal with all providers                                                                                                                           |
| Any of the above, with a session the wallet can restore     | The session is resumed — the modal shows *"Checking for an existing session…"* only if it had to open in the meantime, and closes itself (v2.3.0+) |

{% hint style="info" %}
`withModal` is **deprecated and has no effect** since v2.3.0 — the table above is the whole rule. To make a signed-in user pick a *different* account, call `login({ loginProvider: [...], forceLogin: true })`.
{% endhint %}

### What the user sees

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><strong>Provider picker</strong></td><td>One button per provider ("Continue with Google", …) and, for <code>email_passwordless</code>, an inline email field with validation.</td><td><a href="https://3244648189-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOu6aN3RW264zdJsOQMJ2%2Fuploads%2Fgit-blob-2f59785b2d2df177a56c2031d113a79f7c49a3bd%2Fsdk-login-modal-email-validation-and-hint.webp?alt=media">sdk-login-modal-email-validation-and-hint.webp</a></td></tr><tr><td><strong>Waiting · cancelled · error</strong></td><td>"Waiting for Google…" while the provider window is open; a friendly notice if the user closes it; an inline error with retry if the wallet fails.</td><td><a href="https://3244648189-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOu6aN3RW264zdJsOQMJ2%2Fuploads%2Fgit-blob-72b4e2cc0d016dbcf98e51f89d0048531e1cb9a2%2Fsdk-login-modal-flow-waiting-cancelled-error.webp?alt=media">sdk-login-modal-flow-waiting-cancelled-error.webp</a></td></tr><tr><td><strong>Phones</strong></td><td>A bottom sheet under 480 px with safe-area padding; the whole flow works with a keyboard and screen readers.</td><td><a href="https://3244648189-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOu6aN3RW264zdJsOQMJ2%2Fuploads%2Fgit-blob-38c879d1d9e54104ec5a6cd95622a93d52c557af%2Fsdk-login-modal-mobile-light-dark.webp?alt=media">sdk-login-modal-mobile-light-dark.webp</a></td></tr><tr><td><strong>Japanese</strong></td><td>Every label, hint and state is localised from <code>lang</code>; <code>customUi.words</code> overrides the title, subtitle and legal labels.</td><td><a href="https://3244648189-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOu6aN3RW264zdJsOQMJ2%2Fuploads%2Fgit-blob-aac98371f2227c3b6f42d5a0bc61398e46f600aa%2Fsdk-login-modal-japanese.webp?alt=media">sdk-login-modal-japanese.webp</a></td></tr></tbody></table>

* The order of the provider buttons follows the order of your `loginProvider` array.
* The footer links to the Terms of Service and Privacy Policy — the labels and URLs can be yours (`customUi.words[lang].modal`).
* Closing the modal (Escape, the × button) makes `login()` resolve with `false` — never an exception.

{% hint style="success" %}
See it with your own colours: the [playground's brand studio](https://sdk.startrail.io/#brand) previews the real modal and generates the `customUi` config.
{% endhint %}

### Email Passwordless without a modal (v2.2.0+)

Email Passwordless previously always opened the selection modal (the user still had to type their email there). From **v2.2.0**, if you configure a single `email_passwordless` provider **and** supply the user's email as `loginHint`, the SDK starts the passwordless flow directly and skips the modal entirely.

<table><thead><tr><th width="260">Configuration</th><th>Result</th></tr></thead><tbody><tr><td><code>loginProvider: ['email_passwordless']</code> + valid <code>loginHint</code></td><td>Passwordless flow starts directly — <strong>no modal</strong></td></tr><tr><td><code>loginProvider: ['email_passwordless']</code> without <code>loginHint</code> (or invalid email)</td><td>Modal opens as before</td></tr><tr><td>Multiple providers (even with <code>loginHint</code>)</td><td>Modal opens — the user picks a provider</td></tr></tbody></table>

{% code title="Email Passwordless — no modal" overflow="wrap" %}

```typescript
// Skip the modal: single email_passwordless provider + a known email
const sdk = new Startrail({
  env: 'staging',
  loginProvider: ['email_passwordless'],
  loginHint: 'user@example.com',
})
await sdk.login()

// loginHint can also be passed per-call on login()
await sdk.login({ loginProvider: ['email_passwordless'], loginHint: 'user@example.com' })
```

{% endcode %}

{% hint style="info" %}
`loginHint` is read from the constructor config or from the `login()` override. When you pass it to `login()` together with a single `email_passwordless` provider, the modal is skipped for that call.
{% endhint %}

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><h3>Signature Modal</h3></td><td><img src="https://3244648189-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOu6aN3RW264zdJsOQMJ2%2Fuploads%2FR4xEZkZH1iFPjbWZ9mYA%2FScreenshot%202022-03-08%20at%2019.28.20.png?alt=media&amp;token=f730f115-53bb-41aa-a2b6-42da3d7d9292" alt=""></td><td></td></tr><tr><td></td><td>When it's used ?</td><td><ul><li><code>sdk.signMessage is called</code></li></ul><p>As default, <code>signMessage() is executed with an arbitrary string prepended to the message under the hood of Web3Auth library.</code></p><p><code>This enables skipping the signature modal popup and user consent process. The drawback of this is to require additional backend development. See more details.</code></p><p><a href="/startrail-sdk-js/authentication-integration.md">Required implementation on clients’ backend</a><br><br>Web3Auth</p><p><a href="https://docs.tor.us/wallet/api-reference/installation">Installation | Documentation</a></p></td></tr></tbody></table>

### White-label samples

<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="The modal themed for PORT"><figcaption><p><code>theme: { accent: '#4a156c', accentDark: '#b8a5c4', controlRadius: '50%', buttonStyle: 'filled' }</code></p></figcaption></figure>

<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 modal themed for Acme Gallery"><figcaption><p><code>theme: { accent: '#ff5a1f', logoPlacement: 'inline', logoShape: 'circle', align: 'left', fontFamily: 'Avenir Next' }</code> + custom wording</p></figcaption></figure>

{% content-ref url="/pages/ArKSzO1J1eosVczBoEWW" %}
[Whitelabeling/Customizing](/startrail-sdk-js/login-providers/whitelabeling.md)
{% endcontent-ref %}


---

# 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/startrail-powered-by-web3auth-torus.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.