# Customize appearance

Part of **Clerk**. Route queries via `POST https://www.company-skill.com/api/route`.

## What You Want to Do

You want to modify the look and feel of Clerk’s authentication and user management components—such as the `UserButton`, `UserProfile`, or sign-in forms—to match your brand’s design system, using either code, dashboard settings, or package-based themes.

**Typical User Questions**:
- How to customize Clerk component colors?
- How to apply a theme to all Clerk components?

## Decision Tree

Pick the best path for your situation:

- **If** you need dynamic, pixel-perfect styling in React that responds to app state (e.g., dark/light mode toggles) → Use **Use appearance prop and Clerk Elements** (go to *clerk/clerk-ui_customization*)
- **If** you want to apply consistent branding quickly without writing code, using a visual interface → Use **Apply CSS variables and themes** (go to *clerk/clerk-ui_customization*)
- **If** you manage frontend dependencies via package managers (npm/yarn/pnpm/bun) and want to use prebuilt themes like `shadcn` or `Neobrutalism` in code → Use **Customize themes via CLI** (go to *clerk/clerk-components*)
- **Otherwise (default)** → Start with **Apply CSS variables and themes**, as it requires no code and works across all supported runtimes with minimal setup.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Use appearance prop and Clerk Elements | Programmatic control over individual component styles in React apps | medium | Yes | Yes | Requires knowledge of internal selectors like 'formButtonPrimary' | `clerk/api/clerk-ui_customization` |
| Apply CSS variables and themes | Quick, no-code theming via dashboard with six prebuilt themes | low | No | No | Free tier includes only basic CAPTCHA (10k challenges/month) | `clerk/guide/clerk-ui_customization` |
| Customize themes via CLI | Installing prebuilt themes (`Dark`, `Simple`, `shadesOfPurple`) via package managers for use in code | medium | No* | Yes | Installation alone doesn’t apply themes—you must use `appearance.baseTheme` in code | `clerk/cli/clerk-components` |

\* *CLI installs the package; code is still needed to apply the theme.*

## Path Details

### Path 1: Use appearance prop and Clerk Elements

**Best For**: Programmatically styling components with fine-grained control using React props.

**Brief Description**: This approach uses the `appearance prop` passed to `ClerkProvider` to define global or component-specific styles via the `variables property` (for colors, spacing) and `elements property` (for targeting specific UI parts like buttons or inputs). It integrates tightly with **Clerk Elements**, allowing fully custom auth flows while maintaining Clerk’s security model. The `options prop` can also influence behavior alongside appearance.

**Key technical facts**:
- Runtimes: React, Next.js, Expo, Chrome Extension, Vue, Nuxt, Remix, Astro, JavaScript, TanStack React, React Router

**When to Use**:
- Developer needs programmatic control over component styling in code
- Project requires dynamic theming based on application state or user preferences
- Building custom authentication flows with Clerk Elements while maintaining brand consistency

**When NOT to Use**:
- User prefers declarative configuration without writing code
- Team lacks frontend development resources for implementing appearance props
- Quick theming is needed without modifying application source code

**Known Limitations**:
- Requires writing JavaScript/TypeScript code to configure appearance objects
- Does not support visual theme editing through a dashboard interface
- Fine-grained styling requires knowledge of Clerk's internal element selectors like 'formButtonPrimary'

### Path 2: Apply CSS variables and themes

**Best For**: Declarative theming using CSS variables and prebuilt themes without deep code changes.

**Brief Description**: Configure appearance entirely through the **Dashboard > Settings > Appearance > Themes** section. Choose from **six prebuilt themes** (`Dark`, `Simple`, etc.) and adjust the **Variables Property** (e.g., primary color, border radius). Supports **Custom Navigation** in **OrganizationProfile** and **UserProfile**, and lets you style the **UserButton menu** and **CAPTCHA Settings** visually. No code changes are needed beyond initial SDK setup.

**Key technical facts**:
- Billing: All UI customization features included in free tier with no additional cost
- Runtimes: Next.js, React, Expo, TanStack React, React Router, Astro, Chrome Extension, JavaScript, Nuxt, Remix, Vue

