Customizing <UserButton /> for the Clerk Dashboard

More styling work now happens in a coding agent. Point it at a component, tell it what you want, and it edits the CSS. That works well when the styles are easy to find and change, and poorly when they're buried in a library-specific API.

We saw this in the Clerk Dashboard. Our org switcher, built on UserButton, needed to match the rest of the product, so we'd rebuilt the surrounding UI by hand. With the newest version of our UserButton component, we were able to delete most of that code. What's left is a handful of small CSS overrides, which are an easy tool for an agent to reach for when customizing components to match an existing design system.

It works because this new version of Clerk's components is styled with a plain CSS file you import. Our previous components were styled with CSS too, but through a CSS-in-JS solution. You customized them with the appearance prop or by overriding stable class names, and those overrides ran into specificity problems because of how their dynamic stylesheet was inserted into the page. Now the styles are a stylesheet like any other, with classes, attributes, and layers, which agents already know well.

Here's what changed, and why each piece helps when an agent is doing the styling.

• Restyle in place. A few rules against stable class names replace the wrapper we used to build.
• CSS layers you control. You choose where the stylesheet is imported, which sets where it sits in the cascade. Your styles win without the specificity fights.
• State attributes for enter and exit. Animation state is exposed as data attributes, so you can override the motion in plain CSS.
• Plain CSS, wherever you want it. Use one stylesheet, several, or CSS next to your component code. Wherever you can write CSS, you can customize the components.

How it used to work

Customizing the previous components usually meant using the appearance prop to target internal element names and pass in class strings or style objects.

When we ran up against the limits of that approach, we built our own trigger and popover and embedded Clerk's UI inside it. Our organization switcher became hundreds of lines of code, with a custom popover, a store tracking whether it was open, manual invitation counting, query invalidation callbacks, and a hydration workaround. All of it existed so the Clerk piece would sit comfortably inside our header.

What changed

The Dashboard header now renders UserButton 2.0⁠ with a handful of props, and all the styling to integrate it with our design system lives in a stylesheet.

Restyle in place, instead of rebuilding

In the Dashboard we used to wrap the previous components in our own trigger and popover. With UserButton 2.0 we can achieve the same result with only a few rules against stable class names and state attributes, so there was nothing left to rebuild.

This is the actual code for our trigger (we write it with Tailwind utilities like h-8 rounded border-black/5 shadow-black/2, so this is the plain CSS they compile to, with our theme values filled in).

The components take their colors from a small set of semantic tokens, like --cl-color-surface, --cl-color-foreground, --cl-color-border and --cl-color-brand. Fitting them into an existing design system mostly means setting those tokens once, at the root, to variables you already have. The surface token is the color that menus, popovers and cards sit on. Text and hover tints are derived from it and a neutral color, so they follow along.

In the Dashboard, that comes down to one line for the switcher:

Brand, positive, negative and warning keep their defaults unless you set them too, and overriding one retints its companion colors. The tokens use light-dark(), so a single value replaces both modes. Dark mode follows when your own variable changes with your theme, which ours does.

CSS layers you control

The previous components supported CSS layers too, through a layer name on the appearance prop, but that option was limiting. Now the stylesheet is a normal CSS file you import where you want, into a layer you name, and you define the layer order yourself.

Layer order beats selector specificity, so anything in clerkOverrides wins over the component's styles however specific its selectors are. No !important, no doubled-up selectors.

Because the stylesheet is a regular CSS file in your own app, it can be cached with the rest of your CSS. Even though the initial CSS download can be larger, we believe this approach results in better performance compared to our previous components, which shipped CSS inside our JavaScript bundles. Furthermore, since we use StyleX for our new components, we anticipate that our CSS will grow at a slower rate compared to previous components. It also gives you direct control over how and when it loads.

Animations through data-starting-style and data-ending-style

The popover gets data-starting-style as it mounts and data-ending-style as it leaves, so the animation is ordinary CSS. Here's a version of what we use in the Dashboard. It's subtle and close to the default, but it matches our other components.

Here is another example that is a little more bold, and demonstrates the power unlocked by the new approach. It's the same two attributes, so anything CSS can animate works, whether that's scale, rotation, a 3D tilt, or a custom spring.

This assumes the menu opens below the button, so its top edge is the hinge. The default enter and exit animates transform, so setting transform yourself replaces it directly, and it wins because your layer comes later. If you animate individual properties like scale or rotate instead, reset transform first. Otherwise they stack on top of the default.

Easy for agents to work in

Everything above can live in one CSS file. The component stays a few lines of props, and the look sits in plain CSS with stable class names, data-* state attributes, and --cl-* tokens.

That makes it easier for an agent to work in. It can inspect the DOM to see what it can target, read one stylesheet to see what's already overridden, and write a few rules in a later layer without out-specifying the library. There's no styling API to learn beyond class names, attributes, and tokens, which agents already know well.

The 2.0 components are experimental and subject to change, so we haven't documented them properly yet. Until they settle, the source is the most accurate reference, and your agent can read it directly. The class names, attributes, and tokens are all in there.