Engineering
Apr 15, 2022
Unicorn or Chameleon? Two strategies for exporting customizable React components
Colin Sidoti
React Components are the future of APIs – but how can developer tools companies enable robust customization? We explore two strategies.
Clerk's React library exports <SignUp/>, <SignIn/>, and <UserProfile/> components. They come styled and fully-featured so developers can focus on building their application:
Unsurprisingly, this leads to the question: How can I customize the components to match my brand?
Whitelabeling software is a famously hard and unsolved problem - it's extremely common to find widgets or portions of websites that have completely different styling.
One example is this chat widget from Alaska Airlines, which shows different form field styling (rounded vs square), different buttons (huge text, not capitalized), and a different font (Arial vs Circular).
This quarter at Clerk, we're revisiting our customization strategy. We want to truly solve this problem with perfect matching styles instead of just "close enough" styles. Internally, we say we're switching from a "unicorn" strategy to a "chameleon" strategy.
While we haven't finalized the chameleon strategy yet, we do have a proof of concept running and are excited about the developer experience it produces.
Unicorn strategy
Our initial approach to theming is a "unicorn" strategy because we came up with the system ourselves – developers have to learn our specific way of applying styles.
We drew inspiration from others, so you've probably seen something like it before. Developers simply pass a theme prop to <ClerkProvider> to customize aspects of the design:
{general: {color: "#f1f1f1",backgroundColor: "#f2f2f2",fontColor: "#f3f3f3",fontFamily: "Inter, sans serif",labelFontWeight: "500",padding: "1em",borderRadius: "20px",boxShadow: "0 2px 8px rgba(0, 0, 0, 0.2)",},buttons: {fontColor: "#f4f4f4",fontFamily: "Inter, sans serif",fontWeight: "300",},}
While this system is great for quickly getting close styles, it suffers in the last mile. There simply aren't enough options to provide developers with the complete customization capabilities they desire.
Chameleon strategy
Our next iteration approaches customization with a new mindset. Instead of asking developers to learn our strategy, we will integrate with any strategy they already use.
If you've been around the frontend ecosystem for a while, you know there are several, very popular styling systems that all work completely differently. Because they're so diverse and we want to blend in with all of them, we call this a "chameleon" strategy.
Let's work through an example to explain how it works.
Consider that one of our components has a "primary button." By default, that button renders to this HTML:
<button class="clerk-button-primary">Action</button>
Note: in this post, we're only focused on styles. We'll discuss customizing the "Action" string in the future.
To change the style of this button, developers will still pass a theme prop, but now the selector will be for this specific element:
<SignIn theme={{primaryButton: customButton}} />
In this snippet, customButton can have one of three values:
- A string with one or many class names. If passed, the value will replace the default
clerk-button-primaryclass. - A React component that renders a
<button>and forwards all props (including children). If passed, the default element will not be rendered at all, and instead the passed component will be rendered. - A dictionary that adheres to the
CSSStyleInterfacetype. This is for completeness more than anything else. If passed, the value will be forwarded to thestyleprop, and the the defaultclerk-button-primaryclass will be omitted.
Now, let's see how it works for different styling libraries.
Tailwind
Simply pass in Tailwind classes as a string:
<SignIntheme={{primaryButton: "p-4 rounded"}}/>
CSS modules
When a CSS module is imported, the object automatically returns class names. Simply pass it in:
import styles from "./Styles.css"<SignIntheme={{primaryButton: styles.customButton}}/>
styled-components
styled-components works by returning a React component that automatically forwards props to a <button> element – exactly as specified by Clerk:
const CustomButton = styled.button`border-radius: 1rem;padding: 1rem;`<SignIntheme={{primaryButton: CustomButton}}/>
Chakra
Chakra also provides React components, but they are modified with props, which makes the setup slightly more complex, but still quite simple:
<SignIntheme={{primaryButton: (props) => <Button size="lg" {...props} />}}/>
Since the chameleon strategy ultimately hooks into HTML and React primitives, we're confident that we can make every styling library work with this strategy, not just the four we've listed above.
Thoughts, comments, questions? We're eager for your feedback! Please reach out to @ClerkDev on Twitter or contact support.
Start now,
no strings attached
Start completely free for up to 10,000 monthly active users and up to 100 monthly active orgs. No credit card required.
Pricing built forbusinesses of all sizes.
Learn more about our transparent per-user costs to estimate how much your company could save by implementing Clerk.
Newsletter!
The latest news and updates from Clerk, sent to your inbox.