`, the selector has to keep its literal name to match. If yak rewrote
> `.maps` to `.maps_a4f5e`, it would no longer match the real element and your styles would silently
> do nothing.
>
> The same rules for referencing external styles apply here as well. For further documentation visit:
> [Reference external styles](/docs/migration-from-styled-components#reference-external-styles).
See [`globalStyle`](/docs/api#globalstyle) in the API reference.
## Mixins [#mixins]
Mixins are declarations of the `css` utility function. You can declare a variable which holds the css declaration and
use it inside your `styled` declarations.
```jsx title="my-component.tsx"
import { css, styled } from '@yak/react';
const mixin = css`
color: green;
`;
const MyComp = styled.div`
background-color: yellow;
${mixin}
`;
```
You can also make it dynamic, where the props are passed to the mixin.
```jsx title="my-component.tsx"
import { css, styled } from "@yak/react";
const mixin = css`
color: ${(props) => (props.$green ? "green" : "blue")};
`;
const MyComp = styled.div`
background-color: yellow;
${mixin}
`;
```
A mixin doesn't get a class name of its own. At build time its styles are inlined under the class of every component that uses it.
Dynamic parts like the `color` function are copied into that component too, so the component sets the CSS variable itself.
See transformed output
input:
```jsx
const mixin = css`
color: ${(props) => props.$green ? 'green' : 'blue'};
`;
const MyComp = styled.div`
background-color: yellow;
${mixin}
`;
```
output javascript:
```jsx
const mixin = css({
style: {
"--input_mixin__color_m7uBBu": (props) => props.$green ? 'green' : 'blue',
},
});
const MyComp = __yak.__yak_div("input_MyComp_m7uBBu", {
style: {
"--input_MyComp__color_m7uBBu": (props) => props.$green ? 'green' : 'blue',
},
});
```
output CSS:
```css
.input_MyComp_m7uBBu {
background-color: yellow;
color: var(--input_MyComp__color_m7uBBu);
}
```
See [`css`](/docs/api#css) in the API reference.
## Automatic CSS variables [#automatic-css-variables]
You may have noticed that some functions return a `css` block and others return a plain value. If the property name is already
written in the template and only its value is dynamic, return the value directly. The compiler turns these into CSS variables at build time.
**Automatic CSS variables**
typescript:
```tsx twoslash
import { styled } from '@yak/react';
const Box = styled.div<{ $variant: "primary" | "secondary", $color: string }>`
font-size: ${props => props.$variant === "primary" ? "2rem" : "1rem" };
color: ${props => props.$color};
display: flex;
`
```
javascript:
```jsx
import { styled } from '@yak/react';
const Box = styled.div`
font-size: ${props => props.$variant === "primary" ? "2rem" : "1rem" };
color: ${props => props.$color};
display: flex;
`
```
The component sets each variable through its `style` prop. Variable names are scoped to the file and component, so they don't clash with your own custom properties.
See transformed output
**Compiled output**
input:
```jsx
const Box = styled.div`
font-size: ${props => props.$variant === "primary" ? "2rem" : "1rem" };
color: ${props => props.$color};
display: flex;
`
```
output javascript:
```jsx
const Box = __yak.__yak_div("input_Box_m7uBBu", {
style: {
"--input_Box__font-size_m7uBBu": props => props.$variant === "primary" ? "2rem" : "1rem",
"--input_Box__color_m7uBBu": props => props.$color,
},
});
```
output CSS:
```css
.input_Box_m7uBBu {
font-size: var(--input_Box__font-size_m7uBBu);
color: var(--input_Box__color_m7uBBu);
display: flex;
}
```
## Theming [#theming]
Theming lets you pass the same values to many components, which matters more as your application grows.
### Static Design Tokens vs Dynamic Context [#static-design-tokens-vs-dynamic-context]
For static design tokens like colors, spacing, typography, and other unchanging design values, you often don't need a context at all. You can declare and import them anywhere in your application:
```tsx
// theme.ts
export const colors = {
primary: "#009688",
secondary: "#ff5722",
background: "#ffffff",
};
export const spacing = {
xs: "4px",
sm: "8px",
md: "16px",
lg: "32px",
};
// Button.tsx
import { styled } from "@yak/react";
import { colors, spacing } from "./theme";
const Button = styled.button`
background: ${colors.primary};
padding: ${spacing.md};
`;
```
This approach has better performance because these values can be extracted and optimized during build time, whereas context values are resolved at runtime.
### Dynamic Theming with Context [#dynamic-theming-with-context]
Use the context approach described below when you need dynamic theming that changes based on user preferences, server state, or runtime conditions. yak integrates it for both Server Components and Client Components, with no difference in usage. Wrap your root with `YakThemeProvider` and add a `yak.context.ts` file to your root directory.
```tsx title="yak.context.ts"
import { cookies } from "next/headers";
export async function getYakThemeContext() {
const cookieStore = await cookies();
return {
brandName: cookieStore.get("brand")?.value ?? "myDefaultBrand",
highContrast: cookieStore.get("highContrast")?.value === "true",
};
}
declare module "@yak/react" {
export interface YakTheme extends Awaited
> {}
}
```
`getYakThemeContext()` can be async, so you can await request APIs like `cookies()` and `headers()` inside it.
yak resolves the promise with React's `use()` hook and passes the finished theme object to your styled components.
Your template functions always receive a plain, synchronous `theme`.
Once this context file is in place, you can access the theme props on every component.
**Dynamic theming**
typescript:
```tsx twoslash
//@noErrors
const getMyBrandName: () => string | undefined = () => "test";
const isNewDesign: () => boolean | undefined = () => true;
export async function getYakThemeContext() {
return {
brandName: getMyBrandName() ?? "myDefaultBrand",
featureFlags: {
newDesign: isNewDesign() ?? false,
},
};
}
declare module "@yak/react" {
export interface YakTheme extends Awaited> {}
}
// ---cut---
import { styled, css } from '@yak/react';
const Button = styled.button`
display: block;
${({theme}) => theme.brandName === 'myFancyBrand'
? css`
color: black;
background-color: white;
`
: css`
color: blue;
background-color: white;
`}
`;
```
javascript:
```jsx
import { styled, css } from '@yak/react';
const Button = styled.button`
display: block;
${({theme}) => theme.brandName === 'myFancyBrand'
? css`
color: black;
background-color: white;
`
: css`
color: blue;
background-color: white;
`}
`;
```
See [Theming](/docs/api#theming) in the API reference for `useTheme`, `YakThemeProvider` and `yak.context.ts`.
## CSS Prop [#css-prop]
yak supports the `css` prop out of the box, a shorthand for adding styles to an element. Like inline styles,
it lets you write local styles for certain elements on your page. Unlike inline styles, it lets you use
selectors that target wrapped elements.
```jsx title="my-component.tsx"
import { css } from "@yak/react";
const Component = () => {
return (
Hello there!
);
};
```
It's meant for simple styling requirements, where you don't have to think about a name for a specialized component.
The `css` prop is allowed on any element that can accept `className` and `style`.
Its value has to be styles written in place: a `css` template or an `atoms()` call and logical combinations of them.
Everything else fails the build, because yak only compiles the styles it sees on the element.
To combine several styles, nest them in one template instead of passing an array:
```jsx title="my-component.tsx"
const base = css`
color: red;
`;
const highlight = css`
font-weight: bold;
`;
const Component = () => {
return (
Hello there!
);
};
```
Set the `strictCssProp` option to `false` to leave unsupported values untouched instead, for
example when another library on the same element owns the `css` prop.
If you prefer working with the utility first approach, you can use our `atoms` function in conjunction with the `css` prop.
```jsx title="my-component.tsx"
import { atoms } from "@yak/react";
const Component = (props) => {
return Hello there!
;
};
```
### TypeScript [#typescript]
To get the correct types, add the following line to the top of the file:
```tsx title="my-component.tsx"
/** @jsxImportSource @yak/react */ // [!code hl]
import { css } from "@yak/react";
const Component = () => {
return (
Hello there!
);
};
```
Or add this to your `tsconfig.json` and all your css props will have the correct types.
```json title="tsconfig.json"
{
"compilerOptions": {
"jsxImportSource": "@yak/react" // [!code hl]
}
}
```
See [the css prop](/docs/api#the-css-prop) in the API reference.
## Cross-File Imports [#cross-file-imports]
yak supports importing constants, mixins, and selectors from normal modules or `.yak` files. This works consistently across all bundlers (webpack, Turbopack, Rsbuild and Vite).
### Build-Time Constants with `.yak` Files [#build-time-constants-with-yak-files]
`.yak.ts` / `.yak.tsx` files are evaluated at build time, which means you can use real JavaScript logic to compute values that then become part of your static CSS. This is the key difference from ordinary `.ts` files. You can map, iterate, and calculate at build time.
```tsx title="theme/spacing.yak.ts"
export const spacing = {
xs: "4px",
sm: "8px",
md: "16px",
lg: "32px",
};
export const spacingTokens = Object.entries(spacing).reduce(
(acc, [key, value]) => ({
...acc,
[key]: `padding: ${value}; margin: ${value};`,
}),
{} as Record,
);
```
```tsx title="components/Box.tsx"
import { styled, css } from "@yak/react";
import { spacingTokens } from "../theme/spacing.yak";
const Box = styled.div`
${css`
${spacingTokens.sm}
`}
${css`
${spacingTokens.md}
`}
`;
```
Here `spacingTokens` is computed at build time: an ordinary `.ts` file would keep `Object.entries()` and `.reduce()` as runtime code, but a `.yak` file evaluates these expressions and inlines the final object. The resulting CSS contains fully static class names, which means no JavaScript runs for these styles at runtime, even though their values were computed with array operations. You can reference any key like `spacingTokens.sm` as a build-time constant.
This also works for generating media query ranges, animation durations from a config, or any other calculated value.
### Importing Mixins Across Files [#importing-mixins-across-files]
You can also import CSS mixins defined with `css` from other regular modules:
```tsx title="mixins.tsx"
import { css } from "@yak/react";
export const truncate = css`
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
`;
```
```tsx title="components/Label.tsx"
import { styled } from "@yak/react";
import { truncate } from "../mixins";
const Label = styled.span`
${truncate}
max-width: 200px;
`;
```
## Generic Yak Component [#generic-yak-component]
If you use yak to wrap a generic component, you can use the `GenericYakComponentOf` component to preserve the type of your component while still being able to use it as a regular yak component.
```tsx title="my-generic-component.tsx" twoslash
import { type ReactElement } from "react";
import { type GenericYakComponentOf, styled } from "@yak/react";
type GenericComponentType = (props: T) => ReactElement;
const MyGenericComponent: GenericComponentType = (props) => hello
;
const StyledComponent = styled(MyGenericComponent)`
color: red;
` as GenericYakComponentOf;
// usage
myProp="test" />;
```
This also works for cases where you want to add properties that are not part of the generic component's props.
```tsx title="my-generic-component.tsx" twoslash
import { type ReactElement } from "react";
import { type GenericYakComponentOf, styled } from "@yak/react";
type GenericComponentType = (props: T) => ReactElement;
const MyGenericComponent: GenericComponentType = (props) => hello
;
type MyAdditionalProps = {
additionalProp: string;
};
const StyledComponent = styled(MyGenericComponent)`
color: red;
` as GenericYakComponentOf;
// usage
myProp="test" additionalProp="me" />;
```
See [Types](/docs/api#types) in the API reference.