Clerk logo

Clerk Docs

Ctrl + K
Go to
Check out a preview of our new docs.

Appearance prop

Customize components to match your brand using the appearance prop


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

// You will need to install @clerk/themes separately
import { dark } from '@clerk/themes';
const App = () => {
return (
baseTheme: dark
Sign in form with dark base theme


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

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

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


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

layout: {
socialButtonsVariant: 'iconButton',
socialButtonsPlacement: 'bottom'
Sign In form with social icons buttons at bottom of form


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


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



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



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



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



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



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

@default white



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

@default A lighter shade of {Variables.colorText}



The background color for the card container.



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

@default {Variables.colorText}



The background color for all input element color



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"



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

@default inherit



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



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

@default auto



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}



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



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

@default 1rem


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 © 2023