Unicorn or Chameleon? Two strategies for exporting customizable React parts

Clerk’s React library exports , , and parts. They come styled and fully-featured so developers can specialise in constructing their application:

Unsurprisingly, this ends in the ask: How can I customise the parts to study my ticket?

Whitelabeling instrument is a famously laborious and unsolved scenario – it be extraordinarily frequent to search out widgets or portions of net sites which contain fully diversified styling.

One example is this chat widget from Alaska Airways, which reveals diversified create self-discipline styling (rounded vs square), diversified buttons (big textual narrate, no longer capitalized), and a fascinating font (Arial vs Round).

This quarter at Clerk, we’re revisiting our customization approach. We are looking out to the truth is resolve this scenario with ideal matching styles in order of pleasurable “shut enough” styles. Internally, we deliver we’re switching from a “unicorn” procedure to a “chameleon” approach.

Whereas we haven’t finalized the chameleon approach but, we attain contain a proof of conception working and are pondering the developer journey it produces.

Unicorn approach

Our preliminary capability to theming is a “unicorn” approach due to we came up with the machine ourselves – developers must always be taught our particular process of making exercise of styles.

We drew inspiration from others, so you can also neutral contain presumably considered something admire it earlier than. Builders merely breeze a theme prop to to customise functions of the procedure:

{
  frequent:  {
    coloration:  "#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",
  },
}

Whereas this methodology is sizable for mercurial getting shut styles, it suffers in the closing mile. There merely are no longer enough alternate choices to give developers collectively with your complete customization capabilities they desire.

Chameleon approach

Our next iteration approaches customization with a brand new mindset. Rather than asking developers to be taught our approach, we can integrate with any approach they already exercise.

Whereas you happen to can also neutral contain been across the frontend ecosystem for a while, you know there are several, very accepted styling systems that every person work fully otherwise. On account of they’re so diverse and we are looking out to blend in with all of them, we call this a “chameleon” approach.

Let’s work by an example to illustrate the blueprint in which it works.

Opt into consideration that one among our parts has a “fundamental button.” By default, that button renders to this HTML:

button class="clerk-button-primary">Actionbutton>

Show: in this put up, we’re easiest inquisitive about styles. We will discuss customizing the “Action” string in due route.

To alternate the form of this button, developers will aloof breeze a theme prop, nonetheless now the selector could be for this particular ingredient:

SignIn theme={{
  primaryButton:  customButton
}} />

In this snippet, customButton can contain one among three values:

1. A string with one or many class names. If handed, the associated rate will substitute the default clerk-button-fundamental class.
2. A React component that renders a and forwards all props (collectively with formative years). If handed, the default ingredient can also no longer be rendered at all, and as a substitute the handed component could be rendered.
3. A dictionary that adheres to the CSSStyleInterface form. Right here is for completeness more than the rest. If handed, the associated rate could be forwarded to the model prop, and the the default clerk-button-fundamental class could be ignored.

Now, let’s respect the blueprint in which it works for diversified styling libraries.

Tailwind

Simply breeze in Tailwind classes as a string:

SignIn
  theme={{
    primaryButton:  "p-4 rounded"
  }}
/>

CSS modules

When a CSS module is imported, the article automatically returns class names. Simply breeze it in:

import styles from "./Styles.css"
SignIn
  theme={{
    primaryButton:  styles.customButton
  }}
/>

styled-parts

styled-parts works by returning a React component that automatically forwards props to a ingredient – exactly as specified by Clerk:

const CustomButton = styled.button`
  border-radius: 1rem;
  padding: 1rem;
`
SignIn
  theme={{
    primaryButton:  CustomButton
  }}
/>

Chakra

Chakra also offers React