Theming

Use Clerk's ClerkThemeExtension to adjust the general styles of the Clerk widgets, like colors and text styles.

The ClerkThemeExtension is used to customize the appearance of Clerk widgets by adjusting colors and text styles. It integrates with Flutter's ThemeData extension system to provide a consistent visual experience across all Clerk widgets.

Structure

ClerkThemeExtension consists of two main properties:

colors - Color properties for various UI elements.
stylesBuilder - A builder function that produces text styles from the color palette. Defaults to ClerkThemeStyles.defaultStylesBuilder.

Colors

The colors property is a ClerkThemeColors object containing the following color options:

`background`

Type: Color

The main background color of Clerk widgets. Light theme default: Colors.white. Dark theme default: Colors.black.

`altBackground`

Type: Color

An alternative background color used for secondary surfaces. Light theme default: Color(0xFFdddddd). Dark theme default: Color(0xFF333333).

`borderSide`

Type: Color

The color used for borders and dividers. Light theme default: Color(0xFFdddddd). Dark theme default: Color(0xFF333333).

`text`

Type: Color

The primary text color. Light theme default: Color(0xFF3c3c3d). Dark theme default: Colors.white.

`icon`

Type: Color

The color used for icons. Light theme default: Color(0xFFaaaaaa). Dark theme default: Colors.white.

`lightweightText`

Type: Color

The color used for secondary or hint text. Light theme default: Color(0xFFaaaaaa). Dark theme default: Color(0xFF555555).

`error`

Type: Color

The color used for error messages and validation states. Default: Color(0xFFff3333) (both themes).

`accent`

Type: Color

The color used for links, buttons, and interactive elements. Default: Color(0xFF6c47ff) (both themes).

Text styles

The computed styles property is a ClerkThemeStyles object containing the following text styles, derived automatically from colors:

`heading`

Type: TextStyle

Used for main headings. Font size: 18.0, weight: w500, color: colors.text.

`subheading`

Type: TextStyle

Used for secondary headings. Font size: 14.0, weight: w400, color: colors.text.

`inputText`

Type: TextStyle

Used for form field labels and hints. Font size: 14.0, color: colors.lightweightText.

`error`

Type: TextStyle

Used for validation error messages. Font size: 14.0, color: colors.error.

`text`

Type: TextStyle

Used for regular body text. Font size: 12.0, color: colors.text.

`subtext`

Type: TextStyle

Used for small helper text. Font size: 10.0, color: colors.lightweightText.

`clickableText`

Type: TextStyle

Used for links and tappable text. Font size: 12.0, color: colors.accent.

`button`

Type: TextStyle

Used for button labels. Font size: 12.0, weight: w500, color: colors.text.

`avatarInitials`

Type: TextStyle

Used for user avatar initials. Font size: 14.0, color: colors.background.

Usage

Clerk widgets automatically inherit the ClerkThemeExtension from the nearest ThemeData in the widget tree. If no extension is provided, Clerk falls back to a built-in light or dark preset based on the current ThemeData.brightness.

Apply a custom theme to all Clerk widgets

To customize all Clerk widgets in your app, add a ClerkThemeExtension to your root MaterialApp's theme extensions.

import 'package:clerk_flutter/clerk_flutter.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData.light().copyWith(
        extensions: [
          ClerkThemeExtension(
            colors: const ClerkThemeColors(
              background: Colors.white,
              altBackground: Color(0xFFf5f5f5),
              borderSide: Color(0xFFe0e0e0),
              text: Color(0xFF1a1a1a),
              icon: Color(0xFF757575),
              lightweightText: Color(0xFF9e9e9e),
              error: Color(0xFFd32f2f),
              accent: Color(0xFF0057FF),
            ),
          ),
        ],
      ),
      home: const RootPage(),
    );
  }
}

Apply a theme to specific widgets

You can scope a ClerkThemeExtension to a subtree by wrapping it in a Theme widget. This is useful when different screens require different Clerk styles.

import 'package:clerk_flutter/clerk_flutter.dart';
import 'package:flutter/material.dart';

class SignInPage extends StatelessWidget {
  const SignInPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Theme(
      data: Theme.of(context).copyWith(
        extensions: [
          ClerkThemeExtension(
            colors: const ClerkThemeColors(
              background: Colors.white,
              altBackground: Color(0xFFf5f5f5),
              borderSide: Color(0xFFe0e0e0),
              text: Color(0xFF1a1a1a),
              icon: Color(0xFF757575),
              lightweightText: Color(0xFF9e9e9e),
              error: Color(0xFFd32f2f),
              accent: Colors.purple,
            ),
          ),
        ],
      ),
      child: const ClerkAuthentication(),
    );
  }
}

Custom text styles

You can override the default text styles by providing a custom stylesBuilder. This is useful when you want to use a custom font family or adjust specific text properties.

import 'package:clerk_flutter/clerk_flutter.dart';
import 'package:flutter/material.dart';

class CustomStylesApp extends StatelessWidget {
  const CustomStylesApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData.light().copyWith(
        extensions: [
          ClerkThemeExtension(
            colors: const ClerkThemeColors(
              background: Colors.white,
              altBackground: Color(0xFFf5f5f5),
              borderSide: Color(0xFFe0e0e0),
              text: Color(0xFF1a1a1a),
              icon: Color(0xFF757575),
              lightweightText: Color(0xFF9e9e9e),
              error: Color(0xFFd32f2f),
              accent: Color(0xFF0057FF),
            ),
            stylesBuilder: (colors) => ClerkThemeStyles(colors: colors),
          ),
        ],
      ),
      home: const RootPage(),
    );
  }
}

Light and dark mode support

Clerk widgets automatically support both light and dark mode, adapting to the active ThemeData.brightness. If your app provides separate theme and darkTheme values to MaterialApp, add a ClerkThemeExtension to each.

import 'package:clerk_flutter/clerk_flutter.dart';
import 'package:flutter/material.dart';

final _lightClerkTheme = ClerkThemeExtension(
  colors: const ClerkThemeColors(
    background: Colors.white,
    altBackground: Color(0xFFf5f5f5),
    borderSide: Color(0xFFe0e0e0),
    text: Color(0xFF1a1a1a),
    icon: Color(0xFF757575),
    lightweightText: Color(0xFF9e9e9e),
    error: Color(0xFFd32f2f),
    accent: Color(0xFF0057FF),
  ),
);

final _darkClerkTheme = ClerkThemeExtension(
  colors: const ClerkThemeColors(
    background: Color(0xFF121212),
    altBackground: Color(0xFF1e1e1e),
    borderSide: Color(0xFF2c2c2c),
    text: Colors.white,
    icon: Color(0xFFbbbbbb),
    lightweightText: Color(0xFF757575),
    error: Color(0xFFef5350),
    accent: Color(0xFF4d8fff),
  ),
);

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData.light().copyWith(
        extensions: [_lightClerkTheme],
      ),
      darkTheme: ThemeData.dark().copyWith(
        extensions: [_darkClerkTheme],
      ),
      home: const RootPage(),
    );
  }
}

On this page