John Doe
john@doe.com
Hello !
```
Page
}
```
### Start the Bamboo build process
Run the CLI tool to scan your JavaScript and TypeScript files for style properties and call expressions.
Hello 🎋!
```
```hbs {5} filename="app/templates/application.hbs"
{{page-title 'TestApp'}}
Welcome to Ember
Hello 🎋!
}
export default IndexPage
export const Head: HeadFC = () => Hello 🎋!
}
```
### Start the development server
Run the following command to start the development server:
Hello 🎋!
```
Hello 🎋!
}
export default Home
```
Welcome to the home page
HomePage
Hello World
Hello 🎋!
}
```
Hello 🎋!
}
export default App
```
Hello 🎋!
}
export default App
```
Hello 🎋!
```
Hello 🎋!
}
export default App
```
Hello 🎋!
```
*': { margin: '2' },
})}
/>
)
}
```
This also works with the supported at-rules (`@media`, `@layer`, `@container`, `@supports`, and `@page`):
```tsx
import { css } from '../styled-system/css'
const App = () => {
return (
)
}
```
## Pseudo Classes
### Hover, Active, Focus, and Disabled
You can style the hover, active, focus, and disabled states of an element using their `_` modifier:
```jsx
```
### First, Last, Odd, Even
You can style the first, last, odd, and even elements of a group using their `_` modifier:
```jsx
{items.map((item) => (
```
## Pseudo Elements
### Before and After
You can style the `::before` and `::after` pseudo elements of an element using their `_before` and `_after` modifier:
```jsx
```
This modifer for every pseudo class modifiers like `_groupHover`, `_groupActive`, `_groupFocus`, and `_groupDisabled`,
etc.
## Sibling Selectors
When you need to style an element based on its sibling element's state or attribute, you can add the `peer` class to the
sibling element, and use any of the `_peer*` modifiers on the target element.
```jsx
```
> Note: This only works for when the element marked with `peer` is a previous siblings, that is, it comes before the
> element you want to start.
## Data Attribute
### LTR and RTL
You can style an element based on the direction of the text using the `_ltr` and `_rtl` modifiers:
```jsx
```
For this to work, you need to set the `dir` attribute on the parent element. In most cases,you can set this on the
`html` element.
> **Note:** Consider using logical css properties like `marginInlineStart` and `marginInlineEnd` instead their physical
> counterparts like `marginLeft` and `marginRight`. This will reduce the need to use the `_ltr` and `_rtl` modifiers.
### State
You can style an element based on its `data-{state}` attribute using the corresponding `_{state}` modifier:
```jsx
/` syntax:
> The default container syntax is `@/`.
```ts
import { css } from '/styled-system/css'
function Demo() {
return (
)
}
```
This will generate the following CSS:
```css
.cq-type_inline-size {
container-type: inline-size;
}
@container (min-width: 60em) {
.\@\/sm:fs_md {
container-type: inline-size;
}
}
```
You can also named container queries:
```ts
import { cq } from 'styled-system/patterns'
function Demo() {
return (
)
}
```
## Reference
Here's a list of all the condition shortcuts you can use in Bamboo:
| Condition name | Selector |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| \_hover | `&:is(:hover, [data-hover])` |
| \_focus | `&:is(:focus, [data-focus])` |
| \_focusWithin | `&:focus-within` |
| \_focusVisible | `&:is(:focus-visible, [data-focus-visible])` |
| \_disabled | `&:is(:disabled, [disabled], [data-disabled], [aria-disabled=true])` |
| \_active | `&:is(:active, [data-active])` |
| \_visited | `&:visited` |
| \_target | `&:target` |
| \_readOnly | `&:is(:read-only, [data-read-only], [aria-readonly=true])` |
| \_readWrite | `&:read-write` |
| \_empty | `&:is(:empty, [data-empty])` |
| \_checked | `&:is(:checked, [data-checked], [aria-checked=true], [data-state="checked"])` |
| \_enabled | `&:enabled` |
| \_expanded | `&:is([aria-expanded=true], [data-expanded], [data-state="expanded"])` |
| \_highlighted | `&[data-highlighted]` |
| \_complete | `&[data-complete]` |
| \_incomplete | `&[data-incomplete]` |
| \_dragging | `&[data-dragging]` |
| \_before | `&::before` |
| \_after | `&::after` |
| \_firstLetter | `&::first-letter` |
| \_firstLine | `&::first-line` |
| \_marker | `&::marker, &::-webkit-details-marker` |
| \_selection | `&::selection` |
| \_file | `&::file-selector-button` |
| \_backdrop | `&::backdrop` |
| \_first | `&:first-child` |
| \_last | `&:last-child` |
| \_only | `&:only-child` |
| \_even | `&:nth-child(even)` |
| \_odd | `&:nth-child(odd)` |
| \_firstOfType | `&:first-of-type` |
| \_lastOfType | `&:last-of-type` |
| \_onlyOfType | `&:only-of-type` |
| \_peerFocus | `.peer:is(:focus, [data-focus]) ~ &` |
| \_peerHover | `.peer:is(:hover, [data-hover]) ~ &` |
| \_peerActive | `.peer:is(:active, [data-active]) ~ &` |
| \_peerFocusWithin | `.peer:focus-within ~ &` |
| \_peerFocusVisible | `.peer:is(:focus-visible, [data-focus-visible]) ~ &` |
| \_peerDisabled | `.peer:is(:disabled, [disabled], [data-disabled], [aria-disabled=true]) ~ &` |
| \_peerChecked | `.peer:is(:checked, [data-checked], [aria-checked=true], [data-state="checked"]) ~ &` |
| \_peerInvalid | `.peer:is(:invalid, [data-invalid], [aria-invalid=true]) ~ &` |
| \_peerExpanded | `.peer:is([aria-expanded=true], [data-expanded], [data-state="expanded"]) ~ &` |
| \_peerPlaceholderShown | `.peer:placeholder-shown ~ &` |
| \_groupFocus | `.group:is(:focus, [data-focus]) &` |
| \_groupHover | `.group:is(:hover, [data-hover]) &` |
| \_groupActive | `.group:is(:active, [data-active]) &` |
| \_groupFocusWithin | `.group:focus-within &` |
| \_groupFocusVisible | `.group:is(:focus-visible, [data-focus-visible]) &` |
| \_groupDisabled | `.group:is(:disabled, [disabled], [data-disabled], [aria-disabled=true]) &` |
| \_groupChecked | `.group:is(:checked, [data-checked], [aria-checked=true], [data-state="checked"]) &` |
| \_groupExpanded | `.group:is([aria-expanded=true], [data-expanded], [data-state="expanded"]) &` |
| \_groupInvalid | `.group:is(:invalid, [data-invalid], [aria-invalid=true]) &` |
| \_indeterminate | `&:is(:indeterminate, [data-indeterminate], [aria-checked=mixed], [data-state="indeterminate"])` |
| \_required | `&:is(:required, [data-required], [aria-required=true])` |
| \_valid | `&:is(:valid, [data-valid])` |
| \_invalid | `&:is(:invalid, [data-invalid], [aria-invalid=true])` |
| \_autofill | `&:autofill` |
| \_inRange | `&:is(:in-range, [data-in-range])` |
| \_outOfRange | `&:is(:out-of-range, [data-outside-range])` |
| \_placeholder | `&::placeholder, &[data-placeholder]` |
| \_placeholderShown | `&:is(:placeholder-shown, [data-placeholder-shown])` |
| \_pressed | `&:is([aria-pressed=true], [data-pressed])` |
| \_selected | `&:is([aria-selected=true], [data-selected])` |
| \_grabbed | `&:is([aria-grabbed=true], [data-grabbed])` |
| \_underValue | `&[data-state=under-value]` |
| \_overValue | `&[data-state=over-value]` |
| \_atValue | `&[data-state=at-value]` |
| \_default | `&:default` |
| \_optional | `&:optional` |
| \_open | `&:is([open], [data-open], [data-state="open"], :popover-open)` |
| \_closed | `&:is([closed], [data-closed], [data-state="closed"])` |
| \_fullscreen | `&:is(:fullscreen, [data-fullscreen])` |
| \_loading | `&:is([data-loading], [aria-busy=true])` |
| \_hidden | `&:is([hidden], [data-hidden])` |
| \_current | `&:is([aria-current=true], [data-current])` |
| \_currentPage | `&[aria-current=page]` |
| \_currentStep | `&[aria-current=step]` |
| \_today | `&[data-today]` |
| \_unavailable | `&[data-unavailable]` |
| \_rangeStart | `&[data-range-start]` |
| \_rangeEnd | `&[data-range-end]` |
| \_now | `&[data-now]` |
| \_topmost | `&[data-topmost]` |
| \_motionReduce | `@media (prefers-reduced-motion: reduce)` |
| \_motionSafe | `@media (prefers-reduced-motion: no-preference)` |
| \_print | `@media print` |
| \_landscape | `@media (orientation: landscape)` |
| \_portrait | `@media (orientation: portrait)` |
| \_dark | `.dark &` |
| \_light | `.light &` |
| \_osDark | `@media (prefers-color-scheme: dark)` |
| \_osLight | `@media (prefers-color-scheme: light)` |
| \_highContrast | `@media (forced-colors: active)` |
| \_lessContrast | `@media (prefers-contrast: less)` |
| \_moreContrast | `@media (prefers-contrast: more)` |
| \_ltr | `:where([dir=ltr], :dir(ltr)) &` |
| \_rtl | `:where([dir=rtl], :dir(rtl)) &` |
| \_scrollbar | `&::-webkit-scrollbar` |
| \_scrollbarThumb | `&::-webkit-scrollbar-thumb` |
| \_scrollbarTrack | `&::-webkit-scrollbar-track` |
| \_horizontal | `&[data-orientation=horizontal]` |
| \_vertical | `&[data-orientation=vertical]` |
| \_icon | `& :where(svg)` |
| \_starting | `@starting-style` |
| \_noscript | `@media (scripting: none)` |
| \_invertedColors | `@media (inverted-colors: inverted)` |
## Custom conditions
Bamboo lets you create your own conditions, so you're not limited to the ones in the default preset. Learn more about
customizing conditions [here](/docs/customization/conditions).
---
## The extend keyword
What is and how to to use the extend keyword
The `extend` keyword allows you to extend the default Bamboo configuration. It is useful when you want to add your own
customizations to Bamboo, without erasing the default `presets` values (`conditions`, `tokens`, `utilities`, etc).
It will (deeply) merge your customizations with the default ones, instead of replacing them.
The `extend` keyword allows you to extend the following parts of Bamboo:
- [conditions](/docs/customization/conditions)
- [theme](/docs/customization/theme)
- [recipes](/docs/concepts/recipes) (included in theme)
- [patterns](/docs/customization/patterns)
- [utilities](/docs/customization/utilities)
- [globalCss](/docs/concepts/writing-styles#global-styles)
- [staticCss](/docs/guides/static)
> These keys are all allowed in [presets](/docs/customization/presets).
## Example
After running the `bamboo init` command you should see something similar to this:
```ts
import { defineConfig } from '@bamboocss/dev'
export default defineConfig({
// ...
// Useful for theme customization
theme: {
extend: {}, // 👈 it's already there! perfect, now you just need to add your customizations in this object
},
// ...
})
```
Let's say you want to add a new color to the default theme. You can do it like this:
```ts
import { defineConfig } from '@bamboocss/dev'
export default defineConfig({
theme: {
extend: {
colors: {
primary: { value: '#ff0000' },
},
},
},
})
```
This will add a new color to the default theme, without erasing the other ones.
Now, let's say we want to create new property `br` that applies a border radius to an element.
```ts
import { defineConfig } from '@bamboocss/dev'
export default defineConfig({
utilities: {
extend: {
br: {
className: 'rounded', // css({ br: "sm" }) => rounded-sm
values: 'radii', // connect values to the radii tokens
transform(value) {
return { borderRadius: value }
},
},
},
},
})
```
What if this utility was coming from a preset (`@acme/my-preset`) ? You can extend any specific part, as it will be
deeply merged with the existing one:
```ts
import { defineConfig } from '@bamboocss/dev'
export default defineConfig({
presets: ['@acme/my-preset']
utilities: {
extend: {
br: {
className: 'br' // css({ br: "sm" }) => br-sm
}
}
}
})
```
## Removing something from a preset
Let's say you want to remove the `br` utility from the `@acme/my-preset` preset. You can do it like this:
```ts
import { defineConfig } from '@bamboocss/dev'
import myPreset from '@acme/my-preset'
const { br, ...utilities } = myPreset.utilities
export default defineConfig({
presets: ['@acme/my-preset']
utilities: {
extend: {
...utilities, // 👈 we still want the other utilities from this preset
// your customizations here
}
}
})
```
## Removing something from the base presets
Let's say you want to remove the `stack` pattern from the `@bamboocss/preset-base` preset (included by default).
You can pick only the parts that you need with and spread the rest, like this:
```ts
import bambooBasePreset from '@bamboocss/preset-base'
// omitting stack here
const { stack, ...bambooBasePresetPatterns } = bambooBasePreset.patterns
export default defineConfig({
presets: ['@bamboocss/preset-bamboo'], // 👈 we still want the tokens, breakpoints and textStyles from this preset
// ⚠️ we need to eject to prevent the `@bamboocss/preset-base` from being resolved
// https://bamboocss.com/docs/customization/presets#which-bamboo-presets-will-be-included-
eject: true,
patterns: {
extend: {
...bambooBasePresetPatterns,
// your customizations here
},
},
})
```
## Minimal setup
If you want to use Bamboo with the bare minimum, without any of the defaults, you can read more about it
[here](/docs/guides/minimal-setup)
## FAQ
### Why is my preset overriding the base one, even after adding it to the array?
You might have forgotten to include the `extend` keyword in your config. Without `extend`, your preset will completely
replace the base one, instead of merging with it.
---
## Global Styles
How to work with resets, global styles, and global CSS variables in Bamboo.
Bamboo groups global styles into reset and base layers so you can control defaults predictably and override them safely.
## Layers overview
- **@layer reset**: Preflight/reset styles, enabled with `preflight`.
- **@layer base**: Your additional global styles via `globalCss`.
> See also: [Cascade layers](/docs/concepts/cascade-layers)
## Reset (preflight)
Enable or scope the reset styles.
```ts filename="bamboo.config.ts"
import { defineConfig } from '@bamboocss/dev'
export default defineConfig({
preflight: true,
})
```
Scope and level:
```ts filename="bamboo.config.ts"
import { defineConfig } from '@bamboocss/dev'
export default defineConfig({
preflight: { scope: '.extension', level: 'element' },
})
```
## Exposed global CSS variables
These variables are used by the reset and defaults. Set them in `globalCss`:
- `--global-font-body`
- `--global-font-mono`
- `--global-color-border`
- `--global-color-placeholder`
- `--global-color-selection`
- `--global-color-focus-ring`
## Setting global styles (base)
Use `globalCss` to define additional global styles and set variables.
```ts filename="bamboo.config.ts"
import { defineConfig } from '@bamboocss/dev'
export default defineConfig({
// ...
globalCss: {
html: {
'--global-font-body': 'Inter, sans-serif',
'--global-font-mono': 'Mononoki Nerd Font, monospace',
'--global-color-border': 'colors.gray.400',
'--global-color-placeholder': 'rgba(0,0,0,0.5)',
'--global-color-selection': 'rgba(0,115,255,0.3)',
'--global-color-focus-ring': 'colors.blue.400',
},
},
})
```
### Theming patterns
You can set variables on `:root`, a `.dark` class, or via media queries.
```css
:root {
--global-color-border: oklch(0.8 0 0);
}
.dark {
--global-color-border: oklch(0.72 0 0);
}
@media (prefers-color-scheme: dark) {
:root {
--global-color-border: oklch(0.72 0 0);
}
}
```
## Custom global variables (`globalVars`)
Define additional global CSS variables or `@property` entries.
```ts filename="bamboo.config.ts"
import { defineConfig } from '@bamboocss/dev'
export default defineConfig({
globalVars: {
'--button-color': {
syntax: '',
inherits: false,
initialValue: 'blue',
},
},
})
```
> Keys from `globalVars` are suggestable in style objects and generated near your tokens at `cssVarRoot`.
## Troubleshooting
- **Global styles aren't applied:** Confirm `preflight` is enabled (if you expect reset), and ensure your selector
(`html`, `:root`, `.dark`, etc.) matches the element where variables are set.
- **Global styles are overridden by utilities or component styles:** Verify layer order and specificity. Ensure
`@layer reset` and `@layer base` are emitted before utilities. If you customize insertion or injection order (SSR,
framework plugins), preserve `@layer` order so globals are not overridden.
---
## Bamboo Integration Hooks
Leveraging hooks in Bamboo to create custom functionality.
Bamboo hooks can be used to add new functionality or modify existing behavior during certian parts of the compiler
lifecycle.
Hooks are mostly callbacks that can be added to the bamboo config via the `hooks` property, or installed via `plugins`.
Here are some examples of what you can do with hooks:
- modify the resolved config (`config:resolved`), like strip out tokens or keyframes.
- modify presets after they are resolved (`preset:resolved`), like removing specific tokens or theme properties from a
preset.
- tweak the design token or classname engine (`tokens:created`, `utility:created`), like prefixing token names, or
customizing the hashing function
- transform a source file to a `tsx` friendly syntax before it's parsed (`parser:before`) so that Bamboo can
automatically extract its styles usage
- create your own styles parser (`parser:before`, `parser:after`) using the file's content so that Bamboo could be used
with any templating language
- alter the generated JS and DTS code (`codegen:prepare`)
- modify the generated CSS (`cssgen:done`), allowing all kinds of customizations like removing the unused CSS variables,
etc.
- restrict `strictTokens` to a specific set of token categories, ex: only affect `colors` and `spacing` tokens and
therefore allow any value for `fontSizes` and `lineHeights`
## Examples
### Prefixing token names
This is especially useful when migrating from other css-in-js libraries, [like Stitches.](/docs/migration/stitches)
```ts
import { defineConfig } from '@bamboocss/dev'
export default defineConfig({
// ...
hooks: {
'tokens:created': ({ configure }) => {
configure({
formatTokenName: (path) => '$' + path.join('-'),
})
},
},
})
```
### Customizing the hash function
When using the [`hash: true`](/docs/concepts/writing-styles) config property, you can customize the function used to
hash the classnames.
```ts
export default defineConfig({
// ...
hash: true,
hooks: {
'utility:created': ({ configure }) => {
configure({
toHash: (paths, toHash) => {
const stringConds = paths.join(':')
const splitConds = stringConds.split('_')
const hashConds = splitConds.map(toHash)
return hashConds.join('_')
},
})
},
},
})
```
### Modifying the config
Here's an example of how to leveraging the provided `utils` functions in the `config:resolved` hook to remove the
`stack` pattern from the resolved config.
```ts
import { defineConfig } from '@bamboocss/dev'
export default defineConfig({
// ...
hooks: {
'config:resolved': ({ config, utils }) => {
return utils.omit(config, ['patterns.stack'])
},
},
})
```
### Modifying presets
You can use the `preset:resolved` hook to modify presets after they are resolved. This is useful for customizing or
filtering out parts of a preset.
```ts
import { defineConfig } from '@bamboocss/dev'
export default defineConfig({
// ...
hooks: {
'preset:resolved': ({ utils, preset, name }) => {
if (name === '@bamboocss/preset-bamboo') {
return utils.omit(preset, ['theme.tokens.colors', 'theme.semanticTokens.colors'])
}
return preset
},
},
})
```
### Configuring JSX extraction
Use the `matchTag` / `matchTagProp` functions to customize the way Bamboo extracts your JSX.
This can be especially useful when working with libraries that have properties that look like CSS properties but are not
and should be ignored.
Let's see a Radix UI example where the `Select.Content` component has a `position` property that should be ignored:
```js
// Here, the `position` property will be extracted because `position` is a valid CSS property, but we don't want that
```
```ts
export default defineConfig({
// ...
hooks: {
'parser:before': ({ configure }) => {
configure({
// ignore the Select.Content entirely
matchTag: (tag) => tag !== 'Select.Content',
// ...or specifically ignore the `position` property
matchTagProp: (tag, prop) => tag === 'Select.Content' && prop !== 'position',
})
},
},
})
```
### Remove unused variables from final css
Here's an example of how to transform the generated css in the `cssgen:done` hook.
```ts file="bamboo.config.ts"
import { defineConfig } from '@bamboocss/dev'
import { removeUnusedCssVars } from './remove-unused-css-vars'
import { removeUnusedKeyframes } from './remove-unused-keyframes'
export default defineConfig({
// ...
hooks: {
'cssgen:done': ({ artifact, content }) => {
if (artifact === 'styles.css') {
return removeUnusedCssVars(removeUnusedKeyframes(content))
}
},
},
})
```
Get the snippets for the removal logic from our Github Sandbox in the
[remove-unused-css-vars](https://github.com/bamboocss/bamboo/blob/main/sandbox/vite-ts/remove-unused-css-vars.ts) and
[remove-unused-keyframes](https://github.com/bamboocss/bamboo/blob/main/sandbox/vite-ts/remove-unused-keyframes.ts)
files.
> Note: Using this means you can't use the JS function [`token.var`](/docs/guides/dynamic-styling#using-tokenvar) (or
> [token(xxx)](/docs/guides/dynamic-styling#using-token) where `xxx` is the path to a
> [semanticToken](/docs/theming/tokens#semantic-tokens)) from `styled-system/tokens` as the CSS variables will be
> removed based on the usage found in the generated CSS
## Sharing hooks
Hooks can be shared as a snippet or as a `plugin`. Plugins are currently simple objects that contain a `name` associated
with a `hooks` object with the same structure as the `hooks` object in the config.
> Plugins differ from `presets` as they can't be extended, but they will be called in sequence in the order they are
> defined in the `plugins` array, with the user's config called last.
```ts
import { defineConfig } from '@bamboocss/dev'
export default defineConfig({
// ...
plugins: [
{
name: 'token-format',
hooks: {
'tokens:created': ({ configure }) => {
configure({
formatTokenName: (path) => '$' + path.join('-'),
})
},
},
},
],
})
```
## Reference
```ts
export interface BambooHooks {
/**
* Called when the config is resolved, after all the presets are loaded and merged.
* This is the first hook called, you can use it to tweak the config before the context is created.
*/
'config:resolved': (args: ConfigResolvedHookArgs) => MaybeAsyncReturn
/**
* Called when a preset is resolved, allowing you to modify it before it's merged into the config.
*/
'preset:resolved': (args: PresetResolvedHookArgs) => MaybeAsyncReturn
/**
* Called when the token engine has been created
*/
'tokens:created': (args: TokenCreatedHookArgs) => MaybeAsyncReturn
/**
* Called when the classname engine has been created
*/
'utility:created': (args: UtilityCreatedHookArgs) => MaybeAsyncReturn
/**
* Called when the Bamboo context has been created and the API is ready to be used.
*/
'context:created': (args: ContextCreatedHookArgs) => void
/**
* Called when the config file or one of its dependencies (imports) has changed.
*/
'config:change': (args: ConfigChangeHookArgs) => MaybeAsyncReturn
/**
* Called after reading the file content but before parsing it.
* You can use this hook to transform the file content to a tsx-friendly syntax so that Bamboo's parser can parse it.
* You can also use this hook to parse the file's content on your side using a custom parser, in this case you don't have to return anything.
*/
'parser:before': (args: ParserResultBeforeHookArgs) => string | void
/**
* Called after the file styles are extracted and processed into the resulting ParserResult object.
* You can also use this hook to add your own extraction results from your custom parser to the ParserResult object.
*/
'parser:after': (args: ParserResultAfterHookArgs) => void
/**
* Called right before writing the codegen files to disk.
* You can use this hook to tweak the codegen files before they are written to disk.
*/
'codegen:prepare': (args: CodegenPrepareHookArgs) => MaybeAsyncReturn
/**
* Called after the codegen is completed
*/
'codegen:done': (args: CodegenDoneHookArgs) => MaybeAsyncReturn
/**
* Called right before adding the design-system CSS (global, static, preflight, tokens, keyframes) to the final CSS
* Called right before writing/injecting the final CSS (styles.css) that contains the design-system CSS and the parser CSS
* You can use it to tweak the CSS content before it's written to disk or injected through the postcss plugin.
*/
'cssgen:done': (args: CssgenDoneHookArgs) => string | void
}
```
---
## JSX Style Context
JSX Style Context provides an ergonomic way to style compound components with slot recipes.
It uses a context-based approach to distribute recipe styles across multiple child components, making it easier to style
headless UI libraries like Ark UI, and Radix UI.
## Atomic Slot Recipe
- Create a slot recipe using the `sva` function
- Pass the slot recipe to the `createStyleContext` function
- Use the `withProvider` and `withContext` functions to create compound components
```tsx
// components/ui/card.tsx
import { sva } from 'styled-system/css'
import { createStyleContext } from 'styled-system/jsx'
const card = sva({
slots: ['root', 'label'],
base: {
root: {},
label: {},
},
variants: {
size: {
sm: { root: {} },
md: { root: {} },
},
},
defaultVariants: {
size: 'sm',
},
})
const { withProvider, withContext } = createStyleContext(card)
const Root = withProvider('div', 'root')
const Label = withContext('label', 'label')
export const Card = {
Root,
Label,
}
```
Then you can use the `Root` and `Label` components to create a card.
```tsx
// app/page.tsx
import { Card } from './components/ui/card'
export default function App() {
return (
Hello
)
}
```
## Config Slot Recipe
The `createStyleContext` function can also be used with slot recipes defined in the `bamboo.config.ts` file.
- Pass the config recipe to the `createStyleContext` function
- Use the `withProvider` and `withContext` functions to create compound components
```tsx
// components/ui/card.tsx
import { card } from '../styled-system/recipes'
import { createStyleContext } from 'styled-system/jsx'
const { withProvider, withContext } = createStyleContext(card)
const Root = withProvider('div', 'root')
const Label = withContext('label', 'label')
export const Card = {
Root,
Label,
}
```
Then you can use the `Root` and `Label` components to create a card.
```tsx
// app/page.tsx
import { Card } from './components/ui/card'
export default function App() {
return (
Hello
)
}
```
## createStyleContext
This function is a factory function that returns three functions: `withRootProvider`, `withProvider`, and `withContext`.
### withRootProvider
Creates the root component that provides the style context. Use this when the root component **does not render an
underlying DOM element**.
```tsx
import { Dialog } from '@ark-ui/react'
//...
const DialogRoot = withRootProvider(Dialog.Root)
```
### withProvider
Creates a component that both provides context and applies the root slot styles. Use this when the root component
**renders an underlying DOM element**.
> **Note:** It requires the root `slot` parameter to be passed.
```tsx
import { Avatar } from '@ark-ui/react'
//...
const AvatarRoot = withProvider(Avatar.Root, 'root')
```
### withContext
Creates a component that consumes the style context and applies slot styles. It does not accept variant props directly,
but gets them from context.
```tsx
import { Avatar } from '@ark-ui/react'
//...
const AvatarImage = withContext(Avatar.Image, 'image')
const AvatarFallback = withContext(Avatar.Fallback, 'fallback')
```
### unstyled prop
Every component created with `createStyleContext` supports the `unstyled` prop to disable styling. It is useful when you
want to opt-out of the recipe styles.
- When applied the root component, will disable all styles
- When applied to a child component, will disable the styles for that specific slot
```tsx
// Removes all styles
// Removes only the styles for the image slot
```
## Guides
### Config Recipes
The rules of config recipes still applies when using `createStyleContext`. Ensure the name of the final component
matches the name of the recipe.
> If you want to use a custom name, you can configure the recipe's `jsx` property in the `bamboo.config.ts` file.
```tsx
// recipe name is "card"
import { card } from '../styled-system/recipes'
const { withRootProvider, withContext } = createStyleContext(card)
const Root = withRootProvider('div')
const Header = withContext('header', 'header')
const Body = withContext('body', 'body')
// The final component name must be "Card"
export const Card = {
Root,
Header,
Body,
}
```
### Default Props
Use `defaultProps` option to provide default props to the component.
```tsx
const { withContext } = createStyleContext(card)
export const CardHeader = withContext('header', 'header', {
defaultProps: {
role: 'banner',
},
})
```
---
## Merging Styles
Learn how to merge multiple styles without conflicts.
## Merging `css` objects
You can merge multiple style objects together using the `css` function.
```js
import { css } from 'styled-system/css'
const style1 = {
bg: 'red',
color: 'white',
}
const style2 = {
bg: 'blue',
}
const className = css(style1, style2) // => 'bg_blue text_white'
```
In some cases though, the style object might not be colocated in the same file as the component. In this case, you can
use the `css.raw` function to preserve the original style object.
> All `.raw(...)` signatures are identity functions that return the same value as the input, but serve as a hint to the
> compiler that the value is a style object.
```js
// style.js
import { css } from 'styled-system/css'
export const style1 = css.raw({
bg: 'red',
color: 'white',
})
// component.js
import { css } from 'styled-system/css'
import { style1 } from './style.js'
const style2 = css.raw({
bg: 'blue',
})
const className = css(style1, style2) // => 'bg_blue text_white'
```
## Spreading `css.raw` objects
> **Added in v1.6.1**
You can also spread `css.raw` objects within style declarations. This is particularly useful for reusing styles in
nested selectors, conditions, and complex compositions:
### Child selectors
```js
import { css } from 'styled-system/css'
const baseStyles = css.raw({ margin: 0, padding: 0 })
const component = css({
'& p': { ...baseStyles, fontSize: '1rem' },
'& h1': { ...baseStyles, fontSize: '2rem' },
})
```
### Nested conditions
```js
import { css } from 'styled-system/css'
const interactive = css.raw({ cursor: 'pointer', transition: 'all 0.2s' })
const card = css({
_hover: {
...interactive,
_dark: { ...interactive, color: 'white' },
},
})
```
## Merging `cva` + `css` styles
The same technique can be used to merge an atomic `cva` recipe and a style object.
```js
import { css, cx, cva } from 'styled-system/css'
const overrideStyles = css.raw({
bg: 'red',
color: 'white',
})
const buttonStyles = cva({
base: {
bg: 'blue',
border: '1px solid black',
},
variants: {
size: {
small: { fontSize: '12px' },
},
},
})
const className = css(
// returns the resolved style object
buttonStyles.raw({ size: 'small' }),
// add the override styles
overrideStyles,
)
// => 'bg_red border_1px_solid_black color_white font-size_12px'
```
## Merging `sva` + `css` styles
The same technique can be used to merge an atomic `sva` recipe and a style object.
```js
import { css, sva } from 'styled-system/css'
const overrideStyles = css.raw({
bg: 'red',
color: 'white'
})
const buttonStyles = sva({
slots: ['root']
base: {
root: {
bg: 'blue',
border: '1px solid black'
}
},
variants: {
size: {
root: {
small: { fontSize: '12px' }
}
}
}
})
// returns the resolved style object for all slots
const { root } = buttonStyles.raw({ size: 'small' })
const className = css(
root,
// add the override styles
overrideStyles
)
// => 'bg_red border_1px_solid_black color_white font-size_12px'
```
## Merging config recipe and style object
Due to the fact that the generated styles of a config recipe are saved in the `@layer recipe` cascade layer, they can be
overridden with any atomic styles. Use the `cx` function to achieve that.
> The `utilties` layer has more precedence than the `recipe` layer.
```js
import { css, cx } from 'styled-system/css'
import { button } from 'styled-system/recipes'
const className = cx(
// returns the resolved class name: `button button--size-small`
button({ size: 'small' }),
// add the override styles
css({ bg: 'red' }), // => 'bg_red'
)
// => 'button button--size-small bg_red'
```
## Merging within JSX component
Using these techniques, you can apply them to a component by exposing a `css` prop and merge with local styles.
> **Note:** For this to work, Bamboo requires that you set `jsxFramework` config option to `react`
```jsx
const cardStyles = css.raw({
bg: 'red',
color: 'white',
})
function Card({ title, description, css: cssProp }) {
return (
// merge the `cardStyles` with the `cssProp` passed in
)
}
// usage
function Demo() {
return
)
}
```
### Container
The Container pattern is used to create a container with a max-width and center the content.
By default, the container sets the following properties:
- `maxWidth: 8xl`
- `marginX: auto`
- `position: relative`
- `paddingX: { base: 4, md: 6, lg: 8 }`
```tsx
import { container } from '../styled-system/patterns'
function App() {
return (
)
}
```
```tsx
import { Container } from '../styled-system/jsx'
function App() {
return (
)
}
```
### Stack
The Stack pattern is a layout primitive that can be used to create a vertical or horizontal stack of elements.
The `stack` function accepts the following properties:
- `direction`: An alias for the css `flex-direction` property. Default is `column`.
- `gap`: The gap between the elements in the stack.
- `align`: An alias for the css `align-items` property.
- `justify`: An alias for the css `justify-content` property.
```tsx
import { stack } from '../styled-system/patterns'
function App() {
return (
)
}
```
```tsx
import { Stack } from '../styled-system/jsx'
function App() {
return (
)
}
```
#### HStack
The HStack pattern is a wrapper around the `stack` pattern that sets the `direction` property to `horizontal`, and
centers the elements vertically.
```tsx
import { hstack } from '../styled-system/patterns'
function App() {
return (
)
}
```
```tsx
import { HStack } from '../styled-system/jsx'
function App() {
return (
)
}
```
#### VStack
The VStack pattern is a wrapper around the `stack` pattern that sets the `direction` property to `vertical`, and centers
the elements horizontally.
```tsx
import { vstack } from '../styled-system/patterns'
function App() {
return (
)
}
```
```tsx
import { VStack } from '../styled-system/jsx'
function App() {
return (
)
}
```
### Wrap
The Wrap pattern is used to add space between elements and wraps automatically if there isn't enough space.
The `wrap` function accepts the following properties:
- `gap`: The gap between the elements in the stack.
- `columnGap`: The gap between the elements in the stack horizontally.
- `rowGap`: The gap between the elements in the stack vertically.
- `align`: An alias for the css `align-items` property.
- `justify`: An alias for the css `justify-content` property.
```tsx
import { wrap } from '../styled-system/patterns'
function App() {
return (
)
}
```
```tsx
import { Wrap } from '../styled-system/jsx'
function App() {
return (
)
}
```
### Aspect Ratio
The Aspect Ratio pattern is used to create a container with a fixed aspect ratio. It is used when displaying images,
maps, videos and other media.
> **Note:** In most cases, we recommend using the `aspectRatio` property instead of the pattern.
The `aspectRatio` function accepts the following properties:
- `ratio`: The aspect ratio of the container. Can be a number or a string.
```tsx
import { aspectRatio } from '../styled-system/patterns'
function App() {
return (
)
}
```
```tsx
import { AspectRatio } from '../styled-system/jsx'
function App() {
return (
)
}
```
### Flex
The Flex pattern is used to create a flex container and provides some shortcuts for the `flex` property.
The `flex` function accepts the following properties:
- `direction`: The flex direction of the container. Can be `row`, `column`, `row-reverse` or `column-reverse`.
- `wrap`: Whether to wrap the flex items. The value is a boolean.
- `align`: An alias for the css `align-items` property.
- `justify`: An alias for the css `justify-content` property.
- `basis`: An alias for the css `flex-basis` property.
- `grow`: An alias for the css `flex-grow` property.
- `shrink`: An alias for the css `flex-shrink` property.
```tsx
import { flex } from '../styled-system/patterns'
function App() {
return (
)
}
```
```tsx
import { Flex } from '../styled-system/jsx'
function App() {
return (
)
}
```
### Center
The Center pattern is used to center the content of a container.
The `center` function accepts the following properties:
- `inline`: Whether to use `inline-flex` or `flex` for the container. The value is a boolean.
```tsx
import { center } from '../styled-system/patterns'
function App() {
return (
```tsx
import { Center } from '../styled-system/jsx'
function App() {
return (
)
}
```
### LinkOverlay
The link overlay pattern is used to expand a link's clickable area to its nearest parent with `position: relative`.
> We recommend using this pattern when the relative parent contains at most one clickable link.
```tsx
import { css } from '../styled-system/css'
import { linkOverlay } from '../styled-system/patterns'
function App() {
return (
)
}
```
```tsx
import { Box, LinkOverlay } from '../styled-system/jsx'
function App() {
return (
View more
)
}
```
### Float
The Float pattern is used to anchor an element to the top, bottom, left or right of the container.
> It requires a parent element with `position: relative` styles.
The `float` function accepts the following properties:
- `placement`: The placement of the element. Can be `top-start`, `top`, `top-end`, `bottom-start`, `bottom`,
`bottom-end`, `left-start`, `left`, `left-end`, `right-start`, `right` or `right-end`.
- `offset`: The offset of the element from the edge of the container. Can be a number or a string.
- `offsetX`: Same as `offset`, but only for the horizontal axis.
- `offsetY`: Same as `offset`, but only for the vertical axis.
```tsx
import { css } from '../styled-system/css'
import { float } from '../styled-system/patterns'
function App() {
return (
)
}
```
```tsx
import { css } from '../styled-system/css'
import { Float } from '../styled-system/jsx'
function App() {
return (
3
)
}
```
### Grid
The Grid pattern is used to create a grid layout.
The `grid` function accepts the following properties:
- `columns`: The number of columns in the grid.
- `gap`: The gap between the elements in the stack.
- `columnGap`: The gap between the elements in the stack horizontally.
- `rowGap`: The gap between the elements in the stack vertically.
- `minChildWidth`: The minimum width of the child elements before wrapping (must not be used with `columns`).
```tsx
import { grid } from '../styled-system/patterns'
function App() {
return (
)
}
```
```tsx
import { Grid } from '../styled-system/jsx'
function App() {
return (
)
}
```
#### Grid Item
The Grid Item pattern is used to style the children of a grid container.
The `gridItem` function accepts the following properties:
- `colSpan`: The number of columns the item spans.
- `rowSpan`: The number of rows the item spans.
- `rowStart`: The row the item starts at.
- `rowEnd`: The row the item ends at.
- `colStart`: The column the item starts at.
- `colEnd`: The column the item ends at.
```tsx
import { grid, gridItem } from '../styled-system/patterns'
function App() {
return (
)
}
```
```tsx
import { Grid, GridItem } from '../styled-system/jsx'
function App() {
return (
First
Second
Third
)
}
```
### Divider
The Divider pattern is used to create a horizontal or vertical divider.
The `divider` function accepts the following properties:
- `orientation`: The orientation of the divider. Can be `horizontal` or `vertical`.
- `thickness`: The thickness of the divider. Can be a sizing token, or arbitrary value.
- `color`: The color of the divider. Can be a color token, or arbitrary value.
```tsx
import { divider, stack } from '../styled-system/patterns'
function App() {
return (
)
}
```
```tsx
import { Divider, Stack } from '../styled-system/jsx'
function App() {
return (
)
}
```
### Circle
The Circle pattern is used to create a circle.
The `circle` function accepts the following properties:
- `size`: The size of the circle. Can be a sizing token, or arbitrary value.
```tsx
import { circle } from '../styled-system/patterns'
function App() {
return
}
```
```tsx
import { Circle } from '../styled-system/jsx'
function App() {
return
### Square
The Square pattern is used to create a square with equal width and height.
The `square` function accepts the following properties:
- `size`: The size of the square. Can be a sizing token, or arbitrary value.
```tsx
import { square } from '../styled-system/patterns'
function App() {
return
}
```
```tsx
import { Square } from '../styled-system/jsx'
function App() {
return
### Visually Hidden
The Visually Hidden pattern is used to hide an element visually, but keep it accessible to screen readers.
```tsx
import { visuallyHidden } from '../styled-system/patterns'
export function Checkbox() {
return (
)
}
```
### Bleed
The Bleed pattern is used to create a full width element by negating the padding applied to its parent container.
The `bleed` function accepts the following properties:
- `inline`: The amount of padding to negate on the horizontal axis. Should match the parent's padding.
- `block`: The amount of padding to negate on the vertical axis. Should match the parent's padding.
```tsx
import { css } from '../styled-system/css'
import { bleed } from '../styled-system/patterns'
export function Page() {
return (
)
}
```
```tsx
import { css } from '../styled-system/css'
import { Bleed } from '../styled-system/jsx'
export function Page() {
return (
Welcome
)
}
```
### cq (Container Query)
To make it easier to use container queries, we've added a new `cq` pattern to `@bamboocss/preset-base`. It is used to
apply styles based on the width of the container.
The `cq` function accepts the following properties:
- `name`: The name of the container query, Maps to the
[`containerName` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/container-name).
- `type`: The type of the container query. Maps to the
[`containerType` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/container-type). Defaults to
`inline-size`.
```ts
import { cq } from 'styled-system/patterns'
function Demo() {
return (
)
}
```
You can also named container queries:
```tsx
// 1 - Define container conditions
export default defineConfig({
// ...
theme: {
containerNames: ['sidebar', 'content'],
containerSizes: {
xs: '40em',
sm: '60em',
md: '80em',
},
},
})
```
```tsx
// 2 - Automatically generate container query pattern
import { cq } from 'styled-system/patterns'
function Demo() {
return (
)
}
```
Read more about container queries [here](/docs/concepts/conditional-styles#container-queries).
## Usage with JSX
To use the pattern in JSX, you need to set the `jsxFramework` property in the config. When this is set, Bamboo will emit
files for JSX elements based on the framework.
Every pattern can be used as a JSX element and imported from the `/jsx` entrypoint. By default, the pattern name is the
function name in PascalCase. You can override both the component name (with the `jsx` config property) and the element
rendered (with the `jsxElement` config property).
Learn more about pattern customization [here](/docs/customization/patterns).
```tsx
import { VStack, Center } from '../styled-system/jsx'
function App() {
return (
-
{items.map((item) => (
- {item} ))}
| {item} |
Hello
```
#### Notes
- **Before and After**: Ensure you wrap the content value in double quotes.
- **Mixing with Conditions**: When using condition and pseudo elements, prefer to place the condition **before** the
pseudo element.
```jsx
css({
// This works ✅
_dark: { _backdrop: { color: 'red' } }
// This doesn't work ❌
_backdrop: { _dark: { color: 'red' } }
})
```
The reason `_backdrop: { _dark: { color: 'red' } }` doesn't work is because it generated an invalid CSS structure that
looks like:
```css
&::backdrop {
&.dark,
.dark & {
color: red;
}
}
```
### Placeholder
Style the placeholder text of any input or textarea using the `_placeholder` modifier:
```jsx
```
### File Inputs
Style the file input button using the `_file` modifier:
```jsx
```
## Media Queries
### Reduced Motion
Use the `_motionReduce` and `_motionSafe` modifiers to style an element based on the user's motion preference:
```jsx
Hello
```
### Color Scheme
The `prefers-color-scheme` media feature is used to detect if the user has requested the system use a light or dark
color theme.
Use the `_osLight` and `_osDark` modifiers to style an element based on the user's color scheme preference:
```jsx
Hello
```
Let's say your app is dark by default, but you want to allow users to switch to a light theme. You can do it like this:
```jsx
Hello
```
### Color Contrast
The `prefers-contrast` media feature is used to detect if the user has requested the system use a high or low contrast
theme.
Use the `_highContrast` and `_lessContrast` modifiers to style an element based on the user's color contrast preference:
```jsx
Hello
```
### Orientation
The `orientation` media feature is used to detect if the user has a device in portrait or landscape mode.
Use the `_portrait` and `_landscape` modifiers to style an element based on the user's device orientation:
```jsx
Hello
```
## Group Selectors
When you need to style an element based on its parent element's state or attribute, you can add the `group` class to the
parent element, and use any of the `_group*` modifiers on the child element.
```jsx
Hover me
Hover me
I'll change by bg
Hello
Hello
```
This also works for common states like `data-active`, `data-disabled`, `data-focus`, `data-hover`, `data-invalid`,
`data-required`, and `data-valid`.
```jsx
Hello
```
> Most of the `data-{state}` attributes typically mirror the corresponding browser pseudo class. For example,
> `data-hover` is equivalent to `:hover`, `data-focus` is equivalent to `:focus`, and `data-active` is equivalent to
> `:active`.
### Orientation
You can style an element based on its `data-orientation` attribute using the `_horizontal` and `_vertical` modifiers:
```jsx
Hello
```
## ARIA Attribute
You can style an element based on its `aria-{state}=true` attribute using the corresponding `_{state}` modifier:
```jsx
Hello
```
> Most of the `aria-{state}` attributes typically mirror the support ARIA states in the browser pseudo class. For
> example, `aria-checked=true` is styled with `_checked`, `aria-disabled=true` is styled with `_disabled`.
## Container queries
You can define container names and sizes in your theme configuration and use them in your styles.
```ts
export default defineConfig({
// ...
theme: {
extend: {
containerNames: ['sidebar', 'content'],
containerSizes: {
xs: '40em',
sm: '60em',
md: '80em',
},
},
},
})
```
The default container sizes in the `@bamboocss/preset-bamboo` preset are shown below:
```ts
export const containerSizes = {
xs: '320px',
sm: '384px',
md: '448px',
lg: '512px',
xl: '576px',
'2xl': '672px',
'3xl': '768px',
'4xl': '896px',
'5xl': '1024px',
'6xl': '1152px',
'7xl': '1280px',
'8xl': '1440px',
}
```
Then use them in your styles by referencing using `@{title}
{description}
{title}
{description}
Cool !
First
Second
Third
First
Second
Third
First
Second
Third
First
Second
Third
First
Second
Third
First
Second
Third
First
Second
Third
First
Second
Third
First
Second
Third
First
Second
Third
First
Second
Third
First
Second
Third
First
Second
Third
3
First
Second
Third
First
Second
Third
First
Second
Third
Welcome
First
Second
Third
This is a title
} // => ``` Here's what the emitted atomic CSS looks like: ```css .font-size_16px { font-size: 16px; } .font-weight_bold { font-weight: bold; } ``` ## The `styled` tag The `styled` tag allows you to create a component with encapsulated styles. It's similar to the `styled-components` or `emotion` library. ```js import { styled } from '../styled-system/jsx' // Create a styled component const Heading = styled.h1` font-size: 16px; font-weight: bold; ` function Demo() { // Use the styled component returnThis is a title
``` Here's what the emitted atomic CSS looks like: ```css .font-size_16px { font-size: 16px; } .font-weight_bold { font-weight: bold; } ``` ## Nested styles You can nest selectors, pseudo-elements and pseudo-selectors. ```js const Button = styled.button` color: black; &:hover { color: blue; } ` ``` Using css nesting syntax, pseudo-elements, pseudo-selectors and combinators are also supported: ```js const Demo = styled.div` color: black; &::after { content: '🎋'; } & + & { background: yellow; } &.bordered { border: 1px solid black; } .parent & { color: red; } ` ``` Nested media and container queries are also supported: ```js const Demo = styled.div` color: black; @media (min-width: 200px) { color: blue; } @container (min-width: 200px) { color: red; } ` ``` ## Hashing class names In some cases, it might be useful to shorten the class names by hashing them. Set the `hash: true` option in your `bamboo.config.ts` file to enable this. This will generate shorter class names but will make it harder to debug. To achieve this, set the `hash` option in your `bamboo.config.ts` file to `true`: ```ts // bamboo.config.ts export default defineConfig({ // ... hash: true, // optional }) ``` > Run the `codegen` command to regenerate the functions with hashing enabled. When hashing is enabled, the class names will go from this: ```css .font-size_16px { font-size: 16px; } .font-weight_bold { font-weight: bold; } ``` To a unique six character hash regardless of the length of the selector or the number of declarations: ```css .adfg5r { font-size: 16px; } .bsdf35 { font-weight: bold; } ``` ## Using tokens Use the `token()` function or `{}` syntax in your template literals to reference design tokens in your styles. Bamboo will automatically generate the corresponding CSS variables. ```js import { css } from '../styled-system/css' const className = css` font-size: {fontSizes.md}; font-weight: token(fontWeights.bold, 700); ` ``` ## Caveats The object literal syntax is the recommended way of writing styles. But, if you stick with the template literal syntax, there are some caveats to be aware of: - Patterns and recipes are not generated - Dynamic interpolation or component targeting is not supported - Lack of autocompletion for tokens within the template literal Our [Eslint plugin](https://github.com/bamboocss/bamboo/blob/main/packages/eslint-plugin/docs/rules/no-invalid-token-paths.md) can help you overcome this by detecting invalid tokens - JSX Style props are not supported --- ## Virtual Color Bamboo allows you to create a virtual color or color placeholder in your project. The `colorPalette` property is how you create virtual colors. ```js import { css } from '../styled-system/css' const className = css({ colorPalette: 'blue', bg: 'colorPalette.100', _hover: { bg: 'colorPalette.200', }, }) ``` This will translate to the `blue.100` background color and `blue.200` background color on hover. Virtual colors are useful when creating easily customizable components. ## Using with recipes You can also use virtual colors with recipes. ```js import { css, cva, cx } from '../styled-system/css' const button = cva({ base: { padding: 4, // you can also specify a default colorPalette in the `base` recipe key // colorPalette: 'blue', // ^^^^^^^^^^^^^^^^^^^^ }, variants: { variant: { primary: { color: 'colorPalette.500' }, }, }, defaultVariants: { variant: 'primary' }, }) ``` ## Using with different color modes You can also use virtual colors with different conditions, such as color modes. ```js import { css, cva, cx } from '../styled-system/css' const someButton = cva({ base: { padding: 4 }, variants: { variant: { primary: { bg: { base: 'colorPalette.500', _dark: 'colorPalette.200' }, color: { base: 'white', _dark: 'gray.900' }, }, }, }, defaultVariants: { variant: 'primary' }, }) export const App = () => { return ( <>Hello World
This is an element with slide-fade-in animation style.
)
}
```
Take advantage of it in your conditions:
```ts
export const popoverSlotRecipe = defineSlotRecipe({
slots: anatomy.keys(),
base: {
content: {
_open: {
animationStyle: 'scale-fade-in',
},
_closed: {
animationStyle: 'scale-fade-out',
},
},
},
})
```
## Nesting animation styles
Animation styles support nested structures with a special `DEFAULT` key. This allows you to create variants of an
animation style while having a default fallback.
When you define a `DEFAULT` key within a nested animation style, you can reference the parent key directly to use the
default value.
```js filename="bamboo.config.ts"
export default defineConfig({
theme: {
extend: {
animationStyles: {
fade: {
DEFAULT: {
value: {
animationName: 'fade-in',
animationDuration: '300ms',
animationTimingFunction: 'ease-in-out',
},
},
slow: {
value: {
animationName: 'fade-in',
animationDuration: '600ms',
animationTimingFunction: 'ease-in-out',
},
},
fast: {
value: {
animationName: 'fade-in',
animationDuration: '150ms',
animationTimingFunction: 'ease-in-out',
},
},
},
},
},
},
})
```
Now you can use the default fade animation or specific speed variants:
```jsx
import { css } from '../styled-system/css'
function App() {
return (
Default fade speed
Slow fade
Fast fade
This is inside a container style
}
```
## Nesting layer styles
Layer styles support nested structures with a special `DEFAULT` key. This allows you to create variants of a layer style
while having a default fallback.
When you define a `DEFAULT` key within a nested layer style, you can reference the parent key directly to use the
default value.
```js filename="bamboo.config.ts"
export default defineConfig({
theme: {
extend: {
layerStyles: {
card: {
DEFAULT: {
value: {
background: 'white',
border: '1px solid',
borderColor: 'gray.200',
borderRadius: 'md',
boxShadow: 'sm',
},
},
elevated: {
value: {
background: 'white',
border: 'none',
borderRadius: 'lg',
boxShadow: 'lg',
},
},
outlined: {
value: {
background: 'transparent',
border: '2px solid',
borderColor: 'gray.300',
borderRadius: 'md',
boxShadow: 'none',
},
},
},
},
},
},
})
```
Now you can use the default card style or specific variants:
```jsx
import { css } from '../styled-system/css'
function App() {
return (
Default card style
Elevated card
Outlined card
{colors?.values.map((color) => (
))}
)
}
```
Your color token documentation should look similar to this:
### `semantic-tokens.json`
#### Structure
This file contains an array of semantic token definitions grouped by category, with conditional values for different
modes (e.g., light/dark).
```json
{
"type": "semantic-tokens",
"data": [
{
"type": "colors",
"values": [
{
"name": "bg",
"values": [
{ "value": "{colors.white}", "condition": "base" },
{ "value": "{colors.dark}", "condition": "dark" }
],
"cssVar": "var(--colors-bg)"
}
],
"tokenFunctionExamples": ["token('colors.bg')", "token.var('colors.bg')"],
"functionExamples": ["css({ color: 'bg' })"],
"jsxExamples": ["{color.name}
{color.value}
{colors?.values.map((token) => (
))}
)
}
```
### `recipes.json`
#### Structure
This file contains an array of recipe definitions for styling components with variant support.
```json
{
"type": "recipes",
"data": [
{
"name": "button",
"description": "A button style",
"variants": {
"shape": ["square", "circle"],
"color": ["main", "black", "white"],
"size": ["sm", "md", "lg"]
},
"defaultVariants": {
"shape": "square",
"color": "main",
"size": "md"
},
"functionExamples": ["button({ shape: 'square' })", "button({ color: 'main' })", "button({ size: 'sm' })"],
"jsxExamples": ["", "", ""]
}
]
}
```
Each recipe in the `data` array includes:
- **name**: the recipe name (e.g., `button`, `card`)
- **description**: optional description of what the recipe does
- **variants**: an object where each key is a variant name and each value is an array of allowed options
- **defaultVariants**: an object defining the default option for each variant
- **functionExamples**: examples of how to use the recipe function
- **jsxExamples**: examples of how to use the recipe in JSX
#### Usage
Here's an example of how to document a button recipe within a table:
```tsx
import recipes from 'styled-system/specs/recipes.json'
const Demo = () => {
const buttonRecipe = recipes.data.find((recipe) => recipe.name === 'button')
const defaultVariants = buttonRecipe?.defaultVariants || {}
return (
{token.name}
{token.cssVar}
{token.values.map(({ condition, value }) => (
{condition}
))}
{value}
{buttonRecipe?.name}
{buttonRecipe?.description &&{buttonRecipe.description}
}| Variant | Options | Default |
|---|---|---|
| {key} | {(options as string[]).map((option) => ( {option} ))} | {defaultVariants[key as keyof typeof defaultVariants] || 'none'} |
{textStyles.data.map((style) => (
)
}
```
### `layer-styles.json`
#### Structure
This file contains an array of layer style definitions for visual presets (backgrounds, shadows, borders, etc.).
```json
{
"type": "layer-styles",
"data": [
{
"name": "offShadow",
"functionExamples": ["css({ layerStyle: 'offShadow' })"],
"jsxExamples": ["
{style.name}
))}
The quick brown fox jumps over the lazy dog
{layerStyles.data.map((style) => (
)
}
```
### `animation-styles.json`
Contains an array of animation style entries. Each entry includes:
- `name` — the animation preset name
- Animation properties such as `duration`, `timingFunction`, etc.
- Optional examples: `functionExamples` and `jsxExamples`
If no animation styles are configured in your `bamboo.config.ts` file , this file will contain an empty data array.
### `keyframes.json`
#### Structure
This file contains an array of keyframe definitions for CSS animations.
```json
{
"type": "keyframes",
"data": [
{
"name": "spin",
"functionExamples": ["css({ animationName: 'spin' })", "css({ animation: 'spin 1s ease-in-out infinite' })"],
"jsxExamples": ["
{style.name}
))}
{keyframes.data.map((keyframe) => (
)
}
```
### `patterns.json`
#### Structure
This file contains an array of pattern definitions for layout utilities.
```json
{
"type": "patterns",
"data": [
{
"name": "flex",
"jsx": "Flex",
"properties": [
{ "name": "align", "type": "SystemProperties['alignItems']" },
{ "name": "justify", "type": "SystemProperties['justifyContent']" },
{ "name": "direction", "type": "SystemProperties['flexDirection']" },
{ "name": "wrap", "type": "SystemProperties['flexWrap']" }
],
"functionExamples": ["flex({ align: 'center' })", "flex({ justify: 'space-between' })"],
"jsxExamples": ["
{keyframe.name}
))}
{patterns.data.map((pattern) => (
)}
))}
)
}
```
### `conditions.json`
Contains an array of condition entries. Each entry includes:
- `name` — the condition key used in style objects (e.g.,`_hover`, `_focus`, `_focusWithin`)
- `value` — the CSS selector or media query that the condition maps to
- Optional examples: `functionExamples` and `jsxExamples`
## FAQs
### Can I edit the spec files directly?
**No.** The spec files are **generated** files—you should **not** edit your design tokens, recipes, or theme directly in
these files. All configuration changes must be made in your `bamboo.config.ts` file. The spec files exist purely for
documentation and visualization purposes.
---
## Using Bamboo Studio
Document your design system visually using Bamboo Studio.
### Bamboo Studio
Bamboo Studio is a visual interface for exploring and understanding your entire design system. It provides a read-only
view of your tokens, semantic tokens, recipes, patterns, conditions, and more.
If you don't want to manually generate spec files or build a documentation website, Bamboo Studio is the easiest option.
- Studio does not require you to run pnpm bamboo spec.
- Studio generates and visualizes your design system automatically.
- Studio acts as a fully-featured documentation tool without writing any documentation code.
> Spec files are primarily for custom documentation setups and Storybook integrations. Bamboo Studio is for teams who
> want instant documentation.
## Bamboo Studio Setup
To use bamboo studio, first install it:
```bash
pnpm i @bamboocss/studio
```
Next, launch it locally using:
```bash
pnpm bamboo studio
```
This starts a local server and launches an interactive dashboard showing all your design system elements. Since Studio
reads your theme configuration directly, any changes to your `bamboo.config.ts` will appear automatically the next time
you run it.
You can also deploy the studio as a standalone design system portal for your team.
---
## Text Styles
Define reusable typography css properties.
Text styles allows you to define textual css properties. The common properties are:
- The font family, weight, size
- Line height
- Letter spacing
- Text Decoration (strikethrough and underline)
- Text Transform (uppercase, lowercase, and capitalization)
## Defining text styles
Text styles are defined in the `textStyles` property of the theme.
Here's an example of a text style:
```js filename="text-styles.ts"
import { defineTextStyles } from '@bamboocss/dev'
export const textStyles = defineTextStyles({
body: {
description: 'The body text style - used in paragraphs',
value: {
fontFamily: 'Inter',
fontWeight: '500',
fontSize: '16px',
lineHeight: '24px',
letterSpacing: '0',
textDecoration: 'None',
textTransform: 'None',
},
},
})
```
> **Good to know:** The `value` property maps to style objects that will be applied to the text.
## Update the config
To use the text styles, we need to update the `config` object in the `bamboo.config.ts` file.
```js filename="bamboo.config.ts"
import { defineConfig } from '@bamboocss/dev'
import { textStyles } from './text-styles'
export default defineConfig({
theme: {
extend: {
textStyles,
},
},
})
```
This should automatically update the generated theme the specified `textStyles`. If this doesn't happen, you can run the
`bamboo codegen` command.
## Using text styles
Now we can use `textStyle` property in our components.
```jsx
import { css } from '../styled-system/css'
function App() {
return {pattern.name}
{'<'} {pattern.jsx} {'/'} {'>'} {pattern.properties.length > 0 && (| Prop | Type | Default |
|---|---|---|
| {prop.name} | {prop.type} | {prop.defaultValue || '—'} |
This is a paragraph from Bamboo with the body text style.
} ``` ## Nesting text styles Text styles support nested structures with a special `DEFAULT` key. This allows you to create variants of a text style while having a default fallback. When you define a `DEFAULT` key within a nested text style, you can reference the parent key directly to use the default value. ```js filename="bamboo.config.ts" export default defineConfig({ theme: { extend: { textStyles: { heading: { DEFAULT: { value: { fontFamily: 'Inter', fontWeight: 'bold', fontSize: '1.5rem', lineHeight: '1.2', }, }, h1: { value: { fontFamily: 'Inter', fontWeight: 'bold', fontSize: '2.5rem', lineHeight: '1.1', }, }, h2: { value: { fontFamily: 'Inter', fontWeight: 'bold', fontSize: '2rem', lineHeight: '1.15', }, }, }, }, }, }, }) ``` Now you can use the default heading style or specific variants: ```jsx import { css } from '../styled-system/css' function App() { return (Main Title
Subtitle
Uses DEFAULT variant
Hello World
) } ``` You can also add an optional description to your tokens. This will be used in the autogenerate token documentation. ```js {8} import { defineConfig } from '@bamboocss/dev' export default defineConfig({ theme: { tokens: { colors: { danger: { value: '#EE0F0F', description: 'Color for errors', }, }, }, }, }) ``` ## Semantic Tokens Semantic tokens are tokens that are designed to be used in a specific context. In most cases, the value of a semantic token references to an existing token. > To reference a value in a semantic token, use the `{}` syntax. For example, assuming we've defined the following tokens: - `red` and `green` are raw tokens that define the color red and green. - `danger` and `success` are semantic tokens that reference the `red` and `green` tokens. ```js import { defineConfig } from '@bamboocss/dev' export default defineConfig({ theme: { tokens: { colors: { red: { value: '#EE0F0F' }, green: { value: '#0FEE0F' }, }, }, semanticTokens: { colors: { danger: { value: '{colors.red}' }, success: { value: '{colors.green}' }, }, }, }, }) ``` > ⚠️ Semantic Token values need to be nested in an object with a `value` key. This is to allow for additional properties > like `description` and more in the future. Semantic tokens can also be changed based on the [conditions](/docs/concepts/conditional-styles) like light and dark modes. For example, if you want a color to change automatically based on light or dark mode. ```js import { defineConfig } from '@bamboocss/dev' export default defineConfig({ // ... theme: { semanticTokens: { colors: { danger: { value: { base: '{colors.red}', _dark: '{colors.darkred}' }, }, success: { value: { base: '{colors.green}', _dark: '{colors.darkgreen}' }, }, }, }, }, }) ``` > NOTE 🚨: The conditions used in semantic tokens must be an at-rule or parent selector > [condition](/docs/concepts/conditional-styles#reference). ## Token Nesting Tokens can be nested to create a hierarchy of tokens. This is useful when you want to group tokens together. > Tip: You can use the `DEFAULT` key to define the default value of a nested token. ```js import { defineConfig } from '@bamboocss/dev' export default defineConfig({ // ... theme: { semanticTokens: { colors: { bg: { DEFAULT: { value: '{colors.gray.100}' }, muted: { value: '{colors.gray.100}' }, }, }, }, }, }) ``` This allows the use of the `bg` token in the following ways: ```jsx import { css } from '../styled-system/css' function App() { return (
Hello World
)
}
```
## Token Types
Bamboo supports the following token types:
### Colors
Colors have meaning and support the purpose of the content, communicating things like hierarchy of information, and
states. It is mostly defined as a string value or reference to other tokens.
```jsx
const theme = {
tokens: {
colors: {
red: { 100: { value: '#fff1f0' } },
},
},
}
```
### Gradients
Gradient tokens represent a smooth transition between two or more colors. Its value can be defined as a string or a
composite value.
```ts
type Gradient =
| string
| {
type: 'linear' | 'radial'
placement: string | number
stops:
| Array<{
color: string
position: number
}>
| ArrayAccessible only to screen readers
```
## Debug
The debug utility class applies styles to aid in debugging by adding outlines to elements. This can be helpful during
development to visually inspect the layout and structure of your components.
```jsx
Debugging outline applied
```
---
## Interactivity
Bamboo CSS provides a variety of utility classes to enhance interactivity and user experience on your web applications.
Bamboo CSS provides a variety of utility classes to enhance interactivity and user experience on your web applications.
These utilities cover aspects such as accent color, caret color, scrolling behavior, scrollbar customization, scroll
margins and paddings, scroll snapping, touch actions, and user selection.
## Accent Color
The `accentColor` utility class sets the accent color of an element. It supports `colors` tokens.
```jsx
Accent color applied
```
## Caret Color
The `caretColor` utility class sets the color of the text cursor (caret) in an input or textarea. It supports `colors`
tokens.
```jsx
```
## Scrollbar
The `scrollbar` utility allows customization of scrollbar appearance. It supports `visible` and `hidden` values which
respectively show or hide the scrollbar.
```jsx
Scrollbar hidden
```
## Scroll Margin
Scroll margin utilities set margins around scroll containers.
```jsx
Scrollbar Container with Inline padding
```
| Prop | CSS Property | Token Category |
| ------------------------------------- | ---------------------------- | -------------- |
| `scrollMarginX` ,`scrollMarginInline` | `scroll-margin-inline` | `spacing` |
| `scrollMarginInlineStart` | `scroll-margin-inline-start` | `spacing` |
| `scrollMarginInlineEnd` | `scroll-margin-inline-end` | `spacing` |
| `scrollMarginY` , `scrollMarginBlock` | `scroll-margin-block` | `spacing` |
| `scrollMarginBlockStart` | `scroll-margin-block-start` | `spacing` |
| `scrollMarginBlockEnd` | `scroll-margin-block-end` | `spacing` |
| `scrollMarginLeft` | `scroll-margin-left` | `spacing` |
| `scrollMarginRight` | `scroll-margin-right` | `spacing` |
| `scrollMarginTop` | `scroll-margin-top` | `spacing` |
| `scrollMarginBottom` | `scroll-margin-bottom` | `spacing` |
## Scroll Padding
Scroll padding utilities set padding inside scroll containers.
```jsx
Scrollbar Container with block padding
```
| Prop | CSS Property | Token Category |
| ---------------------------------------- | ----------------------------- | -------------- |
| `scrollPaddingX` , `scrollPaddingInline` | `scroll-padding-inline` | `spacing` |
| `scrollPaddingInlineStart` | `scroll-padding-inline-start` | `spacing` |
| `scrollPaddingInlineEnd` | `scroll-padding-inline-end` | `spacing` |
| `scrollPaddingY` , `scrollPaddingBlock` | `scroll-padding-block` | `spacing` |
| `scrollPaddingBlockStart` | `scroll-padding-block-start` | `spacing` |
| `scrollPaddingBlockEnd` | `scroll-padding-block-end` | `spacing` |
| `scrollPaddingLeft` | `scroll-padding-left` | `spacing` |
| `scrollPaddingRight` | `scroll-padding-right` | `spacing` |
| `scrollPaddingTop` | `scroll-padding-top` | `spacing` |
| `scrollPaddingBottom` | `scroll-padding-bottom` | `spacing` |
## Scroll Snapping
Scroll snapping utilities provide control over the scroll snap behavior.
### Scroll Snap Margin
| Prop | CSS Property | Token Category |
| ------------------------ | ---------------------- | -------------- |
| `scrollSnapMargin` | `scroll-margin` | `spacing` |
| `scrollSnapMarginTop` | `scroll-margin-top` | `spacing` |
| `scrollSnapMarginBottom` | `scroll-margin-bottom` | `spacing` |
| `scrollSnapMarginLeft` | `scroll-margin-left` | `spacing` |
| `scrollSnapMarginRight` | `scroll-margin-right` | `spacing` |
### Scroll Snap Strictness
It's values can be `mandatory` or `proximity` values, and maps to `var(--scroll-snap-strictness)`.
```jsx
Scroll container with proximity scroll snap
```
### Scroll Snap Type
Supported values
| Value | |
| ------ | ------------------------------------ |
| `none` | `none` |
| `x` | `x var(--scroll-snap-strictness)` |
| `y` | `y var(--scroll-snap-strictness)` |
| `both` | `both var(--scroll-snap-strictness)` |
---
## Layout
Bamboo provides style properties for styling layout of an element
Bamboo provides style properties for styling layout of an element.
## Aspect Ratio
Use the `aspectRatio` utilities to set the desired aspect ratio of an element.
Values can reference the `aspectRatios` token category.
```jsx
```
> This uses the native CSS property `aspect-ratio` which is might not supported in all browsers. Consider using the
> [`AspectRatio` pattern](/docs/concepts/patterns#aspect-ratio) instead
## Position
Use the `position` utilities to set the position of an element.
```jsx
// shorthand
```
## Top / Right / Bottom / Left
Use the `top`, `right`, `bottom` and `left` utilities to set the position of an element.
Values can reference the `spacing` token category.
```jsx
```
| Prop | CSS Property | Token Category |
| -------- | ------------ | -------------- |
| `top` | `top` | `spacing` |
| `right` | `right` | `spacing` |
| `bottom` | `bottom` | `spacing` |
| `left` | `left` | `spacing` |
### Logical Properties
Use the `inset{Start|End}` utilities to set the position of an element based on the writing mode.
> For example, `insetStart` will set the `left` property in `ltr` mode and `right` in `rtl` mode.
```jsx
```
| Prop | CSS Property | Token Category |
| ----------------------------------------- | -------------------- | -------------- |
| `start`, `insetStart`, `insetInlineStart` | `inset-inline-start` | `spacing` |
| `end` , `insetEnd`, `insetInlineEnd` | `inset-inline-end` | `spacing` |
| `insetX`, `insetInline` | `inset-inline` | `spacing` |
| `insetY`, `insetBlock` | `inset-inline` | `spacing` |
## Container Query
You can define container names and sizes in your theme configuration and use them in your styles.
[Read more.](/docs/concepts/conditional-styles#container-queries)
| Prop | CSS Property | Token Category |
| --------------- | --------------- | ---------------- |
| `containerName` | `containerName` | `containerNames` |
---
## List
Bamboo provides utilities for customizing list styles.
Bamboo provides utilities for customizing list styles.
## List Style Image
Use a custom image as the list marker. It supports the `assets` token category.
```js filename="bamboo.config.ts"
const theme = {
tokens: {
assets: {
star: {
value: { type: 'svg', value: '' },
},
},
},
}
```
```jsx
```
---
## Outline
Bamboo provides utilities for customizing outlines.
Bamboo provides utilities for customizing outlines.
## Compound Property
Set the width, color, and style of the outline.
```jsx
// shorthand
```
| Prop | CSS Property | Token Category |
| ------------------ | ------------ | -------------- |
| `ring` , `outline` | `outline` | `borders` |
## Outline Width
Change the width of the outline.
```jsx
// shorthand
```
| Prop | CSS Property | Token Category |
| ---------------------------- | --------------- | -------------- |
| `ringWidth` , `outlineWidth` | `outline-width` | `borderWidths` |
## Outline Color
Change the color of the outline.
```jsx
// shorthand
```
| Prop | CSS Property | Token Category |
| -------------- | --------------- | -------------- |
| `outlineColor` | `outline-color` | `colors` |
## Outline Offset
Adjust the space between the outline and the element.
```jsx
// shorthand
```
| Prop | CSS Property | Token Category |
| --------------- | ---------------- | -------------- |
| `outlineOffset` | `outline-offset` | `spacing` |
---
## Sizing
Style properties for controlling the size of an element.
Style properties for controlling the size of an element.
## Width
Use the `width` or `w` property to set the width of an element.
```jsx
// shorthand
```
### Fractional width
Use can set fractional widths using the `width` or `w` property.
Values can be within the following ranges:
- Thirds: `1/3` to `2/3`
- Fourths: `1/4` to `3/4`
- Fifths: `1/5` to `4/5`
- Sixths: `1/6` to `5/6`
- Twelfths: `1/12` to `11/12`
```jsx
// shorthand
// shorthand
```
### Max width
Use the `maxWidth` or `maxW` property to set the maximum width of an element.
```jsx
// shorthand
```
### Min width
Use the `minWidth` or `minW` property to set the minimum width of an element.
```jsx
// shorthand
```
| Prop | CSS Property | Token Category |
| ------------------ | ------------ | -------------- |
| `w`, `width` | `width` | `sizes` |
| `maxW`, `maxWidth` | `max-width` | `sizes` |
| `minW`, `minWidth` | `min-width` | `sizes` |
## Height
Use the `height` or `h` property to set the height of an element.
```jsx
// shorthand
```
### Fractional height
Use can set fractional heights using the `height` or `h` property.
Values can be within the following ranges:
- Thirds: `1/3` to `2/3`
- Fourths: `1/4` to `3/4`
- Fifths: `1/5` to `4/5`
- Sixths: `1/6` to `5/6`
```jsx
// shorthand
```
### Relative heights
You can use the modern relative height values `dvh`, `svh`, `lvh`.
```jsx
// shorthand
```
### Max height
Use the `maxHeight` or `maxH` property to set the maximum height of an element.
```jsx
// shorthand
```
### Min height
Use the `minHeight` or `minH` property to set the minimum height of an element.
```jsx
// shorthand
```
| Prop | CSS Property | Token Category |
| ------------------- | ------------ | -------------- |
| `h`, `height` | `height` | `sizes` |
| `maxH`, `maxHeight` | `max-height` | `sizes` |
| `minH`, `minHeight` | `min-height` | `sizes` |
### Size
Use the `boxSize` property to set the width and height of an element.
```jsx
```
| Prop | CSS Property | Token Category |
| --------- | --------------- | -------------- |
| `boxSize` | `width, height` | `sizes` |
---
## Spacing
Style properties for controlling the padding of an element.
## Padding
### All sides
Use the `padding` property to apply padding on all sides of an element
```jsx
// shorthand
```
### Specific sides
Use the `padding{Left|Right|Top|Bottom}` to apply padding on one side of an element
```jsx
// shorthand
// shorthand
```
### Horizontal and Vertical padding
Use the `padding{X|Y}` properties to apply padding on the horizontal and vertical axis of an element
```jsx
// shorthand
// shorthand
```
| Prop | CSS Property | Token Category |
| --------------------- | ---------------- | -------------- |
| `p`,`padding` | `padding` | `spacing` |
| `pl`, `paddingLeft` | `padding-left` | `spacing` |
| `pr`, `paddingRight` | `padding-right` | `spacing` |
| `pt`, `paddingTop` | `padding-top` | `spacing` |
| `pb`, `paddingBottom` | `padding-bottom` | `spacing` |
| `px`, `paddingX` | `padding-inline` | `spacing` |
| `py`, `paddingY` | `padding-block` | `spacing` |
### Logical properties
Use the `padding{Start|End}` properties to apply padding on the logical axis of an element based on the text direction.
```jsx
// shorthand
// shorthand
```
| Prop | CSS Property | Token Category |
| -------------------- | ---------------------- | -------------- |
| `ps`, `paddingStart` | `padding-inline-start` | `spacing` |
| `pe`, `paddingEnd` | `padding-inline-end` | `spacing` |
## Margin
### All sides
Use the `margin` property to apply margin on all sides of an element
```jsx
// shorthand
```
### Specific sides
Use the `margin{Left|Right|Top|Bottom}` to apply margin on one side of an element
```jsx
// shorthand
// shorthand
```
### Horizontal and Vertical margin
Use the `margin{X|Y}` properties to apply margin on the horizontal and vertical axis of an element
```jsx
// shorthand
// shorthand
```
| Prop | CSS Property | Token Category |
| -------------------- | --------------- | -------------- |
| `m`,`margin` | `margin` | `spacing` |
| `ml`, `marginLeft` | `margin-left` | `spacing` |
| `mr`, `marginRight` | `margin-right` | `spacing` |
| `mt`, `marginTop` | `margin-top` | `spacing` |
| `mb`, `marginBottom` | `margin-bottom` | `spacing` |
| `mx`, `marginX` | `margin-left` | `spacing` |
| `my`, `marginY` | `margin-top` | `spacing` |
### Logical properties
Use the `margin{Start|End}` properties to apply margin on the logical axis of an element based on the text direction.
```jsx
// shorthand
// shorthand
```
| Prop | CSS Property | Token Category |
| ------------------- | --------------------- | -------------- |
| `ms`, `marginStart` | `margin-inline-start` | `spacing` |
| `me`, `marginEnd` | `margin-inline-end` | `spacing` |
---
## SVG
Bamboo provides utilities for styling SVG elements.
Bamboo provides utilities for styling SVG elements.
## Fill
Change the fill color of an SVG element.
```jsx
```
| Prop | CSS Property | Token Category |
| ------ | ------------ | -------------- |
| `fill` | `fill` | `colors` |
## Stroke
Change the stroke color of an SVG element.
```jsx
```
| Prop | CSS Property | Token Category |
| -------- | ------------ | -------------- |
| `stroke` | `stroke` | colors |
## Stroke Width
Change the stroke width of an SVG element.
```jsx
```
| Prop | CSS Property | Token Category |
| ------------- | -------------- | -------------- |
| `strokeWidth` | `stroke-width` | borderWidths |
---
## Tables
Bamboo provides utilities for styling tables.
Bamboo provides utilities for styling tables.
## Border Spacing
Control the border-spacing property of a table.
```jsx
Some long piece of text
Truncated text
```
| Prop | CSS Property | Token Category |
| ----------- | ------------------- | -------------- |
| `lineClamp` | `webkit-line-clamp` | none |
| `truncate` | `text-overflow` | none |
## Text Styles
Utilities for applying a composition of typography properties.
```jsx
Hello World
``` | Prop | Config | | ----------- | ------------ | | `textStyle` | `textStyles` | --- # Customization ## Conditions Learn how to customize conditions in your Bamboo config Conditions allow you to apply different styles and behaviors based on specific conditions or states. They provide a way to target specific elements or apply styles in response to certain events or conditions. ## Creating a condition To create a condition, you can use the conditions property in the config. Let's say we want to create a `groupHover` pseudo condition that applies styles to an element when a parent container with the `group` role is hovered. ```ts filename="bamboo.config.ts" import { defineConfig } from '@bamboocss/dev' export default defineConfig({ conditions: { extend: { groupHover: '[role=group]:where(:hover, [data-hover]) &', }, }, }) ``` > ⚠️ The `&` character is mandatory, it is a placeholder for the current selector. It will be replaced with the actual > selector when the condition is used. It has to be used either at the beginning or at the end of the condition. Then you can run the following command to generate the conditions JS code:Scrollable content
Dynamic color with runtime value
)
}
// App.tsx
const App = () => {
const [runtimeColor, setRuntimeColor] = useState('pink.300')
return
Dynamic color with runtime value
)
}
const App = () => {
const [runtimeColor, setRuntimeColor] = useState('yellow.300')
return Some content
Some content
Mona Sans
Fira Code
Text
` work as expected. ## Re-using Bamboo presets Bamboo offers 2 presets: - `@bamboocss/preset-base`: This is a relatively unopinionated set of utilities for mapping CSS properties to values (almost everyone will want these) You can use these presets by installing them via npm and adding them to your `presets` key: ```js export default defineConfig({ // ... presets: ['@bamboocss/preset-base'], }) ``` - `@bamboocss/preset-bamboo` as an opinionated set of tokens if you don't want to define your own colors/spacing/fonts etc. ```js export default defineConfig({ // ... presets: ['@bamboocss/preset-bamboo'], }) ``` > Note: You don't need to install `@bamboocss/preset-base` or `@bamboocss/preset-bamboo`. Bamboo will automatically > resolve them for you. --- ## Multi-Theme Tokens Bamboo supports advance token definition beyond just light/dark mode; theming beyond just dark mode. You can define multi-theme tokens using nested conditions. ## Multi-Theme Tokens Bamboo supports advance token definition beyond just light/dark mode; theming beyond just dark mode. You can define multi-theme tokens using nested conditions. Let's say your application supports a pink and blue theme, and each theme can have a light and dark mode. Let's see how to model this in Bamboo. We'll start by defining the following conditions for these theme and color modes: ```js // bamboo.config.ts const config = { conditions: { light: '[data-color-mode=light] &', dark: '[data-color-mode=dark] &', pinkTheme: '[data-theme=pink] &', blueTheme: '[data-theme=blue] &', }, } ``` > Conditions are a way to provide preset css selectors or media queries for use in your Bamboo project Next, we'll define a `colors.text` semantic token for the pink and blue theme. ```js // bamboo.config.ts const theme = { // ... semanticTokens: { colors: { text: { value: { _pinkTheme: '{colors.pink.500}', _blueTheme: '{colors.blue.500}', }, }, }, }, } ``` Next, we'll modify `colors.text` to support light and dark color modes for each theme. ```js // bamboo.config.ts const theme = { // ... semanticTokens: { colors: { text: { value: { _pinkTheme: { base: '{colors.pink.500}', _dark: '{colors.pink.300}' }, _blueTheme: { base: '{colors.blue.500}', _dark: '{colors.blue.300}' }, }, }, }, }, } ``` Now, you can use the `text` token in your styles, and it will automatically change based on the theme and the color scheme. ```jsx // use pink and dark mode themeHello World
// use pink and light mode themeHello World
``` ## Multi-Themes The above example shows you how to define multi-theme tokens using nested conditions but you can also define clearly separated themes using the `themes` property in the config. This allows you to apply a `theme` on multiple tokens at once, using data attributes and CSS variables. > Theme variants can be applied using the `data-bamboo-theme` attribute with the theme key as the value. ```ts // bamboo.config.ts import { defineConfig } from '@bamboocss/dev' export default defineConfig({ // ... // main theme theme: { extend: { tokens: { colors: { text: { value: 'green' }, }, }, semanticTokens: { colors: { body: { value: { base: '{colors.green.600}', _osDark: '{colors.green.400}', }, }, }, }, }, }, // alternative theme variants themes: { primary: { tokens: { colors: { text: { value: 'red' }, }, }, semanticTokens: { colors: { muted: { value: '{colors.red.200}' }, body: { value: { base: '{colors.red.600}', _osDark: '{colors.red.400}', }, }, }, }, }, secondary: { tokens: { colors: { text: { value: 'blue' }, }, }, semanticTokens: { colors: { muted: { value: '{colors.blue.200}' }, body: { value: { base: '{colors.blue.600}', _osDark: '{colors.blue.400}', }, }, }, }, }, }, }) ``` ### Pregenerating themes By default, no additional theme variant is generated, you need to specify the specific themes you want to generate in `staticCss.themes` to include them in the CSS output. ```ts // bamboo.config.ts import { defineConfig } from '@bamboocss/dev' export default defineConfig({ // ... staticCss: { themes: ['primary', 'secondary'], }, }) ``` This will generate the following CSS: ```css @layer tokens { :where(:root, :host) { --colors-text: blue; --colors-body: var(--colors-blue-600); } [data-bamboo-theme='primary'] { --colors-text: red; --colors-muted: var(--colors-red-200); --colors-body: var(--colors-red-600); } @media (prefers-color-scheme: dark) { :where(:root, :host) { --colors-body: var(--colors-blue-400); } [data-bamboo-theme='primary'] { --colors-body: var(--colors-red-400); } } } ``` ### Dynamically importing themes An alternative way of applying a theme is by using the new `styled-system/themes` entrypoint where you can import the themes expected CSS and apply them in your app. > ℹ️ The `styled-system/themes` will always contain every themes (tree-shaken if not used), whereas `staticCss.themes` > only applies to the CSS output. Each theme has a corresponding JSON file with a similar structure: ```json { "name": "primary", "id": "bamboo-themes-primary", "css": "[data-bamboo-theme=primary] { ... }" } ``` #### Dynamically import a theme using its name ```ts import { getTheme } from '../styled-system/themes' const theme = await getTheme('red') // ^? { // name: "red"; // id: string; // css: string; // } ``` #### Inject the theme styles into the DOM: ```ts import { injectTheme } from '../styled-system/themes' const theme = await getTheme('red') injectTheme(document.documentElement, theme) // this returns the injected style element ``` #### SSR example with NextJS: ```tsx // app/layout.tsx import { cookies } from 'next/headers' import './globals.css' import { ThemeName, getTheme } from '../../styled-system/themes' export default async function RootLayout({ children }: { children: React.ReactNode }) { const store = cookies() const themeName = store.get('theme')?.value as ThemeName const theme = themeName && (await getTheme(themeName)) return ( {themeName && ( )} {children} ) } ``` ```tsx // app/page.tsx 'use client' import { getTheme, injectTheme } from '../../styled-system/themes' export default function Home() { return ( <> ) } // Set a Cookie function setCookie(cName: string, cValue: any, expDays: number) { let date = new Date() date.setTime(date.getTime() + expDays * 24 * 60 * 60 * 1000) const expires = 'expires=' + date.toUTCString() document.cookie = cName + '=' + cValue + '; ' + expires + '; path=/' } ``` ### Theme contract Finally, you can create a theme contract to ensure that all themes have the same structure: ```ts import { defineThemeContract } from '@bamboocss/dev' const defineTheme = defineThemeContract({ tokens: { colors: { red: { value: '' }, // theme implementations must have a red color }, }, }) defineTheme({ tokens: { colors: { // ^^^^ ❌ Property 'red' is missing in type '{}' but required in type '{ red: { value: string; }; }' // // ✅ fixed with // red: { value: 'red' }, }, }, }) ``` --- ## Source Transformation Fold static css() and pattern calls into literal class strings at build time Bamboo resolves styles at runtime: `css({ color: 'red.300' })` runs on every render and returns a class string. The result is cached, but the call still costs something — and for a call whose arguments never change, that cost buys nothing. Source transformation removes it. During a production build, `@bamboocss/vite` rewrites statically-resolvable calls into the string they would have returned: ```tsx // you write export const title = css({ fontSize: 'lg', fontWeight: 'bold' }) // the bundle gets export const title = 'fs_lg fw_bold' ``` The CSS is unchanged. Only the JavaScript changes. ## Setup Install the plugin and add it to your Vite config. It is **off by default** — you have to ask for it. ```bash pnpm add -D @bamboocss/vite ``` ```ts // vite.config.ts import { defineConfig } from 'vite' import bamboocss from '@bamboocss/vite' export default defineConfig({ plugins: [bamboocss({ transform: true })], }) ```hi
```
This is the one that matters most at runtime. The factory runs `splitProps`, `css()` and `cx` for every element on every
render, inside a `forwardRef` component — folding removes all of it, including the component layer.
Measured on `sandbox/runtime-perf`, rendering fifty trees, warm: **3.2× faster** on a mixed tree, and **2.9×** on one
whose style props are all runtime-valued. The second is the weaker case and still the more interesting one — nothing
about those elements resolves at build time, so what folding removes there is the factory itself rather than the styles.
Both sides are warmed first, which is the conservative reading: the runtime's style memo is full, so this is the
steady-state win rather than the cold-start one, and cold start is where the gap is widest.
Props are handled the way the factory handles them. For a factory with no recipe attached, `defaultShouldForwardProp`
reduces to "css properties are consumed, everything else reaches the DOM unchanged", so `onClick` and `id` pass through
verbatim while `color` becomes part of the class. A static `className` is appended, in the position `cx` would have put
it.
A static `as` names the tag to fold to, rather than blocking the fold:
```tsx
hi
```
Pattern props and style props are both consumed; anything else passes through. `as` and a static `className` behave as
they do on a `styled.*` element.
Pattern elements only fold under the default `jsxStyleProps: 'all'`. Under `minimal` and `none` the pattern's styles
reach the factory through the `css` prop rather than being spread, which reverses which side wins when a prop is set in
both places.
`jsx: false` turns element folding off altogether — both `styled.*` and pattern elements — leaving call sites folding on
their own.
## What does not fold
Everything else is left byte-identical. A call Bamboo cannot fully resolve keeps its runtime behaviour.
```tsx
// ❌ a value only known at runtime
css({ color: tone })
// ❌ a spread of anything but an inline object literal
css({ color: 'red.300', ...rest })
// ❌ a computed key
css({ [key]: { color: 'red.300' } })
// ❌ several arguments where one is dynamic — later-wins across the whole object, so the
// static half cannot be hoisted out without reproducing the merge
css({ display: 'block' }, extra)
```
### Composed across files
A value imported from another module folds, as long as the extractor can resolve it statically:
```tsx
// styles.ts
export const button = css.raw({ display: 'inline-flex', padding: '4' })
// button.tsx
import { button } from './styles'
export const cls = css(button, { background: 'blue.500' })
// → "d_inline-flex p_4 bg_blue.500"
```
The same holds for plain exported objects, aliased imports, re-exports, and pure local helpers — including IIFEs:
```tsx
const pad = (n) => ({ padding: n })
css(pad('4')) // → "p_4"
```
When a fold reads from another module, the plugin registers that module as a watch dependency, so editing it
re-transforms the files that folded against it rather than leaving a stale literal behind.
The one cross-file shape that does **not** fold is an imported value spread inside a nested selector
(`css({ '& svg': { ...icon } })`). Extraction handles it and the CSS is still emitted — only the rewrite is declined,
for the spread reason below.
### Never folded
Three kinds of call never fold, because they do not evaluate to a class string at all:
- **`css.raw()`**, `recipe.raw()`, and `pattern.raw()` return a _style object_ so callers can compose them. Folding one
to a string would break every consumer.
- **`cva()` and `sva()`** return a function. Their definitions stay as they are.
- **`token()`** returns a token value, not a class.
### Why spreads are conservative
`{ ...base }` where `base` is a static local object _is_ resolvable, and Bamboo's extractor resolves it. But once the
extractor flattens a spread into its result, a spread it understood and a spread it silently skipped look identical —
both simply contribute keys, or fail to. Folding the second case would drop styles without any error.
Rather than guess, the fold declines any spread that is not an inline object literal.
## Partly static calls and elements
A single-argument `css()` call, or a `styled.*` element, does not have to be entirely static. The part that resolves
becomes a literal and the rest keeps its runtime call:
```tsx
css({ color: 'red.300', padding: p })
cx('c_red.300', css({ padding: p }))
Content nested in dark theme.
Box
Box