Hooks and conditions
A hook describes a CSS state that can be used to filter declarations in an element’s style object so that they apply conditionally. Hooks work independently, but they can also serve as building blocks for more advanced conditions. This guide explains how to declare selector, at-rule, and flag hooks and combine them into reusable conditions.
src/css.tsimport { createHooks } from "@css-hooks/react"; export const { on, and, or, not, styleSheet } = createHooks( "&:hover", "&.a", "@media (hover: hover)", "@container (min-width: 400px)", "@scope ([data-theme='dark']) to ([data-theme])", "@supports (height: 100dvh)", "%dark", );
createHooks() returns the styleSheet function, which constructs the plumbing
stylesheet that supports the declared hooks. It also returns the and, or,
and not combinators, which combine hooks into conditions. The returned on
function makes style declarations conditional. See
Applying styles for details.
Selector hooks
A selector hook activates when the element matches its selector logic. Use
selector hooks for the element’s state, reusable class markers, relationships
with ancestors or siblings, and other surrounding context. The & character
represents the styled element. Every selector hook must include it.
typescript"&:hover" // The element is hovered. "&.a" // The element has the reusable class marker "a". ".group:hover &" // The element is inside a hovered .group. ":checked + &" // The element follows a checked input.
At-rule hooks
An at-rule hook activates based on criteria beyond the element’s selector, such as the browsing environment, a container’s size or style, or the element’s own state. CSS Hooks supports these at-rules:
@mediaresponds to the viewport, input devices, and user preferences.@containerresponds to the size or styles of a containing element.@supportschecks whether the browser supports a CSS feature.@scopelimits a condition to a section of the document tree.@starting-styledefines an element’s starting styles when it first renders or changes fromdisplay: noneto a rendered state.
typescript"@media (prefers-reduced-motion: reduce)" // The user requests reduced motion. "@container (min-width: 400px)" // The container is at least 400px wide. "@supports (height: 100dvh)" // The browser supports the dvh unit. "@scope ([data-theme='dark']) to ([data-theme])" // Within a dark-themed donut scope "@starting-style" // The element’s first rendered styles
When an @scope hook includes a scope limit, it forms a donut scope. It
activates for the scope root and its descendants, excluding the limit and its
descendants.
Flag hooks
A flag hook activates when its inherited Boolean state is enabled. Use flags when an entire subtree must respond to shared state, such as a color mode, display density, or a parent’s interaction state. Flags rely on property inheritance, so descendants can respond without receiving presentational state through component props or framework context.
Declare a flag as %<name>. Each flag is disabled by default. See
Flags to learn how to set, override, and invert flag state.
Conditions
The on function accepts a hook or a condition. A condition combines hooks
and other conditions using the and, or, and not combinators.
A single hook covers one criterion, while a condition can express more specific criteria without enlarging the plumbing stylesheet or cluttering autocomplete suggestions with use-case-specific hooks. A hover style, for example, may require both a device that can hover and a hovered element:
typescriptexport const hoverOnly = and("@media (hover: hover)", "&:hover");
The hoverOnly condition activates only when the media query and the :hover
pseudo-class both match.
For best results, keep hooks small and generic so they compose. Export reusable
conditions such as hoverOnly from your styling module.