> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-docs-event-stream-action-templates.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize Style and Themes for iOS Universal Components

> Learn how to customize style and themes for Universal Components on iOS.

export const ReleaseStageNotice = ({feature, stage, plans, contact, terms}) => {
  const stageTextMap = {
    "beta": "Beta",
    "ea": "Early Access"
  };
  const stageText = stageTextMap[stage] || "a product release stage";
  const prsLink = "/docs/troubleshoot/product-lifecycle/product-release-stages";
  const linkify = (text, url) => {
    return <a href={url} target="_blank" rel="noreferrer" class="link">{text}</a>;
  };
  const includeDetails = (plans, contact, terms) => {
    const hasDetails = terms || plans || contact;
    if (!hasDetails) return null;
    return <span data-as="p">
            {plans && <>This feature is available for {linkify(`${plans} plans`, "https://auth0.com/pricing")}. </>}
            {contact && "To participate, contact " + contact + ". "}
            {terms && <>By using this feature, you agree to the applicable Free Trial terms in Okta's {linkify("Master Subscription Agreement", "https://www.okta.com/legal")}.</>}
        </span>;
  };
  return <Warning>
            <span data-as="p">
                <strong>The {feature} feature is in {linkify(stageText, prsLink)}.</strong>
            </span>

            {includeDetails(plans, contact, terms)}
        </Warning>;
};

<ReleaseStageNotice feature="Auth0 Universal Components" stage="beta" terms="true" contact="Auth0 Support" />

Auth0 [Universal Components for iOS](https://github.com/auth0/ui-components-ios) use a design token model. Visual properties such as colors, typography, spacing, corner radii, and component sizes are each expressed as a token that you can override without changes to your layouts.

Universal Components ship with a default Auth0 theme. You can provide your own theme to match your brand.

## How theming works

Universal Components for iOS use a SwiftUI `@Environment` property wrapper theme. Apply the `.auth0Theme(_:)` modifier to any SwiftUI view. Every child component renders the injected `Auth0Theme` automatically.

### Zero configuration

If you do not configure a theme, Universal Components for iOS render the Auth0 default theme. The following example displays the `MyAccountAuthMethodsView` component without any customization:

```swift wrap lines theme={null}
import SwiftUI
import Auth0UniversalComponents

struct ContentView: View {
    var body: some View {
        MyAccountAuthMethodsView()
    }
}
```

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  No additional setup is required to load the Auth0 default theme. Universal Components apply it automatically when no custom theme is provided.
</Callout>

### Override a subset of tokens

You can override specific tokens while Universal Components for iOS render every other token using the Auth0 default theme.

The following example overrides only the primary background and text colors:

```swift wrap lines theme={null}
import SwiftUI
import Auth0UniversalComponents

struct ContentView: View {
    var body: some View {
        MyAccountAuthMethodsView()
            .auth0Theme(
                Auth0Theme(
                    colors: DefaultAuth0ColorTokens(
                        background: DefaultAuth0BackgroundColorTokens(primary: Color("BrandBlue")),
                        text: DefaultAuth0TextColorTokens(onPrimary: .white)
                    )
                )
            )
    }
}
```

The same applies to typography, spacing, radius, and size tokens.

The following example overrides typography and button radius:

```swift wrap lines theme={null}
Auth0Theme(
    typography: DefaultAuth0TypographyTokens(
        body: Auth0TextStyle(
            font: .custom("Lato-Regular", size: 17),
            tracking: 0,
            lineSpacing: 7
        ),
        label: Auth0TextStyle(
            font: .custom("Lato-Medium", size: 16),
            tracking: 0.1,
            lineSpacing: 5
        )
    ),
    radius: DefaultAuth0RadiusTokens(button: 24)
)
```

### Configure a full brand theme

Provide your own branding theme that implements the three color category properties, then wire them into an `Auth0ColorTokens` container:

```swift wrap lines theme={null}
struct BrandBackground: Auth0BackgroundColorTokens {
    var primary: Color { Color("Background/Primary", bundle: .main) }
    var primarySubtle: Color { Color("Background/Primary", bundle: .main).opacity(0.35) }
    var inverse: Color { Color("Background/Inverse", bundle: .main) }
    var accent: Color { Color("Background/Accent", bundle: .main) }
    var layerTop: Color { Color("Background/LayerTop", bundle: .main) }
    var layerMedium: Color { Color("Background/LayerMedium", bundle: .main) }
    var layerBase: Color { Color("Background/LayerBase", bundle: .main) }
    var error: Color { Color("Background/Error", bundle: .main) }
    var errorSubtle: Color { Color("Background/ErrorSubtle", bundle: .main).opacity(0.35) }
    var success: Color { Color("Background/Success", bundle: .main) }
    var successSubtle: Color { Color("Background/SuccessSubtle", bundle: .main) }
}

struct BrandColors: Auth0ColorTokens {
    var background: any Auth0BackgroundColorTokens { BrandBackground() }
    var text: any Auth0TextColorTokens { DefaultAuth0TextColorTokens() }
    var border: any Auth0BorderColorTokens { DefaultAuth0BorderColorTokens() }
}

MyAccountAuthMethodsView()
    .auth0Theme(Auth0Theme(colors: BrandColors()))
```

### Read the theme in your own views

Access the `@Environment(\.auth0Theme)` property wrapper to apply the same tokens in any Swift view:

```swift wrap lines theme={null}
struct MyCustomStep: View {
    @Environment(\.auth0Theme) private var theme

    var body: some View {
        VStack(spacing: theme.spacing.md) {
            Text("Almost there!")
                .auth0TextStyle(theme.typography.titleLarge)
                .foregroundStyle(theme.colors.text.bold)

            Button("Continue") { /* ... */ }
                .frame(height: theme.sizes.buttonHeight)
                .background(theme.colors.background.primary)
                .cornerRadius(theme.radius.button)
        }
        .padding(theme.spacing.md)
    }
}
```

### Token reference

<Accordion title="Colors — Auth0ColorTokens">
  Colors are split across three focused protocols: `Auth0BackgroundColorTokens`, `Auth0TextColorTokens`, and `Auth0BorderColorTokens`. These are aggregated into the `Auth0ColorTokens` protocol.

  All color assets are adaptive. The asset catalog handles light and dark mode automatically.

  **Background primary**

  | **Token**                  | **Usage**                              |
  | -------------------------- | -------------------------------------- |
  | `background.primary`       | CTA button background, primary borders |
  | `background.primarySubtle` | Low-emphasis primary background        |
  | `background.inverse`       | Contrast-flipped background            |
  | `background.accent`        | Branded or featured UI highlight       |

  **Background layers**

  | **Token**                | **Usage**                   |
  | ------------------------ | --------------------------- |
  | `background.layerTop`    | Overlays and modals         |
  | `background.layerMedium` | Cards and raised containers |
  | `background.layerBase`   | Main app background         |

  **Background feedback**

  | **Token**                  | **Usage**               |
  | -------------------------- | ----------------------- |
  | `background.error`         | Error state container   |
  | `background.errorSubtle`   | Subtle error banner     |
  | `background.success`       | Success state container |
  | `background.successSubtle` | Subtle success banner   |

  **Text content**

  | **Token**       | **Usage**                              |
  | --------------- | -------------------------------------- |
  | `text.bold`     | Headings and primary body text         |
  | `text.regular`  | Secondary copy, descriptions, captions |
  | `text.disabled` | Disabled and placeholder text          |

  **Text on color surfaces**

  | **Token**        | **Usage**                                                 |
  | ---------------- | --------------------------------------------------------- |
  | `text.onPrimary` | Text and icons on `background.primary`                    |
  | `text.onSuccess` | Text and icons on `background.success`                    |
  | `text.onError`   | Text and icons on `background.error`, validation messages |

  **Border**

  | **Token**        | **Usage**                         |
  | ---------------- | --------------------------------- |
  | `border.bold`    | High-contrast or selected borders |
  | `border.regular` | Input field and card borders      |
  | `border.subtle`  | Delicate dividers                 |
  | `border.shadow`  | Elevation shadow border           |
</Accordion>

<Accordion title="Typography — Auth0TypographyTokens">
  Each token is an `Auth0TextStyle` bundling `font`, `tracking`, and `lineSpacing`. Apply them using the `.auth0TextStyle(_:)` view modifier.

  | **Token**       | **Typeface** | **Size** | **Weight** | **Line height** | **Tracking** | **Usage**                           |
  | --------------- | ------------ | -------- | ---------- | --------------- | ------------ | ----------------------------------- |
  | `displayLarge`  | Inter        | 34 pt    | SemiBold   | 41 pt           | −0.20 pt     | Hero headings, passkey enrollment   |
  | `displayMedium` | Inter        | 28 pt    | SemiBold   | 34 pt           | −0.10 pt     | Major screen titles, error headings |
  | `display`       | Inter        | 22 pt    | SemiBold   | 28 pt           | −0.05 pt     | Section-level headings              |
  | `titleLarge`    | Inter        | 20 pt    | SemiBold   | 25 pt           | 0 pt         | Screen titles, subheading cards     |
  | `title`         | Inter        | 17 pt    | SemiBold   | 24 pt           | 0 pt         | In-content titles                   |
  | `body`          | Inter        | 17 pt    | Regular    | 24 pt           | 0 pt         | Descriptions, body copy             |
  | `bodySmall`     | Inter        | 15 pt    | Regular    | 20 pt           | +0.10 pt     | Secondary body copy, footnotes      |
  | `label`         | Inter        | 16 pt    | Medium     | 21 pt           | +0.10 pt     | Button labels, form field labels    |
  | `helper`        | Inter        | 13 pt    | Regular    | 18 pt           | +0.20 pt     | Captions, helper text               |
  | `overline`      | Inter        | 11 pt    | Regular    | 16 pt           | +0.77 pt     | Overline and category labels        |

  <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
    If typeface `Inter` is not bundled in the host application, SwiftUI uses the `SF Pro` typeface automatically.
  </Callout>
</Accordion>

<Accordion title="Spacing — Auth0SpacingTokens">
  Spacing defaults to a `4 pt` grid. Use the token name in design handoffs to customize spacing, not the raw pixel value.

  | **Token** | **Default** | **Description**                              |
  | --------- | ----------- | -------------------------------------------- |
  | `xxs`     | 4 pt        | Minimal gap between tightly coupled elements |
  | `xs`      | 8 pt        | Small gap between grouped elements           |
  | `sm`      | 12 pt       | Medium internal padding                      |
  | `md`      | 16 pt       | Standard component and container padding     |
  | `lg`      | 24 pt       | Larger padding for major sections            |
  | `xl`      | 32 pt       | Extra-large padding                          |
  | `xxl`     | 48 pt       | Double-extra-large padding                   |
  | `xxxl`    | 56 pt       | Triple-extra-large padding                   |
</Accordion>

<Accordion title="Radius — Auth0RadiusTokens">
  | **Token**    | **Default** | **Usage**                                      |
  | ------------ | ----------- | ---------------------------------------------- |
  | `small`      | 8 pt        | Single character-input cells (OTP, PIN digits) |
  | `medium`     | 12 pt       | Banner and feedback cards                      |
  | `inputField` | 14 pt       | Text inputs, code display containers           |
  | `button`     | 16 pt       | CTA buttons, auth-method cards                 |
  | `pill`       | 24 pt       | Pill-shaped outline buttons                    |
</Accordion>

<Accordion title="Sizes — Auth0SizeTokens">
  | **Token**                 | **Default** | **Usage**                                         |
  | ------------------------- | ----------- | ------------------------------------------------- |
  | `buttonHeight`            | 48 pt       | All primary and secondary action buttons          |
  | `inputHeight`             | 60 pt       | Text and phone-number input fields                |
  | `size4xlDimen`            | 48 pt       | Width of a single character-input cell            |
  | `size5xlDimen`            | 56 pt       | Height of a single character-input cell           |
  | `containerSizeLargeDimen` | 52 pt       | Height of a read-only code display container      |
  | `iconSmall`               | 16 pt       | Small icons—chevrons, info indicators, checkmarks |
  | `iconMedium`              | 24 pt       | Standard icons—authentication-method images       |
  | `iconLarge`               | 28 pt       | Large icons—three-dots menu                       |
</Accordion>

## Learn more

<CardGroup cols={2}>
  <Card title="Install the iOS SDK" icon="download" href="/docs/get-started/universal-components/ios/ios-overview">
    Platform prerequisites and installation for iOS.
  </Card>

  <Card title="Build a Self-Service Account Security Interface" icon="key" href="/docs/get-started/universal-components/ios/components/my-account-overview">
    Initialize the SDK and wire the token provider to your Auth0 tenant.
  </Card>
</CardGroup>