API reference

This page lists everything @yak/react exports. Each entry links to the Features page, which explains it with more examples. The Solid package exports the same API with a few Solid-shaped differences.

Styling

All of these come from the package root:

import { styled, css, keyframes, globalStyle, atoms } from "@yak/react";

styled

Creates a styled component from an HTML tag, a custom element or another component. Interpolations can read props and the theme. See Static CSS and Dynamic styles.

const Button = styled.button<{ $primary?: boolean }>`
  color: ${({ $primary }) => ($primary ? "white" : "black")};
`;

// wrap any component that accepts className and style
const Fancy = styled(Link)`
  text-decoration: none;
`;

// default props with .attrs()
const Submit = styled.button.attrs({ type: "submit" })`
  font-weight: bold;
`;

css

Creates a reusable block of styles, a mixin. Use it inside styled, inside the css prop or in conditions. See Mixins.

const truncate = css`
  overflow: hidden;
  text-overflow: ellipsis;
`;

keyframes

Creates a CSS animation and returns its name, which you use in an animation declaration. See Animations.

const fadeIn = keyframes`
  from { opacity: 0; }
  to { opacity: 1; }
`;

globalStyle

Adds styles that don't belong to a component, like resets or :root variables. Call it at the top level of a module, because it is a statement, not a component. See Global styles.

globalStyle`
  body {
    margin: 0;
  }
`;

atoms

Adds existing utility classes, for example from Tailwind, inside styled, css or the css prop. Falsy values are skipped. See Compatible with utility-first CSS frameworks.

<div css={atoms("flex gap-4", props.active && "bg-blue-500")} />

The css prop

With @yak/react as the JSX import source, every HTML element accepts a css prop with a css template, an atoms() call or a falsy value. Components accept it too, as long as their props include className and style. See CSS Prop.

{
  "compilerOptions": {
    "jsxImportSource": "@yak/react"
  }
}

Any other value, like an object or a string, fails the build. To leave such values to another library, set strictCssProp to false.

Theming

yak.context.ts

The plugins look for a yak.context file (.ts, .tsx, .js or .jsx) in your project root and use its getYakThemeContext export as the theme. Set contextPath to use another file. The function can be async. See Theming.

export function getYakThemeContext() {
  return { highContrast: false };
}

declare module "@yak/react" {
  export interface YakTheme extends ReturnType<typeof getYakThemeContext> {}
}

useTheme

Returns the current theme. In a client component it reads it from YakThemeProvider, and in a React Server Component it calls getYakThemeContext directly.

import { useTheme } from "@yak/react";

const theme = useTheme();

YakThemeProvider

Provides the theme to the components below it. In a Server Component, such as your root layout, it takes no theme prop and reads the theme from getYakThemeContext:

import { YakThemeProvider } from "@yak/react";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <YakThemeProvider>{children}</YakThemeProvider>
      </body>
    </html>
  );
}

In a client-only app, for example with Vite, pass the theme yourself. @yak/react/context/baseContext points to your yak.context.ts, because each plugin sets an alias for it:

import { YakThemeProvider } from "@yak/react";
import { getYakThemeContext } from "@yak/react/context/baseContext";

<YakThemeProvider theme={getYakThemeContext()}>{children}</YakThemeProvider>;

Types

Bundler plugins

withYak (Next.js)

Wraps your Next.js config and sets up yak for webpack and Turbopack. Pass yak options as the first argument, or only the Next.js config. It also accepts a config function, sync or async.

import { withYak } from "@yak/react/withYak";

export default withYak({ prefix: "app" }, nextConfig);
// or without options:
export default withYak(nextConfig);

viteYak (Vite)

Add it before the React plugin. See the Vite guide.

import { viteYak } from "@yak/react/vite";

export default defineConfig({
  plugins: [viteYak(), react()],
});

pluginYak (Rsbuild)

See the Rsbuild guide.

import { pluginYak } from "@yak/react/rsbuild";

export default defineConfig({
  plugins: [pluginReact(), pluginYak()],
});

Plugin options

withYak, viteYak, pluginYak and the Solid plugin take the same options. The type is YakConfigOptions, exported from @yak/react/withYak and @yak/react/rsbuild.

viteYak and the Solid plugin take two more options:

The Storybook addon supports contextPath, minify, prefix and displayNames.

Other entry points