CSS Hooks
Documentation
Source on GitHub

Setup

Setting up CSS Hooks is quick and easy, but may vary slightly depending on your project. This guide gives a general overview. For more specific examples, check the Quickstart section.

Installation

First, install the appropriate framework integration package for your project, e.g.

npm install @css-hooks/react

Available options are:

  • @css-hooks/react
  • @css-hooks/preact
  • @css-hooks/solid
  • @css-hooks/qwik

If you're using a different framework, you can simply install the core package:

npm install @css-hooks/core

Pipeline function

You'll also need a generic pipeline utility function, like one of these:

Alternatively, if you prefer not to install a third-party library, you can simply copy this implementation of a pipe function.

The css.ts module

Next, create a module to configure CSS Hooks. A common file path is src/css.ts.

Obtaining createHooks

From a framework integration package

If you're using a framework integration package like @css-hooks/react, you can simply import createHooks:

// src/css.ts

import { createHooks } from "@css-hooks/react";
From the core package

If you're using the core package, create a createHooks function:

// src/css.ts

import { buildHooksSystem } from "@css-hooks/core";

const createHooks = buildHooksSystem();

For extra type safety, you can integrate csstype by passing a generic argument:

// src/css.ts

import { buildHooksSystem } from "@css-hooks/core";
import type * as CSS from "csstype";

const createHooks = buildHooksSystem<CSS.Properties>();

For custom value conversion (e.g. adding px to numbers), pass a callback:

// src/css.ts

import { buildHooksSystem } from "@css-hooks/core";
import type * as CSS from "csstype";
import { isUnitlessNumber } from "unitless";

const createHooks = buildHooksSystem<CSS.Properties<string | number>>(
  (value, propertyName) => {
    switch (typeof value) {
      case "string":
        return value;
      case "number":
        return isUnitlessNumber(propertyName) ? `${value}` : `${value}px`;
      default:
        return null; // return null when the value can't be stringified
    }
  },
);

Creating hooks

Once you have createHooks, use it to generate and export the on, and, or, not, and styleSheet functions:

// src/css.ts

import { createHooks } from "@css-hooks/react";

export const { on, and, or, not, styleSheet } = createHooks(
  "@media (min-width: 1000px)",
  "&:hover",
  /* additional hooks */
);

Please see the Configuration guide for more details about the syntax used to create hooks.

Adding the style sheet

Add the generated style sheet to your app. For example, in your App component:

// src/app.tsx

import { styleSheet } from "./css";

export function App() {
  return <HomePage />;
  return (
    <>
      <style dangerouslySetInnerHTML={{ __html: styleSheet() }} />
      <HomePage />
    </>
  );
}

Note

Despite the name, React's dangerouslySetInnerHTML prop is safe to use for trusted content.

Ready to use

Now you're all set to use conditional styles in your components. Proceed to the Usage guide to learn how.