Customize Style and Themes for iOS Universal Components

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

Auth0 Universal Components for 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:

import SwiftUI
import Auth0UniversalComponents

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

No additional setup is required to load the Auth0 default theme. Universal Components apply it automatically when no custom theme is provided.

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:

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:

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:

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:

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

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

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

If typeface Inter is not bundled in the host application, SwiftUI uses the SF Pro typeface automatically.

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

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

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

Learn more

Install the iOS SDK

Platform prerequisites and installation for iOS.

Build a Self-Service Account Security Interface

Initialize the SDK and wire the token provider to your Auth0 tenant.