home / skills / clerk / skills / custom-ui

custom-ui skill

safe

/skills/custom-ui

This skill helps you tailor Clerk component appearance by applying themes, layout, colors, and fonts to match branding.

npx playbooks add skill clerk/skills --skill custom-ui

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.8 KB

---
name: clerk-custom-ui
description: Customize Clerk component appearance - themes, layout, colors, fonts, CSS. Use for appearance styling, visual customization, branding.
allowed-tools: WebFetch
license: MIT
metadata:
  author: clerk
  version: "1.0.0"
---

# Component Customization

> **Prerequisite**: Ensure `ClerkProvider` wraps your app. See `setup/`.

## Component Customization Options

| Task | Documentation |
|------|---------------|
| Appearance prop overview | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview |
| Layout (structure, logo, buttons) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/layout |
| Themes (pre-built dark/light) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/themes |
| Variables (colors, fonts, spacing) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/variables |
| CAPTCHA configuration | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/captcha |
| Bring your own CSS | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/bring-your-own-css |

## Appearance Pattern

```typescript
<SignIn
  appearance={{
    variables: {
      colorPrimary: '#0000ff',
      borderRadius: '0.5rem',
    },
    layout: {
      logoImageUrl: '/logo.png',
      socialButtonsVariant: 'iconButton',
    },
  }}
/>
```

### variables (colors, typography, borders)

| Property | Description |
|----------|-------------|
| `colorPrimary` | Primary color throughout |
| `colorBackground` | Background color |
| `borderRadius` | Border radius (default: `0.375rem`) |

### layout (structure, logo, social buttons)

| Property | Description |
|----------|-------------|
| `logoImageUrl` | URL to custom logo |
| `socialButtonsVariant` | `'blockButton'` \| `'iconButton'` \| `'auto'` |
| `socialButtonsPlacement` | `'top'` \| `'bottom'` |

## shadcn Theme

**If the project has `components.json`** (shadcn/ui installed), use the shadcn theme:

```typescript
import { shadcn } from '@clerk/themes'

<ClerkProvider
  appearance={{
    theme: shadcn,
  }}
/>
```

Also import shadcn CSS in your global.css:
```css
@import 'tailwindcss';
@import '@clerk/themes/shadcn.css';
```
## Workflow

1. Identify customization needs (colors, layout, theme, CSS)
2. WebFetch the appropriate documentation from table above
3. Follow official code examples from the docs
4. Apply appearance prop to your Clerk components

## Common Pitfalls

| Issue | Solution |
|-------|----------|
| Colors not applying | Use `colorPrimary` not `primaryColor` |
| Logo not showing | Put `logoImageUrl` inside `layout: {}` |
| Social buttons wrong | Add `socialButtonsVariant: 'iconButton'` in `layout` |
| Styling not working | Use appearance prop, not direct CSS (unless with bring-your-own-css) |

Overview

This skill customizes Clerk component appearance across themes, layout, colors, fonts, and CSS. It centralizes configuration using Clerk's appearance prop so UI changes are consistent and maintainable. Use it to implement branding, switch between pre-built themes, or drop in custom CSS for advanced styling.

How this skill works

It applies an appearance object to Clerk components or ClerkProvider, setting variables (colors, typography, radii), layout options (logo, social button styles, placement), and optional theme imports like shadcn. For advanced control you can import a prebuilt theme or provide your own CSS via the bring-your-own-css pattern. The skill maps common visual needs to Clerk's documented properties and common workﬂow steps to apply them reliably.

When to use it

Apply brand colors, fonts, and radii for a consistent sign-in/up experience
Switch between light/dark or prebuilt themes like shadcn across the app
Reposition or replace the Clerk logo and adjust social button styles
Troubleshoot styling that isn’t applying as expected
Add global CSS overrides when appearance prop is insufficient

Best practices

Wrap your app with ClerkProvider before applying appearance settings
Prefer appearance.variables for colors/typography instead of direct CSS where possible
Place logoImageUrl inside layout to ensure the logo renders
Use socialButtonsVariant and socialButtonsPlacement to control third-party button behavior
Import and include shadcn CSS only when using the shadcn theme

Example use cases

Set colorPrimary and borderRadius in appearance.variables to match brand tokens
Configure layout.logoImageUrl and socialButtonsVariant for a compact sign-in UI
Enable a dark theme by swapping Clerk’s theme or toggling variables for background and text
Import @clerk/themes/shadcn.css and set theme: shadcn when the project uses shadcn/ui
Add a custom stylesheet via bring-your-own-css to handle edge-case layout tweaks

FAQ

What is the recommended place to add appearance settings?

Add appearance settings on ClerkProvider to apply them app-wide or on individual components for targeted overrides.

Why isn’t my color change showing?

Use appearance.variables.colorPrimary (not primaryColor) and verify the appearance object is passed to the component or provider.