Apply shared styling through the Clerk integration
Application-wide branding
Clerk · Type Alias
Appearance
Appearance is Clerk's configuration for customizing component styling globally or per component. It supports themes, layout options, broad variables, element-level overrides, CAPTCHA appearance settings, and CSS-layer control.
How it works
Appearance configures the visual presentation of Clerk components. Provide it globally through the integration setup or locally on a component; its options include a base theme, layout settings, general variables, element-specific overrides, CAPTCHA settings, and a CSS layer name.
Syntax
appearance?: {
theme?: BaseTheme | BaseTheme[]
options?: Options
variables?: Variables
elements?: Elements
Captcha?: object
cssLayerName?: string
}Parameters
| Name | Type | Description |
|---|---|---|
theme? | BaseTheme | BaseTheme[] | Base theme or themes used by Clerk components. |
options? | Options | Layout and other component configuration options. |
variables? | Variables | General theme overrides, including colors and fonts. |
elements? | Elements | Fine-grained overrides for specific elements or states. |
Captcha | object | Configuration for the CAPTCHA widget's appearance. |
cssLayerName? | string | Name of the CSS layer containing Clerk component styles. |
Key points
- Use Appearance globally for shared styling or attach it to a specific Clerk component for local styling.
- Global configuration belongs at the point where the Clerk integration is initialized.
- The documented configuration is an object whose supported properties are listed by Clerk.
- The optional theme establishes the starting visual theme for Clerk components.
- Variables provide broad visual overrides such as colors and fonts.
- Elements target particular component elements or state-specific styling.
Common mistakes
- A top-level appearance setting does not automatically style components opened by another component.
- Pass appearance through the opened component's dedicated props object when nested customization is needed.
Example: Apply a global Clerk theme
import { ClerkProvider } from '@clerk/nextjs'
import { dark } from '@clerk/themes'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<ClerkProvider appearance={{ theme: dark }}>
{children}
</ClerkProvider>
)
}Uses a base theme to customize Clerk components globally.
When to use it
Customize one Clerk component without changing others
Component-specific design
Override individual elements or state styles
State-level visual refinement
Place Clerk styles in a named CSS layer
CSS cascade isolation
Interview questions
QWhat is the purpose of Appearance?
Appearance is Clerk's configuration object for styling its components. It can be supplied globally where Clerk is initialized or individually on a Clerk component.
Follow-up: How would you style a component opened by another component? Pass appearance through the dedicated props object for the component being opened.
QWhat configuration areas does Appearance provide?
The documented configuration includes optional theme, options, variables, elements, CAPTCHA, and cssLayerName settings. A theme supplies the base visual theme, while variables and elements provide broader and fine-grained overrides.
Follow-up: Which setting is intended for global color and font changes? Use variables, because it provides general theme overrides.
QWhat does the theme property do?
The theme property accepts BaseTheme or an array of BaseTheme values. It establishes the base theme used by Clerk components before further customization is applied.
Follow-up: How can advanced CSS conflicts be managed? Set cssLayerName to isolate Clerk styles in a named CSS layer and control the cascade.
Related
BaseThemeOptionsVariablesElementsCaptchaClerkProvider