Appearance and sections
An embedded component sits inside your product, so it imposes as little as possible: no page background of its own, no font of its own, and no colors beyond the ones it is given.
There are two places to set that, and they rank.
- A variant, built in the admin console and named in
init(). Administrators change it without a deployment. themeandsectionspassed toinit(), which win wherever the two overlap.
How the layers rank
From lowest to highest: built-in defaults, the stored variant, then init() options. A layer
only overrides what it sets, so a variant that sets colors and an init()
call that hides one section combine.
Where a variant lives
A variant is stored on your workspace, not in anyone's browser. It reaches a person in a different browser, or one who has cleared their profile, exactly as it reaches everyone else.
The embed reads it when init() runs. The read needs no token, so that it never waits on your
tokenProvider. That makes a variant's contents (its colors and section choices) readable by
anyone who knows your tenant, workspace, and variant id. Keep secrets out of it. If the read
fails or takes too long, the elements render with the built-in defaults instead of breaking
your page.
Prefer the variant. Pass values in code only for something your application genuinely decides at runtime, such as a color mode that follows the person's own setting, or a palette that differs per customer in a multi-tenant product.
Color mode
theme.mode picks the light or dark base. Nothing is inferred from the host page, because a
page can be dark without the person having asked for dark.
init({
// ...
theme: { mode: window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light" },
});
Each mode has its own colors in the variant, so one variant covers both.
Colors and font
theme.style sets the element's own tokens directly. Colors group by mode; the font applies
to both.
init({
// ...
theme: {
style: {
fontUrl: "https://cdn.example.com/Brand.woff2",
light: { primaryColor: "#1E40AF", surfaceColor: "#FFFFFF" },
dark: { primaryColor: "#7AA2F7", surfaceColor: "#161C2B" },
},
},
});
| Token | Applies to |
|---|---|
primaryColor | Buttons, links, and selected states. |
backgroundColor | The surface behind the element's cards. |
surfaceColor | The cards themselves. |
fontUrl | A font file (WOFF, WOFF2, or TTF), loaded by the element. |
Every field is optional, and absent means unset rather than default: a color you leave out keeps the base theme's. Colors must be 3, 4, 6, or 8 digit hex. Anything else is ignored.
The element's own font family is inherit, so with no fontUrl it takes whatever your page
uses and needs no configuration at all.
Tenant branding
theme.branding defaults to "none": the tenant's configured branding is not applied, and no
request for it is made. Set it to "tenant" to opt in, and the element adopts the primary
color, page background, and header color that tenant configured for the hosted pages
SecureAuth provides.
init({
// ...
theme: { branding: "tenant" },
});
Two things to know. Under mode: "dark" nothing is fetched or applied, because that branding
is authored against the light theme and carries no dark variant. And theme.style outranks
it, so a page that sets both gets its own values wherever they overlap.
Use "tenant" when the element should look like the rest of that tenant's SecureAuth
experience. Use theme.style, or a variant, when it should look like your product.
Sections
A variant decides which sections each pane renders. The same thing can be passed in code, keyed by tag and then by section id:
init({
// ...
sections: {
"sa-self-service-security": { sessions: false },
"sa-self-service-profile": { header: false },
},
});
Absent means visible, so configuring nothing hides nothing, and an id no element declares is
ignored. /embed/v1/manifest.json lists the sections each element actually has.
A toggle applies to that pane wherever it renders: on its own, or inside the composite.
The composite's own four sections are its tabs. Hiding one drops it from the navigation and makes its route unreachable, and the composite falls back to the first tab still showing. That is navigation only: the same pane mounted directly still renders.
Hiding a section also stops the requests behind it, but only when nothing else visible needs
the same data. Hiding sessions drops the MFA request immediately, while the sessions request
itself continues as long as the identity header is still showing a last sign-in row.
Hiding a section is presentation, not authorization. It removes the UI and suppresses requests, but the underlying API stays reachable with that token. See Authentication and tokens.