Applying styles
With CSS Hooks, styling stays in the style prop. The mergeStyles and on
functions make that possible. This guide explains how they work together to
construct style objects with conditional overrides.
src/button.tsximport { and, mergeStyles, on } from "./css"; export function Button() { return ( <button style={mergeStyles( { background: "#666", color: "white", transition: "background 150ms, transform 75ms", }, on(and("@media (hover: hover)", "&:hover"), { background: "#009", }), on("&:hover", { transform: "scale(0.98)", }), )} > Save changes </button> ); }
Style object composition
The mergeStyles function processes style objects from left to right. Each
object’s properties move to the end of the result, overriding matching
properties from earlier objects. mergeStyles also resolves each conditional
property against the value it overrides.
Warning Do not use object spread instead of the
mergeStylesfunction when combining base and conditional styles. Object spread does not resolve conditional property fallback values.
Conditional overrides
The on function encodes a hook or condition in a style object. mergeStyles
then resolves each declaration’s fallback from the corresponding value
accumulated from earlier style object arguments.
In the preceding example, on(and("@media (hover: hover)", "&:hover"), ...)
changes the background on hover-capable devices, while on("&:hover", ...)
scales the button on any device.
Nesting conditions
Because on returns a plain style object, calls can be nested. The declarations
apply only when every enclosing condition matches:
typescripton("@media (hover: hover)", on("&:hover", { background: "#009" }))
This is equivalent to:
typescripton(and("@media (hover: hover)", "&:hover"), { background: "#009" })
Use mergeStyles inside an on call to group declarations and nested overrides
under a single condition:
typescriptmergeStyles( { background: "#eee", color: "#333" }, on( "@media (hover: hover)", mergeStyles( { background: "#ddd" }, on("&:hover", { color: "#009" }), ), ), )
Override priority
The mergeStyles function prioritizes later arguments over earlier ones. This
means that conditional styles should be ordered from broader conditions to more
specific ones. Consumer styles (for example, the style prop value passed to a
custom component) should generally be passed as the last argument so internal
component styles do not override them unexpectedly.
typescript<button style={mergeStyles( { background: "#666" }, on("&:hover", { background: "#009" }), on("&:active", { background: "#900" }), on("&:disabled", { background: "#aaa" }), consumerStyle, )} />
This example shows how order matters. The :hover and :disabled
pseudo-classes can both be active at the same time, but in that case the
disabled style should usually override the hover style. Likewise, the pressed
style should generally be prioritized over the hover style when the element is
pressed.
The final consumerStyle argument represents a value passed to a custom
component’s style prop. It overrides the previous value for each property
unconditionally.
Property conflicts
Certain combinations of CSS properties can produce unexpected results at runtime. Notable conflicts include shorthand properties and their longhand equivalents, physical and logical properties that affect the same edge, and aliases. Avoid mixing these properties across base styles and overrides.
The TypeScript types for the React, Preact, Solid, and Qwik integrations report
these conflicts in calls to mergeStyles.
Conflict checking requires the specific keys of each style object to be
retained. If you annotate a reusable style with a broad framework type such as
CSSProperties, use satisfies instead:
typescriptconst baseStyle = { color: "black", } satisfies CSSProperties;
This protection is compile-time only. Custom integrations built directly with
@css-hooks/core can enable conflict checking by supplying a property-conflict
map.