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/>.

Start by choosing the baseTheme that most closely matches your brand
Modify the placement of elements like social sign-in buttons with layout
Set global styles like the primary color with variables
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

1
// You will need to install @clerk/themes separately
2
import { dark } from '@clerk/themes';
3

4
const App = () => {
5
  return (
6
    <ClerkProvider
7
      appearance={{
8
        baseTheme: dark
9
      }}
10
    >
11
      {...}
12
    </ClerkProvider>
13
  );
14
}

Layout

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

Name	Type	Description
logoPlacement	string	Controls whether the logo will be rendered inside or outside the component card. Valid inputs: -'inside' -'outside' -'none'
logoImageUrl	string	The URL of your custom logo the components will display.
socialButtonsVariant	string	Controls the variant that will be used for the social buttons. Valid inputs: -'auto' -'iconButton' -'blockButton'
socialButtonsPlacement	string	Controls whether the social buttons will be rendered above or below the card form. Valid inputs: -'top' -'bottom'

Example: Social buttons as icons, placed at the bottom

1
<SignIn
2
  appearance={{
3
    layout: {
4
      socialButtonsVariant: 'iconButton',
5
      socialButtonsPlacement: 'bottom'
6
    }
7
  }}
8
/>

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:

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 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.

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!