Styling API
There are three ways to apply styles, and they all take the same style objects:
cssprop on host elements: style objects, compiled styles,null/false, or lists of them.styled(component, styles)returns a component that acceptsclassNameandcss.css(...styles)returns[className, Styles]; render<Styles />next to the element.
The css prop
With the JSX import source set (see Getting started), every host element accepts css:
<p css={{ margin: 0, color: isError ? "crimson" : "seagreen" }}>Saved</p>
styled
styled(component, styles) wraps a host element or a component. The result accepts className and css as well as the wrapped component's props.
styles can also be a function (styleProps, props) => styles. Style props are the props whose names start with $; they reach the function and never reach the element. A styled component that wraps another passes them on, so the inner one's function sees them too.
import { styled } from "nishiki";
type Tone = "info" | "success" | "danger";
const Badge = styled("span", ({ $tone }: { $tone: Tone }) => ({
display: "inline-block",
padding: "2px 10px",
borderRadius: 999,
fontSize: 14,
color: "white",
background: $tone === "danger" ? "#cf222e" : $tone === "success" ? "#1a7f37" : "#0969da",
}));
export default function Badges() {
return (
<div css={{ display: "flex", flexWrap: "wrap", gap: 8 }}>
<Badge $tone="info">Queued</Badge>
<Badge $tone="success">Passed</Badge>
<Badge $tone="danger">Failed</Badge>
</div>
);
}
Wrapping a styled component with styled merges both style objects, so the outer styles always win.
css()
css(...styles) returns a class name and a Styles component that inserts the rules. Use it when you need a class name string, for example for a third-party component, and render <Styles /> next to the element.
Merging
Inputs merge per top-level key, later inputs winning, and null unsets a key:
<div css={[base, isActive && { color: "red" }, { margin: null }]} />
Toggle the checkbox to see the class list change: margin is unset by the last input, and the active styles replace color and background from base.
import { css, type CSSObject } from "nishiki";
import { useState } from "react";
const base: CSSObject = { padding: 12, margin: 8, borderRadius: 6, color: "#1f2328", background: "#eaeef2" };
export default function Merging() {
const [active, setActive] = useState(false);
const [className, Styles] = css(base, active && { color: "white", background: "crimson" }, { margin: null });
return (
<div css={{ display: "grid", gap: 12 }}>
<label css={{ display: "flex", gap: 8, alignItems: "center" }}>
<input type="checkbox" checked={active} onChange={(event) => setActive(event.target.checked)} />
active
</label>
<div className={className}>
<Styles />
<code>className="{className}"</code>
</div>
</div>
);
}
Never join class names from separate calls into one className, and never override a styled component through className: pass its css prop or wrap it with styled.
Style objects
| Key | Meaning |
|---|---|
color, marginTop, ... |
CSS properties in camelCase |
--brand |
Custom properties, passed through untouched |
":hover", "&:focus-visible", ".dark &" |
Nested selectors (& is the element) |
"@media (...)", "@supports (...)", "@container (...)" |
At-rules, which can nest |
Numbers get px unless the property is unitless (lineHeight, opacity, zIndex, ...).
Writing styles that compile
The compiler only compiles literals; everything else keeps working at runtime. To get the most out of it:
- Write values that never change as literals in place, not through variables, helpers or spreads.
- Put spreads and computed keys first and literal keys after them. Everything up to the last spread or computed key stays runtime-only, because only runtime knows what it overrides.
- Keep dynamic values in their own keys; the other literal keys of the same object are still compiled.
What counts as a literal:
- Strings, numbers, template literals without expressions, nested objects of literals,
nullandundefined. - Styles with no runtime part are hoisted to module-level constants, and their result is cached by identity.
There is no evaluator and no cross-file analysis, so every file is transformed on its own, and cached and hot-reloaded per file.