nishiki

Styling API

There are three ways to apply styles, and they all take the same style objects:

  • css prop on host elements: style objects, compiled styles, null/false, or lists of them.
  • styled(component, styles) returns a component that accepts className and css.
  • 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, null and undefined.
  • 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.