Setup
CSS Hooks requires a small amount of setup, which may vary slightly depending on your project's architecture. This guide offers a general overview. For specific examples, please see the Quickstart section.
Installation
If you haven't already, you should install one of the framework-specific packages, e.g.
npm install @css-hooks/react
The options currently available are:
@css-hooks/react
@css-hooks/preact
@css-hooks/solid
@css-hooks/qwik
Alternatively, if you are using a different framework, you can simply install
@css-hooks/core
.
The css.ts
module
First, you'll need a module dedicated to configuration/setup for CSS Hooks. You
can choose any file path you'd like, but our typical recommendation is
src/css.ts
.
Obtaining createHooks
From a framework package
If you are using one of the framework packages listed above, then you can simply
import the createHooks
function.
// src/css.ts
import { createHooks } from "@css-hooks/react";
Using `@css-hooks/core` directly
If you are using @css-hooks/core
rather than a framework-specific flavor of
CSS Hooks, then you will first need to create a createHooks
function tailored
to your use case.
In this case, call the buildHooksSystem
function to produce createHooks
:
// src/css.ts
import { buildHooksSystem } from "@css-hooks/core";
const createHooks = buildHooksSystem();
The default createHooks
function has the following characteristics:
- It types style objects as
Record<string, unknown>
, meaning that it doesn't offer much type safety for CSS properties. - It doesn't transform CSS values when converting them to strings; e.g. it
won't automatically append
px
to a length defined as anumber
like some app frameworks do.
If you would like to override the default type for CSS properties, you can pass a generic argument accordingly. For example, here's how you can integrate csstype:
// src/css.ts
import { buildHooksSystem } from "@css-hooks/core";
import type * as CSS from "csstype";
const createHooks = buildHooksSystem<CSS.Properties>();
If you would like to use custom logic for converting values to strings, you can pass this as a callback function:
// 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>>(
(propertyName, value) => {
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
}
},
);
Once you have created your createHooks
function, proceed to the next section.
Creating hooks
Call createHooks
to create and export css
and styleSheet
functions:
- The
css
function allows you to define inline styles enhanced with hooks; and - The
styleSheet
function returns a style sheet (CSS string) required to support the configured hooks.
// src/css.ts
import { createHooks } from "@css-hooks/react";
export const { styleSheet, css } = createHooks({
// TODO: Configure hooks and other options.
});
Please see the Configuration guide for more information.
Adding the style sheet
Now you need to determine where to render the style sheet. Most likely, you'll want to do this in your root component or the entry point for your application, but there are many ways to approach it.
Let's say you want to add the style sheet to an existing App
component. Here's
how to do that:
// src/app.tsx
import { styleSheet } from "./css";
export function App() {
return <HomePage />;
return (
<>
<style dangerouslySetInnerHTML={{ __html: styleSheet() }} />
<HomePage />
</>
);
}
The key here is to call the styleSheet
function and insert the CSS string it
returns into the document (in a <style>
element).
Note
Don't worry about the use of React'sdangerouslySetInnerHTML
prop above: Its scary name is intended to discourage adding untrusted content to the document.
For more examples specific to various frameworks, see the Quickstart section.
Ready to use
Now you're all set to use the css
function in your components. Proceed to the
Usage guide to learn how it works.