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, andnotinstead of defining them in thecreateHooksconfiguration.
Complete these steps:
- Replace the configuration object with the values of the existing
hooksobject. - Replace each reference to a simple v2 alias with its corresponding hook
string. For example, replace
$("hover", styles)withon("&:hover", styles). - 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.tsexport 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:
pipefrom Remedapipefrom fp-tspipeIntofrom ts-functional-pipe
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:
- Replace
csswithpipe. - Move the
onarray’s contents outside of the style object and pass them as additional inputs topipeafter the style object. - Remove the
onfield from the style object. - Update
$function calls to use the new functionon. - Import
onfrom yourcss.tsmodule. Importand,or, andnotwhen 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.tsmodule.