Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.dev

Appearance prop

Customize components to match your brand using the appearance prop

Overview

The appearance prop can be applied to <ClerkProvider/> to share styles across every component, or individually to <SignUp/>, <SignIn/>, <UserProfile/>, and <UserButton/>.

  1. Start by choosing the baseTheme that most closely matches your brand
  2. Modify the placement of elements like social sign-in buttons with layout
  3. Set global styles like the primary color with variables
  4. Apply custom CSS to individual HTML elements with elements

The appearance prop is built to work with TypeScript. If you have types enabled, you will benefit from IntelliSense code completion.

Want to play around with the appearance prop right now? Check out the Components sandbox on the Clerk Playground

Base theme

Choose from one of the following base themes:

  • light (default)
  • dark

Example: Use the dark theme

Sign in form with dark base theme

Layout

The layout property is used for customizations that require changes to the HTML, like changing the placement or structure of elements.

NameTypeDescription
logoPlacement'inside' | 'outside' | 'none'

Controls whether the logo will be rendered inside or outside the component card.

logoImageUrlString

The URL of your custom logo the components will display.

socialButtonsVariant'auto' | 'iconButton' | 'blockButton'

Controls the variant that will be used for the social buttons.

socialButtonsPlacement'top' | 'bottom'

Controls whether the social buttons will be rendered above or below the card form.

Example: Social buttons as icons, placed at the bottom

Sign In form with social icons buttons at bottom of form

Variables

The variables property is used to adjust the general styles of the base theme, like colors, backgrounds, typography. Much of what is typically defined as a brand style can be controlled by only setting variables to match your brand, e.g. colorPrimary, fontFamily, borderRadius.

The table below includes all the possible variables with their property name, type, and description of how it is used:

Variable Name & Type Description
colorPrimary?

CssColorOrScale

The primary color used throughout the components. Set this to your brand color.

colorDanger?

CssColorOrScale

The color used to indicate errors or destructive actions. Set this to your brand's danger color.

colorSuccess?

CssColorOrScale

The color used to indicate an action that was completed successfully or a positive result.

colorWarning?

CssColorOrScale

The color used for potentially destructive actions or when the user's attention is required.

colorAlphaShade?

CssColorOrAlphaScale

The color that will be used for all to generate the alpha shades the components use. To achieve sufficient contrast, light themes should be using dark shades (`black`), while dark themes should be using light (`white`) shades. This option applies to borders, backgrounds for hovered elements, hovered dropdown options etc.

@default black

colorTextOnPrimaryBackground?

CssColor

The color of text appearing on top of an element that with a background color of {Variables.colorPrimary}, eg: solid primary buttons.

@default white

colorTextSecondary?

CssColor

The text color for elements of lower importance, eg: a subtitle text.

@default A lighter shade of {Variables.colorText}

colorBackground?

CssColor

The background color for the card container.

colorInputText?

CssColor

The default text color inside input elements. To customise the input background color instead, use{' '} {Variables.colorInputBackground}.

@default {Variables.colorText}

colorInputBackground?

CssColor

The background color for all input element color

fontFamily?

FontFamily

The default font that will be used in all components. This can be the name of a custom font loaded by your code or the name of a web-safe font. If a specific fontFamily is not provided, the components will inherit the font of the parent element.

@default inherit

@example fontFamily: "Montserrat"

fontFamilyButtons?

FontFamily

The default font that will be used in all buttons. If not provided, {Variables.fontFamily} will be used instead.

@default inherit

fontSize?

CssLengthUnit

The value will be used as the base `md` to calculate all the other scale values (`2xs`, `xs`, `sm`, `lg` and `xl`). By default, this value is relative to the root fontSize of the HTML element.

@default 1rem

fontSmoothing?

FontSmoothing

What text anti-aliasing strategy the components will use by default. You can set it to `auto`, `antialiased` or `never`.

@default auto

fontWeight?

FontWeightScale

The font weight the components will use. By default, the components will use the 400, 500 and 600 weights for normal, medium and bold text respectively. You can override the default weights by passing a {FontWeightScale} object.

@default {normal: 400, medium: 500, bold: 600}

borderRadius?

CssLengthUnit

The size that will be used as the `md` base borderRadius value. This is used as the base to calculate the `lg`, `xl`, `2xl` our components use. As a general rule, the bigger an element is, the larger its borderRadius is going to be. eg: the Card element uses '2xl'

@default 0.375rem

spacingUnit?

CssLengthUnit

The base spacing unit that all margins, paddings and gaps between the elements are derived from.

@default 1rem

Elements

The elements property is used for fine-grained theme overrides, and is useful when for styling specific HTML elements. Whereas variables applies styles across many elements, using elements is like using a scalpel.

To determine the selector for each element, use your browser's element inspector and examine the elements class.

Using elements inspector with dev tools

The element will have multiple classes applied like:

cl-formButtonPrimary cl-button 🔒️ cl-internal-1ta0xpz

The classes to the right of the lock icon (🔒) are used internally and can be safely ignored. The main class to focus on for styling in this case is cl-formButtonPrimary. You can use this as a global CSS selector (e.g. .cl-formButtonPrimary { /* ... */ }) to add style rules to this element, or you can use the appearance prop to replace this class name with one of your own. Choose your preferred styling method for additional guidance:

Looking for Chakra or Styled Components? Support for these is on our roadmap and will be implemented soon. Stay tuned!

Was this helpful?

Clerk © 2022