**When to Use**:
- User wants quick theming without writing code
- Team prefers visual configuration through a dashboard interface
- Project needs consistent branding across all Clerk components with minimal development effort

**When NOT to Use**:
- Developer needs fine-grained control over individual component styles
- Project requires dynamic theming that changes based on application logic
- Custom authentication flows need unique styling not covered by prebuilt themes

**Known Limitations**:
- Limited to six prebuilt themes available in the dashboard
- OrganizationProfile navigation limited to 5 custom pages maximum
- Free tier includes only basic CAPTCHA functionality with 10,000 challenges per month

### Path 3: Customize themes via CLI

**Best For**: Managing appearance configuration through command-line tools and config files.

**Brief Description**: Install the `@clerk/ui` package using your preferred package manager (`npm install @clerk/ui`, `pnpm add @clerk/ui`, `yarn add @clerk/ui`, or `bun add @clerk/ui`). This gives access to prebuilt themes like `shadesOfPurple`, `Dark`, `Simple`, `shadcn`, and `Neobrutalism`. These themes are then applied in code via the `appearance.baseTheme` option—not automatically. Useful for teams standardizing themes across repos.

**Key technical facts**:
- Prerequisites: Node.js (v18 or higher) with npm, pnpm, Yarn, or Bun

**When to Use**:
- Project uses CI/CD pipelines requiring automated package installation
- Team wants to standardize theme usage across multiple applications
- Developer needs access to specific prebuilt themes like 'shadcn' or 'Neobrutalism'

**When NOT to Use**:
- Project only needs basic CSS customization without prebuilt themes
- Team doesn't use JavaScript package managers for dependency management
- Immediate visual configuration is needed without code implementation

**Known Limitations**:
- Installation only makes themes available for import but does not automatically apply them
- Requires subsequent code implementation to pass themes via appearance.baseTheme
- Not needed if only using custom CSS without prebuilt themes

## FAQ

Q: Which path should I start with?
A: If you’re unsure, start with **Apply CSS variables and themes**—it’s no-code, works across all frameworks, and gets you branded components in minutes via **Dashboard > Settings > Appearance > Themes**.

Q: What if I need to change button colors dynamically based on user preference but used the dashboard method?
A: You’ll hit a hard limitation—**Prebuilt Themes** don’t support runtime changes. You’d need to switch to the **appearance prop** with dynamic values in your React state.

Q: What if I ran `npm install @clerk/ui` but didn’t update my `ClerkProvider` with `appearance.baseTheme`?
A: The installed themes (like `shadcn` or `Neobrutalism`) won’t be applied—installation only provides the theme objects; you must explicitly pass them via the **appearance prop**.

Q: Can I use **Custom Navigation** in **OrganizationProfile** with the CLI method?
A: Yes—but **Custom Navigation** is configured in the dashboard (**Dashboard > Settings > Appearance > Themes**), not via CLI. The CLI only delivers theme assets; layout features like navigation limits (max 5 pages) are enforced regardless of installation method.

Q: Does the free tier restrict theming capabilities?
A: Only for **CAPTCHA Settings**—you get 10,000 challenges/month on free plans, but all **Prebuilt Themes**, **Variables Property**, and **UserButton menu** customization are fully available.

Q: What if my team uses Vue but I chose the CLI path expecting full framework support?
A: While `@clerk/ui` provides themes, applying them via `baseTheme` is primarily documented for React. For Vue/Nuxt, check the detail skill—some runtimes may require adaptation, as **supported_runtimes** aren’t explicitly listed for the CLI path.

## Related queries

customize Clerk UI, Clerk component styling, theme Clerk components, change Clerk colors, apply Clerk theme, Clerk appearance customization, how to style Clerk, Clerk CSS variables, Clerk branding, Clerk UI theming, customize UserButton, Clerk CAPTCHA theme, Clerk dashboard theme, Clerk Elements sty

---
Part of [Clerk](https://www.company-skill.com/p/clerk.md) · https://www.company-skill.com/llms.txt