CSS Hooks
Documentation
Source on GitHub

Migrating to v3

CSS Hooks v3 accepts hook strings instead of a configuration object and uses a pipeline function to apply conditional styles.

To migrate from v2, update your styling module’s exports, replace complex hooks with reusable conditions, and replace calls to the css function with a pipeline. Choose a pipeline implementation before updating inline styles.

New exports

In v2, the return value of createHooks included a css function. In v3, on replaces css, and and, or, and not construct complex conditions. Export these functions from your css.ts module.

src/css.ts
-export const { styleSheet, css } = createHooks(/* ... */); +export const { styleSheet, on, and, or, not } = createHooks(/* ... */);

Keep exporting styleSheet. Components will import on and the condition functions they use instead of importing css.

Simplified initialization

In v2, createHooks accepted a configuration object that contained a hook map and several options. The v3 on function has a smaller scope than the css function it replaces, so v3 removes those configuration options.

The initialization API changes in two ways:

  • Pass hook strings directly to createHooks. v3 does not use aliases.
  • Define complex conditions with and, or, and not instead of defining them in the createHooks configuration.

Complete these steps:

  1. Replace the configuration object with the values of the existing hooks object.
  2. Replace each reference to a simple v2 alias with its corresponding hook string. For example, replace $("hover", styles) with on("&:hover", styles).
  3. Replace each complex hook with the individual hook strings that compose it.
src/css.ts
-export const {/* ... */} = createHooks({ - hooks: ({ or }) => ({ - "&:hover": "&:hover", - "&:intent": or("&:hover", "&:focus"), - }), - sort: { - properties: true, - conditionalStyles: true, - }, - fallback: "revert-layer", - debug: true, -}); +export const {/* ... */} = createHooks("&:hover", "&:focus");

The v3 call declares &:hover and &:focus directly. It omits the v2 aliases, sorting options, fallback option, and debug option.

Defining reusable conditions

Replace each globally defined complex v2 hook with a condition created by and, or, or not. Export the condition from your css.ts module so that components can reuse it.

Example

src/css.ts
export const intent = or("&:hover", "&:focus");

The intent export preserves the v2 &:intent condition without declaring an alias. Components can pass intent to on.

Pipeline function

The v3 API uses a pipeline function to apply conditional style transforms in order. Use a pipeline function from a utility library such as:

If you do not want to install a third-party library, copy this implementation of a pipe function.

The pipeline must pass the base style object through each on transform from left to right. Keep that order when you migrate each css call.

Updating inline styles

Update each inline style that uses the v2 css function:

  1. Replace css with pipe.
  2. Move the on array’s contents outside of the style object and pass them as additional inputs to pipe after the style object.
  3. Remove the on field from the style object.
  4. Update $ function calls to use the new function on.
  5. Import on from your css.ts module. Import and, or, and not when the style uses them.
diff
-import { css } from "./css"; +import { pipe } from "remeda"; // or from fp-ts, etc. +import { on, or } from "./css"; function HelloWorld() { return ( <button - style={css({ - color: "black", - on: ($, { or }) => [ - $(or("&:hover", "&:focus"), { - color: "blue", - }), - $("&:active", { - color: "red", - }), - ], - })} + style={pipe( + { + color: "black", + }, + on(or("&:hover", "&:focus"), { + color: "blue", + }), + on("&:active", { + color: "red", + }), + )} > Hello World </button> ); }

pipe starts with the base style object. Each on call then applies its color override when its condition matches. Keeping the on calls in their original array order preserves the v2 override order.

Note Replace every reference to a v2 alias. Use the declared hook string for a simple alias. For a complex alias, use a reusable condition exported from your css.ts module.