# Cherry Design System

> Full documentation for Cherry Design System.

---

# Introduction

> Cherry is a design system for the modern web. Designed in Figma, built in React using TypeScript and Styled Components.

Source: https://cherry.al/

# Cherry Design System

Cherry is a design system for the modern web. Designed in Figma, built in React using TypeScript.

In the world of design and development, consistency is key. Every page, every component, and every interaction should adhere to a set of fundamental principles. The Cherry Design System is your reliable companion for maintaining harmony between design and development.

## Why a Design System?

1. **Consistency** - A design system ensures that basic elements remain consistent across all pages. Whether it's buttons, typography, or spacing, users should experience a seamless visual language.
2. **Efficiency** - For meticulously crafted projects, a robust design system streamlines workflows. It bridges the gap between designers and developers, fostering collaboration and efficiency.
3. **Foundations** - A good design system lays down the groundwork. It establishes rules, guidelines, and best practices, allowing teams to build upon a solid foundation.

## What Cherry Offers

- **Figma Designs** - Meticulously crafted Figma designs for all the design primitives. From buttons to inputs, we've got you covered.
- **Figma Plugin** - Extract default theme tokens automatically, ensuring consistency across your entire project.
- **Open Source React Components** - Cherry provides open source React components via `cherry-styled-components` for the default implementation. Meant to be customized and built upon.
- **Theming & Dark Mode** - Fully typed light and dark themes with SSR-safe, flash-free dark mode.

<Callout type="info">
  Cherry intentionally focuses on providing the essential building blocks that most interfaces require. Simplicity often leads to elegance.
</Callout>

These docs are split in two: you are reading the **Design** section; switch to **Code** in the header for installation and the full component API.

<Columns cols={2}>
  <Card title="Live Demo" icon="play" href="https://demo.cherry.al/">
    See every component in one interactive playground.
  </Card>
  <Card title="Figma" icon="frame" href="/figma">
    Start with the Figma template and plugin.
  </Card>
  <Card title="Colors" icon="palette" href="/colors">
    Explore the color palette for light and dark modes.
  </Card>
  <Card title="Typography" icon="type" href="/typography">
    Typography scales for desktop and mobile.
  </Card>
  <Card title="Shadows" icon="layers" href="/shadows">
    Shadow elevation system for depth and hierarchy.
  </Card>
  <Card title="Icons" icon="smile" href="/icons">
    Over 1,500 Lucide icons on a consistent grid.
  </Card>
  <Card title="Installation" icon="download" href="/code/installation">
    Install cherry-styled-components and set up the providers.
  </Card>
  <Card title="Component API" icon="compass" href="/code">
    Props and usage docs for every React component.
  </Card>
</Columns>

---

# Figma

> Get started with the Cherry Design System Figma template and plugin for extracting design tokens.

Source: https://cherry.al/figma

# Figma

When embarking on the design process, Figma is an excellent tool to kick things off.

## 1. Download the Template

Begin by obtaining the Cherry template from Figma Community. This serves as your foundation for all design work.

<Button href="https://www.figma.com/community/file/943862931766586094/Cherry-Design-System" icon="pen-tool" iconPosition="left">
  Figma Template
</Button>

## 2. File Structure: Pages

The template is organized into four pages:

- **🎨 Foundations** - The design primitives, grouped into sections: **Color** (the full palette previewed in light and dark mode), **Typography** (heading and body styles at desktop and mobile sizes), and **Elevation** (shadow styles).
- **🧩 Components** - Reusable design elements that streamline your workflow. Every component is a variant set bound to the Figma variables, so all of them adapt to dark mode automatically: Button, IconButton, Input, Password, Textarea, Select, Checkbox, Radio, Toggle, Range, ThemeToggle, Modal, Toast, Accordion, Tabs, Dropzone, and AvatarDropzone. The section also includes the assembled Tabs component and a Box helper.
- **🌍 Examples** - A sample landing page composed entirely of Cherry components, provided in light and dark mode.
- **🌐 Assets** - Icons associated with a website or application: favicons, Apple touch icons, Google manifest icons, and the Open Graph social image.

## 3. Figma Variables

Cherry uses Figma variables to store design values. These values create design tokens. Variables are organized into collections:

| Variable Collection | Purpose                                                                                                                |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Colors**          | Color values grouped into Primary, Secondary, Tertiary, Gray, and UI, with a Light Mode and a Dark Mode                |
| **Font Family**     | Font families for text, headings, and monospace                                                                        |
| **Font Sizes**      | Font size definitions with `lg` (desktop) and `xs` (mobile) modes                                                      |
| **Font Weights**    | Font weights for text, headings, and buttons (Figma preview only - the extracted theme file has no font-weight tokens) |
| **Grid Gap**        | Grid gaps for visually appealing layouts                                                                               |
| **Line Heights**    | Line height definitions with `lg` (desktop) and `xs` (mobile) modes                                                    |
| **Max Width**       | Max width values for `xs` and `xxxl`                                                                                   |
| **Media Queries**   | Breakpoints: `xs`, `sm`, `md`, `lg`, `xl`, `xxl`, `xxxl`                                                               |
| **Padding**         | Padding sizes for `xs` and `lg`                                                                                        |
| **Radius**          | Border radius for `xs`, `lg`, and `xl`                                                                                 |

## 4. Typography

Inside Figma, typography is driven by the Font Family, Font Sizes, Font Weights, and Line Heights variables. Adjust the definitions there and you'll see a live preview in the Typography section of the Foundations page. Keep in mind that Font Weights only affect the Figma preview: the theme file has no font-weight tokens, since weights are set directly in each component's CSS.

## 5. Local Styles

Local styles are only used for shadows. There are two sets of five elevations (`XS` to `XL`): one for light mode and one for dark mode (`Dark/XS` to `Dark/XL`). They are previewed in the Elevation section of the Foundations page.

## 6. Extract Design Tokens

Cherry has its own **Figma Plugin** to extract design tokens automatically. The plugin gives you the theme file - copy it into your app's theme file (for example `app/theme.ts`) and pass it to the theme provider. See the [Theme](/code/theme) page for how to consume a custom theme object.

<Button href="https://www.figma.com/community/plugin/1091785956842659849/Cherry-Theme-Generator" icon="puzzle" iconPosition="left">
  Figma Plugin
</Button>

---

# Colors

> Cherry's curated color palette with 18 predefined colors for light and dark themes.

Source: https://cherry.al/colors

# Colors

Cherry offers a curated set of predefined colors to kickstart your interface design. Depending on your specific requirements, you can always tweak or expand this palette. However, in most scenarios, the default palette of 18 colors should suffice.

<Tabs>
  <TabContent title="Light Mode">

### Primary

<ColorSwatchGroup>
  <ColorSwatch token="primaryLight" value="#91AEC4" />
  <ColorSwatch token="primary" value="#4D6F8B" />
  <ColorSwatch token="primaryDark" value="#194569" />
</ColorSwatchGroup>

### Secondary

<ColorSwatchGroup>
  <ColorSwatch token="secondaryLight" value="#A4B17B" />
  <ColorSwatch token="secondary" value="#5C6E46" />
  <ColorSwatch token="secondaryDark" value="#354C2B" />
</ColorSwatchGroup>

### Tertiary

<ColorSwatchGroup>
  <ColorSwatch token="tertiaryLight" value="#EBCCB9" />
  <ColorSwatch token="tertiary" value="#816B5A" />
  <ColorSwatch token="tertiaryDark" value="#675445" />
</ColorSwatchGroup>

### Gray

<ColorSwatchGroup>
  <ColorSwatch token="grayLight" value="#E5E7EB" />
  <ColorSwatch token="gray" value="#9CA3AF" />
  <ColorSwatch token="grayDark" value="#4B5563" />
</ColorSwatchGroup>

### Status

<ColorSwatchGroup>
  <ColorSwatch token="success" value="#84CC16" />
  <ColorSwatch token="error" value="#EF4444" />
  <ColorSwatch token="warning" value="#EAB308" />
  <ColorSwatch token="info" value="#06B6D4" />
</ColorSwatchGroup>

### Neutrals

<ColorSwatchGroup>
  <ColorSwatch token="dark" value="#000000" />
  <ColorSwatch token="light" value="#FFFFFF" />
</ColorSwatchGroup>

  </TabContent>
  <TabContent title="Dark Mode">

In addition to the primary color palette, Cherry provides the same variables for Dark Mode. This allows seamless switching between light and dark modes with a single click in Figma.

### Primary

<ColorSwatchGroup>
  <ColorSwatch token="primaryLight" value="#79C5FF" />
  <ColorSwatch token="primary" value="#6198C6" />
  <ColorSwatch token="primaryDark" value="#339DF4" />
</ColorSwatchGroup>

### Secondary

<ColorSwatchGroup>
  <ColorSwatch token="secondaryLight" value="#A4B17B" />
  <ColorSwatch token="secondary" value="#5C6E46" />
  <ColorSwatch token="secondaryDark" value="#354C2B" />
</ColorSwatchGroup>

### Tertiary

<ColorSwatchGroup>
  <ColorSwatch token="tertiaryLight" value="#EBCCB9" />
  <ColorSwatch token="tertiary" value="#816B5A" />
  <ColorSwatch token="tertiaryDark" value="#675445" />
</ColorSwatchGroup>

### Gray (Dark Mode)

<ColorSwatchGroup>
  <ColorSwatch token="grayLight" value="#1A1A1A" />
  <ColorSwatch token="gray" value="#454444" />
  <ColorSwatch token="grayDark" value="#808080" />
</ColorSwatchGroup>

### Status

<ColorSwatchGroup>
  <ColorSwatch token="success" value="#84CC16" />
  <ColorSwatch token="error" value="#EF4444" />
  <ColorSwatch token="warning" value="#EAB308" />
  <ColorSwatch token="info" value="#06B6D4" />
</ColorSwatchGroup>

### Neutrals (Inverted)

<ColorSwatchGroup>
  <ColorSwatch token="dark" value="#FFFFFF" />
  <ColorSwatch token="light" value="#000000" />
</ColorSwatchGroup>

  </TabContent>
</Tabs>

## Using the tokens

Every color above is available as a token on the theme object, so you can reference it by name in any styled-component:

```tsx
const Title = styled.h2`
  color: ${({ theme }) => theme.colors.primary};
`;
```

<Callout type="info">
  To use these colors in code, see the [Theme](/code/theme) and [Dark Mode](/code/dark-mode) pages.
</Callout>

<Callout type="note">
  Colors can be found in the Figma Template in the Color section of the
  Foundations page.
</Callout>

<Button href="https://www.figma.com/community/file/943862931766586094/Cherry-Design-System" icon="pen-tool" iconPosition="left">
  View in Figma
</Button>

---

# Typography

> Cherry's responsive typography system with definitions for desktop and mobile breakpoints.

Source: https://cherry.al/typography

# Typography

Cherry offers two distinct sets of typography definitions: one for desktop and another for mobile. These comprehensive definitions ensure that type displays correctly on screens of all sizes. The **Desktop (LG)** values apply from the `lg` breakpoint (992px) and up, while the **Mobile (XS)** values are the base scale used on narrower screens.

<Tabs>
  <TabContent title="Desktop (LG)">

| Style        | Font  | Size  | Line Height | Weight |
| ------------ | ----- | ----- | ----------- | ------ |
| Hero1        | Inter | 128px | 1.1         | 700    |
| Hero2        | Inter | 96px  | 1.1         | 700    |
| Hero3        | Inter | 72px  | 1.1         | 700    |
| H1           | Inter | 60px  | 1.4         | 700    |
| H2           | Inter | 36px  | 1.5         | 700    |
| H3           | Inter | 30px  | 1.5         | 700    |
| H4           | Inter | 24px  | 1.5         | 700    |
| H5           | Inter | 20px  | 1.5         | 700    |
| H6           | Inter | 18px  | 1.6         | 700    |
| Text         | Inter | 16px  | 1.7         | 400    |
| Strong       | Inter | 16px  | 1.7         | 700    |
| Small        | Inter | 14px  | 1.7         | 400    |
| Blockquote   | Inter | 18px  | 1.7         | 400    |
| Code         | Mono  | 16px  | 1.7         | 400    |
| Button Small | Inter | 14px  | 1.0         | 600    |
| Button       | Inter | 16px  | 1.0         | 600    |
| Button Big   | Inter | 18px  | 1.0         | 600    |
| Input Small  | Inter | 14px  | 1.0         | 400    |
| Input        | Inter | 16px  | 1.0         | 400    |
| Input Big    | Inter | 18px  | 1.0         | 400    |

  </TabContent>
  <TabContent title="Mobile (XS)">

| Style        | Font  | Size | Line Height | Weight |
| ------------ | ----- | ---- | ----------- | ------ |
| Hero1        | Inter | 72px | 1.1         | 700    |
| Hero2        | Inter | 60px | 1.1         | 700    |
| Hero3        | Inter | 36px | 1.2         | 700    |
| H1           | Inter | 40px | 1.5         | 700    |
| H2           | Inter | 30px | 1.5         | 700    |
| H3           | Inter | 28px | 1.3         | 700    |
| H4           | Inter | 26px | 1.3         | 700    |
| H5           | Inter | 18px | 1.6         | 700    |
| H6           | Inter | 16px | 1.6         | 700    |
| Text         | Inter | 14px | 1.7         | 400    |
| Strong       | Inter | 14px | 1.7         | 700    |
| Small        | Inter | 12px | 1.7         | 400    |
| Blockquote   | Inter | 16px | 1.7         | 400    |
| Code         | Mono  | 14px | 1.7         | 400    |
| Button Small | Inter | 14px | 1.0         | 600    |
| Button       | Inter | 16px | 1.0         | 600    |
| Button Big   | Inter | 18px | 1.0         | 600    |
| Input Small  | Inter | 14px | 1.0         | 400    |
| Input        | Inter | 16px | 1.0         | 400    |
| Input Big    | Inter | 18px | 1.0         | 400    |

  </TabContent>
</Tabs>

<Callout type="note">
  The Weight column is part of the design spec. In code, the typography mixins
  only set `font-size` and `line-height`, so heading weights come from the
  browser's bold defaults for `h1` to `h6` unless you set `font-weight`
  yourself. The Button (600) and Input (400) components set their own weights.
</Callout>

## Usage

Nearly every style above is available as a ready-made CSS mixin exported from `cherry-styled-components`: `styledHero1`, `styledHero2`, `styledHero3`, `styledH1` through `styledH6`, `styledText`, `styledStrong`, `styledSmall`, `styledBlockquote`, `styledCode`, `styledButton`, `styledButtonBig`, `styledInput`, and `styledInputBig`. Each mixin takes the theme and returns the responsive `font-size` and `line-height`, switching from the mobile to the desktop values at the `lg` breakpoint:

```tsx
import styled from "styled-components";
import { styledH1 } from "cherry-styled-components";

const Title = styled.h2`
  ${({ theme }) => styledH1(theme)}
`;
```

For scales without a dedicated mixin (like Button Small and Input Small) or for custom theme keys, use the `createTypographyStyle` factory, e.g. `createTypographyStyle("buttonSmall")`.

<Callout type="info">
  To apply these styles in code, use the exported [typography
  helpers](/code/typography), and see [Theme](/code/theme) for font tokens.
</Callout>

<Callout type="note">
  Styles can be found in the Figma Template in the Typography section of the
  Foundations page.
</Callout>

<Button href="https://www.figma.com/community/file/943862931766586094/Cherry-Design-System" icon="pen-tool" iconPosition="left">
  View in Figma
</Button>

---

# Shadows

> Cherry's shadow elevation system with five levels for light and dark modes.

Source: https://cherry.al/shadows

# Shadows

Cherry offers several shadow variations that allow you to create elevations and add depth to your interfaces. Shadows play a crucial role in enhancing the visual hierarchy of elements, providing a sense of depth and realism.

There are two sets of shadows, one for dark mode and one for light mode.

<iframe className="light-only" src="https://demo.cherry.al/preview/shadows?theme=light" title="Shadow elevations" loading="lazy" style={{ width: "100%", height: "500px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/shadows?theme=dark" title="Shadow elevations" loading="lazy" style={{ width: "100%", height: "500px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

<Tabs>
  <TabContent title="Light Mode">

| Level  | Value                                                                        |
| ------ | ---------------------------------------------------------------------------- |
| **xs** | `0px 4px 4px 0px rgba(18,18,18,0.04), 0px 1px 3px 0px rgba(39,41,45,0.02)`   |
| **sm** | `0px 4px 4px 0px rgba(18,18,18,0.08), 0px 1px 3px 0px rgba(39,41,45,0.04)`   |
| **md** | `0px 8px 8px 0px rgba(18,18,18,0.16), 0px 2px 3px 0px rgba(39,41,45,0.06)`   |
| **lg** | `0px 16px 24px 0px rgba(18,18,18,0.20), 0px 2px 3px 0px rgba(39,41,45,0.08)` |
| **xl** | `0px 24px 32px 0px rgba(18,18,18,0.24), 0px 2px 3px 0px rgba(39,41,45,0.12)` |

  </TabContent>
  <TabContent title="Dark Mode">

| Level  | Value                                                                              |
| ------ | ---------------------------------------------------------------------------------- |
| **xs** | `0px 4px 4px 0px rgba(255,255,255,0.04), 0px 1px 3px 0px rgba(255,255,255,0.02)`   |
| **sm** | `0px 4px 4px 0px rgba(255,255,255,0.08), 0px 1px 3px 0px rgba(255,255,255,0.04)`   |
| **md** | `0px 8px 8px 0px rgba(255,255,255,0.16), 0px 2px 3px 0px rgba(255,255,255,0.06)`   |
| **lg** | `0px 16px 24px 0px rgba(255,255,255,0.20), 0px 2px 3px 0px rgba(255,255,255,0.08)` |
| **xl** | `0px 24px 32px 0px rgba(255,255,255,0.24), 0px 2px 3px 0px rgba(255,255,255,0.12)` |

  </TabContent>
</Tabs>

## Usage

Shadows live on the theme object under `theme.shadows`, keyed by level (`xs`, `sm`, `md`, `lg`, `xl`). Reference them in your styled components and the matching set is applied automatically in light and dark mode:

```tsx
import styled from "styled-components";

const Card = styled.div`
  box-shadow: ${({ theme }) => theme.shadows.md};
`;
```

The raw values are also exported as `shadows` and `shadowsDark` from `cherry-styled-components` if you need them outside the theme.

<Callout type="info">
  Shadow tokens live on the theme object; see [Theme](/code/theme) for setup.
</Callout>

<Callout type="note">
  Shadows can be found in the Figma Template in the Elevation section of the
  Foundations page.
</Callout>

<Button href="https://www.figma.com/community/file/943862931766586094/Cherry-Design-System" icon="pen-tool" iconPosition="left">
  View in Figma
</Button>

---

# Icons

> Cherry uses the Lucide icon set - over 1,500 consistent, open-source icons available in every component.

Source: https://cherry.al/icons

# Icons

Cherry uses [Lucide](https://lucide.dev), an open-source icon set with over 1,500 icons drawn on a consistent 24x24 grid with a 2px rounded stroke. Leaning on one primary set keeps iconography coherent across your interface, and the outline style pairs naturally with Cherry's borders and typography.

Lucide icons inherit the current text color, so they adapt to light and dark mode automatically along with the component they sit in.

## Where icons appear

Several Cherry components ship with built-in Lucide icons:

- **Accordion** - the rotating chevron (`ChevronDown`)
- **Modal** - the close button (`X`)
- **Toast** - a per-status icon (`CircleCheck`, `CircleX`, `TriangleAlert`, `Info`) plus the dismiss button (`X`)
- **Password** - the visibility toggle (`Eye`, `EyeOff`)
- **ThemeToggle** - the sun and moon (`Sun`, `MoonStar`)
- **Dropzone / AvatarDropzone** - the drop-area glyph, customizable via the `$icon` prop (Dropzone defaults to `FileUp`, AvatarDropzone to `User`); Dropzone's file thumbnails also use `File` and `X`
- **Input** - the checkbox check mark (`Check`) and the calendar glyph on date and time inputs (`CalendarDays`)
- **Select** - the dropdown arrow (`ChevronDown`)
- **IconButton** - accepts any icon as its content

## Choosing icons

Browse the full set at [lucide.dev/icons](https://lucide.dev/icons). Icons are referenced by their PascalCase name (for example `Settings`, `Trash2`, `ImageUp`). In code, render them with the [Icon](/code/icon) component; designers can use the official [Lucide Figma plugin](https://www.figma.com/community/plugin/939567362549682242/lucide-icons) to place the same icons in mockups.

```jsx
import { Icon } from "cherry-styled-components";

<Icon name="Heart" />;
```

<Callout type="note">
  Keep icon usage purposeful: prefer familiar glyphs for common actions
  (pencil for edit, trash for delete) and pair less obvious icons with a
  visible label.
</Callout>

<Button href="https://lucide.dev/icons" icon="external-link" iconPosition="left">
  Browse Lucide Icons
</Button>

---

# Buttons

> Cherry button design specifications with three variations, sizes, outline variants, icon buttons, and all interactive states.

Source: https://cherry.al/buttons

# Buttons

Cherry offers three color variations of buttons: Primary, Secondary, and Tertiary. Each variation comes in three sizes (Small, Default, and Big) with optional outline styling.

## States

When customizing your designs, consider all the different states that buttons can have:

1. **Normal** - The default appearance of the button.
2. **Hover** `:hover` - When the user hovers the cursor over the button.
3. **Active** `:active` - When the button is clicked or pressed.
4. **Focus** `:focus` - When the button gains focus.
5. **Disabled** - When the button cannot be interacted with.

<Callout type="warning">
  Ensure that your designs account for all these states to provide a consistent
  and user-friendly experience.
</Callout>

## Variations

Beyond the color variations below, regular buttons also support a full-width option that stretches the button to the full width of its container, an error variant for destructive actions (available in both filled and outline styles), and inline icons placed on either side of the label.

### Primary

<iframe className="light-only" src="https://demo.cherry.al/preview/button?theme=light" title="Primary button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/button?theme=dark" title="Primary button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

<iframe className="light-only" src="https://demo.cherry.al/preview/button-outline?theme=light" title="Primary outline button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/button-outline?theme=dark" title="Primary outline button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Size    | Filled | Outline | Disabled |
| ------- | ------ | ------- | -------- |
| Small   | Yes    | Yes     | Yes      |
| Default | Yes    | Yes     | Yes      |
| Big     | Yes    | Yes     | Yes      |

### Secondary

<iframe className="light-only" src="https://demo.cherry.al/preview/button-secondary?theme=light" title="Secondary button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/button-secondary?theme=dark" title="Secondary button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Size    | Filled | Outline | Disabled |
| ------- | ------ | ------- | -------- |
| Small   | Yes    | Yes     | Yes      |
| Default | Yes    | Yes     | Yes      |
| Big     | Yes    | Yes     | Yes      |

### Tertiary

<iframe className="light-only" src="https://demo.cherry.al/preview/button-tertiary?theme=light" title="Tertiary button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/button-tertiary?theme=dark" title="Tertiary button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Size    | Filled | Outline | Disabled |
| ------- | ------ | ------- | -------- |
| Small   | Yes    | Yes     | Yes      |
| Default | Yes    | Yes     | Yes      |
| Big     | Yes    | Yes     | Yes      |

## Icon Buttons

Icon buttons are circular, icon-only buttons for compact actions like edit, delete, or settings. They come in three sizes (24px, 28px, and 32px) and support all interactive states, an error variant for destructive actions, and an active "on" state (primary border with a translucent primary tint) for toggle-like actions such as an open dropzone or an active preview.

Because icon buttons have no visible text, every icon button requires an `aria-label` describing its action. The active "on" state is exposed to assistive technology as `aria-pressed`.

<iframe className="light-only" src="https://demo.cherry.al/preview/icon-button?theme=light" title="Icon button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/icon-button?theme=dark" title="Icon button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Size    | Default | Error | Active | Disabled |
| ------- | ------- | ----- | ------ | -------- |
| Small   | Yes     | Yes   | Yes    | Yes      |
| Default | Yes     | Yes   | Yes    | Yes      |
| Big     | Yes     | Yes   | Yes    | Yes      |

<Callout type="info">
  Ready to build? See the [Button](/code/button) and
  [IconButton](/code/icon-button) component docs for props and usage examples.
</Callout>

<Callout type="note">
  Buttons can be found in the Figma Template in the Components page, alongside
  the IconButton component set.
</Callout>

<Button href="https://www.figma.com/community/file/943862931766586094/Cherry-Design-System" icon="pen-tool" iconPosition="left">
  View in Figma
</Button>

---

# Inputs

> Cherry input design specifications covering text fields, password fields, checkboxes, radios, toggles, range sliders, and dropzones.

Source: https://cherry.al/inputs

# Inputs

Cherry offers several variations for input elements. Inputs facilitate user interaction with applications. While there are no color variations for inputs, Cherry provides three sizes: Small, Default, and Big. Inputs can have error or success states to provide feedback to the user.

## States

When customizing your designs, consider all the different states:

1. **Normal** - The default appearance of the input.
2. **Hover** `:hover` - When the user hovers the cursor over the input.
3. **Active** `:active` - When the input is clicked or pressed.
4. **Focus** `:focus` - When the input gains focus.
5. **Checked** `:checked` - Depending on the type of input, additional states may apply.
6. **Disabled** - When the input cannot be interacted with.

<Callout type="warning">
  Ensure that your designs account for all these states to provide a consistent
  and user-friendly experience.
</Callout>

## Text Input

<iframe className="light-only" src="https://demo.cherry.al/preview/input?theme=light" title="Text input" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/input?theme=dark" title="Text input" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Size    | Default | Success | Error | Disabled |
| ------- | ------- | ------- | ----- | -------- |
| Small   | Yes     | Yes     | Yes   | Yes      |
| Default | Yes     | Yes     | Yes   | Yes      |
| Big     | Yes     | Yes     | Yes   | Yes      |

Implementation: [Input](/code/input)

## Password

Password fields extend the text input with a reveal toggle pinned inside the field. The revealed state swaps the masked dots for plain text and flips the eye icon.

<iframe className="light-only" src="https://demo.cherry.al/preview/password?theme=light" title="Password field" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/password?theme=dark" title="Password field" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Size    | Default | Revealed | Success | Error | Disabled |
| ------- | ------- | -------- | ------- | ----- | -------- |
| Small   | Yes     | Yes      | Yes     | Yes   | Yes      |
| Default | Yes     | Yes      | Yes     | Yes   | Yes      |
| Big     | Yes     | Yes      | Yes     | Yes   | Yes      |

Implementation: [Password](/code/password)

## Textarea

Textareas are multi-line text fields for longer content. They share the text input's border, focus ring, and status states.

<iframe className="light-only" src="https://demo.cherry.al/preview/textarea?theme=light" title="Textarea" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/textarea?theme=dark" title="Textarea" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Size    | Default | Success | Error | Disabled |
| ------- | ------- | ------- | ----- | -------- |
| Small   | Yes     | Yes     | Yes   | Yes      |
| Default | Yes     | Yes     | Yes   | Yes      |
| Big     | Yes     | Yes     | Yes   | Yes      |

Implementation: [Textarea](/code/textarea)

## Select

Selects are dropdown pickers styled to match the text input, with an arrow indicator that flips while the select is focused or open.

<iframe className="light-only" src="https://demo.cherry.al/preview/select?theme=light" title="Select" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/select?theme=dark" title="Select" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Size    | Default | Success | Error | Disabled |
| ------- | ------- | ------- | ----- | -------- |
| Small   | Yes     | Yes     | Yes   | Yes      |
| Default | Yes     | Yes     | Yes   | Yes      |
| Big     | Yes     | Yes     | Yes   | Yes      |

Implementation: [Select](/code/select)

## Checkbox

<iframe className="light-only" src="https://demo.cherry.al/preview/checkbox?theme=light" title="Checkbox" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/checkbox?theme=dark" title="Checkbox" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Size    | Default | Success | Error | Disabled |
| ------- | ------- | ------- | ----- | -------- |
| Small   | Yes     | Yes     | Yes   | Yes      |
| Default | Yes     | Yes     | Yes   | Yes      |
| Big     | Yes     | Yes     | Yes   | Yes      |

Implementation: [Input](/code/input)

## Radio

<iframe className="light-only" src="https://demo.cherry.al/preview/radio?theme=light" title="Radio button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/radio?theme=dark" title="Radio button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Size    | Default | Success | Error | Disabled |
| ------- | ------- | ------- | ----- | -------- |
| Small   | Yes     | Yes     | Yes   | Yes      |
| Default | Yes     | Yes     | Yes   | Yes      |
| Big     | Yes     | Yes     | Yes   | Yes      |

Implementation: [Input](/code/input)

## Toggle

<iframe className="light-only" src="https://demo.cherry.al/preview/toggle?theme=light" title="Toggle" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/toggle?theme=dark" title="Toggle" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Size    | Default | Success | Error | Disabled |
| ------- | ------- | ------- | ----- | -------- |
| Small   | Yes     | Yes     | Yes   | Yes      |
| Default | Yes     | Yes     | Yes   | Yes      |
| Big     | Yes     | Yes     | Yes   | Yes      |

Implementation: [Toggle](/code/toggle)

## Range

<iframe className="light-only" src="https://demo.cherry.al/preview/range?theme=light" title="Range slider" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/range?theme=dark" title="Range slider" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Size    | Default | Success | Error | Disabled |
| ------- | ------- | ------- | ----- | -------- |
| Small   | Yes     | Yes     | Yes   | Yes      |
| Default | Yes     | Yes     | Yes   | Yes      |
| Big     | Yes     | Yes     | Yes   | Yes      |

Implementation: [Range](/code/range)

## Dropzone

Dropzones are file inputs rendered as dashed drop targets, with a compact inline variant for embedding in forms and modals.

<iframe className="light-only" src="https://demo.cherry.al/preview/dropzone?theme=light" title="Dropzone" loading="lazy" style={{ width: "100%", height: "400px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/dropzone?theme=dark" title="Dropzone" loading="lazy" style={{ width: "100%", height: "400px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

<iframe className="light-only" src="https://demo.cherry.al/preview/dropzone-inline?theme=light" title="Inline dropzone" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/dropzone-inline?theme=dark" title="Inline dropzone" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Variant | Default | Drag Over | Disabled |
| ------- | ------- | --------- | -------- |
| Block   | Yes     | Yes       | Yes      |
| Inline  | Yes     | Yes       | Yes      |

Implementation: [Dropzone](/code/dropzone)

## Avatar Dropzone

Avatar dropzones are circular, single-file dropzones for profile pictures. The circle is dashed while empty and shows the selected picture with a corner remove button once filled.

<iframe className="light-only" src="https://demo.cherry.al/preview/avatar-dropzone?theme=light" title="Avatar dropzone" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/avatar-dropzone?theme=dark" title="Avatar dropzone" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Size           | Empty | Filled | Drag Over | Disabled |
| -------------- | ----- | ------ | --------- | -------- |
| Small (64px)   | Yes   | Yes    | Yes       | Yes      |
| Default (96px) | Yes   | Yes    | Yes       | Yes      |
| Big (128px)    | Yes   | Yes    | Yes       | Yes      |

Implementation: [AvatarDropzone](/code/avatar-dropzone)

<Callout type="note">
  Inputs can be found in the Figma Template in the Components page, alongside
  the Password, Dropzone, and AvatarDropzone component sets.
</Callout>

<Button href="https://www.figma.com/community/file/943862931766586094/Cherry-Design-System" icon="pen-tool" iconPosition="left">
  View in Figma
</Button>

---

# Accordions

> Cherry accordion design specifications with card and inline variants.

Source: https://cherry.al/accordions

# Accordions

Accordions show and hide content behind a clickable title, keeping dense pages scannable. The chevron rotates to mirror the open state, and the open and close motion is animated.

## States

When customizing your designs, consider all the different states that accordions can have:

1. **Normal** - The default appearance of the accordion.
2. **Hover** `:hover` - When the user hovers the cursor over the title.
3. **Focus** - When the accordion title gains focus.
4. **Open / Closed** - The content expands or collapses, and the chevron rotates to match.

<Callout type="warning">
  Ensure that your designs account for all these states to provide a consistent
  and user-friendly experience.
</Callout>

## Variations

<iframe className="light-only" src="https://demo.cherry.al/preview/accordion?theme=light" title="Card accordion" loading="lazy" style={{ width: "100%", height: "340px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/accordion?theme=dark" title="Card accordion" loading="lazy" style={{ width: "100%", height: "340px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

<iframe className="light-only" src="https://demo.cherry.al/preview/accordion-inline?theme=light" title="Inline accordion" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/accordion-inline?theme=dark" title="Inline accordion" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Variation | Open | Closed |
| --------- | ---- | ------ |
| Card      | Yes  | Yes    |
| Inline    | Yes  | Yes    |

- **Card** - A bordered, rounded surface with generous padding. Use it when the accordion stands on its own.
- **Inline** - No border, radius, or side padding. Use it inside cards, lists, or other surfaces that already provide their own container. Enabled in code with the `$inline` prop.

In code, both variations use the same `Accordion` component:

```jsx
import { Accordion } from "cherry-styled-components";

<Accordion title="Title">Content</Accordion>;
```

The accordion manages its own open state and starts closed; use `defaultOpen` to start it open, or pass `open` together with `onToggle` to control it from the parent.

<Callout type="info">
  Ready to build? See the [Accordion](/code/accordion) component docs for props
  and usage examples.
</Callout>

<Callout type="note">
  Accordions can be found in the Figma Template in the Components page.
</Callout>

<Button href="https://www.figma.com/community/file/943862931766586094/Cherry-Design-System" icon="pen-tool" iconPosition="left">
  View in Figma
</Button>

---

# Tabs

> Cherry tabs design specifications with tab states and panel styling.

Source: https://cherry.al/tabs

# Tabs

Tabs group related content into panels behind a horizontal list of triggers. The active tab is highlighted with the primary color and a bottom indicator, and the panel below shares the same bordered, rounded surface as cards and accordions.

## States

When customizing your designs, consider all the different states that a tab trigger can have:

1. **Normal** - The resting appearance of an unselected tab.
2. **Hover** `:hover` - The label turns primary over a subtle primary tint.
3. **Focus** `:focus-visible` - A rounded primary outline inset within the tab for keyboard users. While a tab is focused, the ring replaces the selected tab's bottom indicator.
4. **Selected** - Primary label with a 3px primary bottom indicator.

<Callout type="warning">
  Ensure that your designs account for all these states to provide a consistent
  and user-friendly experience.
</Callout>

<iframe className="light-only" src="https://demo.cherry.al/preview/tabs?theme=light" title="Tabs" loading="lazy" style={{ width: "100%", height: "360px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/tabs?theme=dark" title="Tabs" loading="lazy" style={{ width: "100%", height: "360px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

<Callout type="info">
  Ready to build? See the [Tabs](/code/tabs) component docs for props and usage
  examples.
</Callout>

<Callout type="note">
  Tabs can be found in the Figma Template in the Components page as the Tab
  component set and the assembled Tabs component.
</Callout>

<Button href="https://www.figma.com/community/file/943862931766586094/Cherry-Design-System" icon="pen-tool" iconPosition="left">
  View in Figma
</Button>

---

# Overlays

> Cherry overlay design specifications for modals and toast notifications.

Source: https://cherry.al/overlays

# Overlays

Overlays sit on top of the page to demand attention or give feedback. Cherry provides two overlay elements: the Modal for blocking dialogs and the Toast for transient notifications.

## States

Both overlays are dismissed through an icon button: the close button on the Modal and the dismiss button on the Toast. When customizing your designs, consider all the different states these controls can have:

1. **Normal** - The default appearance of the control.
2. **Hover** `:hover` - When the user hovers the cursor over the control.
3. **Active** `:active` - When the control is clicked or pressed.
4. **Focus** `:focus` - When the control gains focus.

<Callout type="warning">
  Ensure that your designs account for all these states to provide a consistent
  and user-friendly experience.
</Callout>

## Modal

The modal is a centered dialog on a primary-tinted backdrop. It has an optional title with a divider, scrollable content, and a close icon button in the corner.

<iframe className="light-only" src="https://demo.cherry.al/preview/modal?theme=light" title="Modal" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/modal?theme=dark" title="Modal" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Variant       | Included |
| ------------- | -------- |
| With title    | Yes      |
| Without title | Yes      |

The dialog caps at 500px wide on large screens; a custom width (`$width`) overrides that cap. The close button can be hidden (`$hideCloseButton`) when the flow should own dismissal. For app-level restyling, the overlay accepts `className` and `style`, and the inner parts expose stable class hooks: `.modal-inner`, `.modal-close`, `.modal-title`, and `.modal-content`.

When designing modal flows, account for the three ways users dismiss it (two when the close button is hidden):

1. **Close button** - The icon button in the top-right corner.
2. **Escape** - Pressing the Escape key.
3. **Outside click** - Clicking the backdrop.

## Toast

Toasts are pill-shaped notifications with a semantic status icon, a message, and a close button. They stack vertically and animate in and out.

<iframe className="light-only" src="https://demo.cherry.al/preview/toast?theme=light" title="Toast notifications" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/toast?theme=dark" title="Toast notifications" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

| Color   | Icon           | Use for                    |
| ------- | -------------- | -------------------------- |
| Info    | Info           | Neutral information        |
| Success | Circle check   | Completed actions          |
| Error   | Circle x       | Failures                   |
| Warning | Triangle alert | Situations needing caution |

By default the stack is anchored to the top of the viewport and centered horizontally. It can be aligned left, center, or right (`$align`) and anchored to the bottom instead (`$bottom`); toasts slide in from the edge the stack is anchored to. When no color is given, a toast defaults to Info.

Toasts are persistent by default: auto-hide (`autoHide`) is a duration in milliseconds that defaults to 0, meaning off, so a toast stays on screen until the user dismisses it. Pass a duration to have the toast dismiss itself.

<Callout type="warning">
  Reserve persistent toasts (without auto-hide) for messages that require the
  user's acknowledgment. Transient confirmations should dismiss themselves.
</Callout>

In code, the Modal is controlled through its `$isOpen` and `$onClose` props. Toast is context-driven: wrap the app in `ToastNotificationsProvider`, render the `ToastNotifications` outlet once, and push messages with `useToastNotifications().addNotification`.

<Callout type="info">
  Ready to build? See the [Modal](/code/modal) and [Toast](/code/toast)
  component docs for props and usage examples.
</Callout>

<Callout type="note">
  Modal and Toast can be found in the Figma Template in the Components page.
</Callout>

<Button href="https://www.figma.com/community/file/943862931766586094/Cherry-Design-System" icon="pen-tool" iconPosition="left">
  View in Figma
</Button>

---

# Site Images

> Icons and thumbnail specifications for favicons, Apple Touch Icons, Google Manifest Icons, and social images.

Source: https://cherry.al/site-images

# Site Images

When designing interfaces for web applications, it's essential to include icons and thumbnails. These visual elements enhance user experience and provide a professional look.

## Image Types

<Steps>
  <Step title="Favicons" icon="image">
    Sizes: 32x32px (standard) and 16x16px (small). Favicons appear in browser tabs, bookmarks, and other places where your website is listed. They help users quickly identify your site.
  </Step>
  <Step title="Apple Touch Icons" icon="smartphone">
    Size: 180x180px. These icons are specifically for iOS devices. When users add your website to their home screen, this icon is displayed.
  </Step>
  <Step title="Google Manifest Icons" icon="app-window">
    Sizes: 256x256px and 192x192px. The manifest file specifies how your web app should behave when installed on an Android device. For full PWA installability, also include a 512x512px icon, since Chrome and Lighthouse expect the 192x192px and 512x512px pair.
  </Step>
  <Step title="Social Image" icon="share-2">
    Size: Around 1280x670px. This is the open graph image that serves as a preview when your website is shared on social media platforms. Make sure the image represents your site well and encourages users to click through.
  </Step>
</Steps>

<Callout type="info">
  Remember to include these icons and images in your project to create a cohesive and professional appearance for your web application.
</Callout>

Site images can be found in the Figma Template in the Assets page.

<Button href="https://www.figma.com/community/file/943862931766586094/Cherry-Design-System" icon="pen-tool" iconPosition="left">
  View in Figma
</Button>

---

# Overview

> Get started with Cherry's React components built with Styled Components and TypeScript.

Source: https://cherry.al/code

# Develop

Every component in the **Cherry Design System** is meticulously crafted using **React** and **Styled Components**. These building blocks empower you to create delightful user interfaces.

<CodeTabs tabs={[{ label: "npm", code: "npm install cherry-styled-components styled-components" }, { label: "pnpm", code: "pnpm add cherry-styled-components styled-components" }, { label: "yarn", code: "yarn add cherry-styled-components styled-components" }]} />

## Components

<Columns cols={2}>
  <Card title="Accordion" icon="chevrons-up-down" href="/code/accordion">
    Show and hide content behind a clickable, animated title.
  </Card>
  <Card title="AvatarDropzone" icon="circle-user-round" href="/code/avatar-dropzone">
    Circular single-file dropzone for profile pictures.
  </Card>
  <Card title="Button" icon="mouse-pointer-click" href="/code/button">
    The gateway to interaction. Various styles and states.
  </Card>
  <Card title="Dropzone" icon="upload" href="/code/dropzone">
    File drop target with drag & drop, validation, and previews.
  </Card>
  <Card title="Icon" icon="smile" href="/code/icon">
    Render any Lucide icon by name.
  </Card>
  <Card title="IconButton" icon="circle-plus" href="/code/icon-button">
    Circular icon-only button for compact actions.
  </Card>
  <Card title="Input" icon="text-cursor-input" href="/code/input">
    Text fields, checkboxes, radio buttons - everything input-related.
  </Card>
  <Card title="Modal" icon="app-window" href="/code/modal">
    Animated dialog with Escape and outside-click dismissal.
  </Card>
  <Card title="Password" icon="key-round" href="/code/password">
    Password input with a built-in show/hide reveal toggle.
  </Card>
  <Card title="Range" icon="sliders-horizontal" href="/code/range">
    Sliders for numeric input.
  </Card>
  <Card title="Select" icon="chevron-down" href="/code/select">
    Dropdown menus for options.
  </Card>
  <Card title="Tabs" icon="panels-top-left" href="/code/tabs">
    Accessible tabbed panels with keyboard navigation.
  </Card>
  <Card title="Textarea" icon="notebook-text" href="/code/textarea">
    Multiline text input for longer messages.
  </Card>
  <Card title="ThemeToggle" icon="sun-moon" href="/code/theme-toggle">
    Pill-shaped sun/moon switch for light and dark mode.
  </Card>
  <Card title="Toast" icon="bell" href="/code/toast">
    Transient notifications with semantic colors and auto-hide.
  </Card>
  <Card title="Toggle" icon="toggle-right" href="/code/toggle">
    Simplify binary choices.
  </Card>
</Columns>

## Layout

<Columns cols={2}>
  <Card title="Box" icon="box" href="/code/box">
    The versatile container for layout, spacing, or as a wrapper.
  </Card>
  <Card title="Col" icon="columns-3" href="/code/col">
    Create responsive column layouts with ease.
  </Card>
  <Card title="Container" icon="square" href="/code/container">
    A container for your content.
  </Card>
  <Card title="Flex" icon="stretch-horizontal" href="/code/flex">
    Arrange items horizontally or vertically.
  </Card>
  <Card title="Grid" icon="grid-3x3" href="/code/grid">
    Build grids effortlessly using CSS grid.
  </Card>
  <Card title="MaxWidth" icon="move-horizontal" href="/code/max-width">
    Control the maximum width of your content.
  </Card>
  <Card title="Space" icon="stretch-vertical" href="/code/space">
    Responsive vertical or horizontal spacing between elements.
  </Card>
</Columns>

## Cherry Helpers

<Columns cols={2}>
  <Card title="Global Styles" icon="globe" href="/code/global-styles">
    Consistency across your app. Define global rules here.
  </Card>
  <Card title="Hooks" icon="webhook" href="/code/hooks">
    Utility hooks like `useOnClickOutside` for floating UI.
  </Card>
  <Card title="Mixins" icon="blend" href="/code/mixins">
    Reusable code snippets. Efficiency meets elegance.
  </Card>
  <Card title="Theme" icon="paintbrush" href="/code/theme">
    Define spacings, colors, typography, and more.
  </Card>
  <Card title="Icons" icon="smile" href="/code/icon">
    Basic icons for elements like checkbox and dropdown arrow.
  </Card>
  <Card title="Typography" icon="type" href="/code/typography">
    Text matters. Set font styles and sizes effortlessly.
  </Card>
</Columns>

## Styled Components Helpers

- **[StyledComponentsRegistry](/code/installation)** - Renders CSS in your Next.js app.
- **[CherryThemeProvider](/code/installation)** - Wrap your app with the Cherry Theme context.
- **[ClientThemeProvider](/code/dark-mode)** - SSR-aware theme provider for flash-free dark mode.
- **[themeInitScript / createThemeInitScript](/code/dark-mode)** - Blocking head script that prevents the dark-mode flash.
- **[resolveTheme](/code/dark-mode)** - Resolve the `theme` cookie to a theme object in server code.
- **[ThemeContext](/code/dark-mode)** - Access `setTheme` and `toggleTheme` for custom theme controls.

## Next Steps

<Columns cols={2}>
  <Card title="Live Demo" icon="play" href="https://demo.cherry.al/">
    See every component in one interactive playground.
  </Card>
  <Card title="Installation" icon="download" href="/code/installation">
    Get started with development.
  </Card>
  <Card title="Dark Mode" icon="moon" href="/code/dark-mode">
    Flash-free dark mode with SSR support.
  </Card>
  <Card title="Changelog" icon="history" href="/code/changelog">
    Release notes for every version.
  </Card>
</Columns>

---

# Installation

> Install Cherry Styled Components via npm or by cloning the repository.

Source: https://cherry.al/code/installation

# Installation

There are two main ways to install Cherry Styled Components into your project. You can either clone the main repository and customize the components to your liking, or install the library from npm.

## Implementation Options

<Tabs>
  <TabContent title="NPM">

Install the Cherry library from npm along with its peer dependencies. Import components directly into your project. Perfect for smaller projects or rapid development. The library requires `react` and `react-dom` (^18 or ^19) and `styled-components` (^6) as peer dependencies.

<CodeTabs tabs={[{ label: "npm", code: "npm install cherry-styled-components react react-dom styled-components" }, { label: "pnpm", code: "pnpm add cherry-styled-components react react-dom styled-components" }, { label: "yarn", code: "yarn add cherry-styled-components react react-dom styled-components" }]} />

  </TabContent>
  <TabContent title="Repository">

Clone the main Cherry repository. Dive into the components' code and customize to your heart's content. Ideal for extensive modifications.

```bash
git clone git@github.com:cherry-design-system/styled-components.git
```

  </TabContent>
</Tabs>

## Theme Context

Always wrap your application in the `CherryThemeProvider` component. Ensure that your theme prop is passed down correctly. For server-rendered apps that need flash-free dark mode, use `ClientThemeProvider` instead - see [Dark Mode](/code/dark-mode).

```tsx
import { CherryThemeProvider, theme } from "cherry-styled-components";

export default function App({ children }) {
  return <CherryThemeProvider theme={theme}>{children}</CherryThemeProvider>;
}
```

## Next.js Integration

When integrating into a Next.js app, first install the dependencies:

<CodeTabs tabs={[{ label: "npm", code: "npm install cherry-styled-components react react-dom styled-components" }, { label: "pnpm", code: "pnpm add cherry-styled-components react react-dom styled-components" }, { label: "yarn", code: "yarn add cherry-styled-components react react-dom styled-components" }]} />

Next, enable the styled-components compiler in your `next.config.ts`. This keeps class names deterministic between server and client renders and avoids hydration mismatches:

<Code title="next.config.ts" language="ts" code={`import type { NextConfig } from "next";

  const nextConfig: NextConfig = {
    compiler: {
      styledComponents: true,
    },
  };

  export default nextConfig;`} />

To render the CSS, open your `layout.tsx` and wrap your application. The `StyledComponentsRegistry` component injects the server-rendered styles into the HTML via `useServerInsertedHTML`, so styled-components work with server-side rendering and the App Router:

<Code title="app/layout.tsx" language="tsx" code={`import {
    StyledComponentsRegistry,
    CherryThemeProvider,
    theme,
  } from "cherry-styled-components";

  export default function RootLayout({
    children,
  }: Readonly<{
    children: React.ReactNode;
  }>) {
    return (
      <html lang="en">
        <body>
          <StyledComponentsRegistry>
            <CherryThemeProvider theme={theme}>{children}</CherryThemeProvider>
          </StyledComponentsRegistry>
        </body>
      </html>
    );
  }`} />

<Callout type="info">
  Next.js requires these additional steps because it uses server-side rendering.
</Callout>

---

# Skill for AI Agents

> Teach Claude and other coding agents to build with Cherry correctly using the official Agent Skill.

Source: https://cherry.al/code/skill-for-ai-agents

# Skill for AI Agents

Cherry ships an official AI-assistant skill that teaches Claude and other coding agents to build with the library correctly: reach for a Cherry component for every button and form control, read design values from the theme instead of hardcoding them, and wire up the provider. Drop it into your project and your assistant stops guessing.

It is a [Claude Agent Skill](https://docs.claude.com/en/docs/claude-code/skills) - a `SKILL.md` plus on-demand `references/` covering setup, theme tokens, the full component API, and recipes - and it lives in the [`skills/cherry-design-system`](https://github.com/cherry-design-system/styled-components/tree/main/skills/cherry-design-system) folder of the library repo.

## Install

<Tabs>
  <TabContent title="skills CLI">

The [`skills` CLI](https://github.com/vercel-labs/skills) is the recommended, cross-agent path. It installs into the right directory for Claude Code, Cursor, Codex, and many other agents, detecting yours automatically.

<CodeTabs tabs={[{ label: "npm", code: "npx -y skills add cherry-design-system/styled-components" }, { label: "pnpm", code: "pnpm dlx skills add cherry-design-system/styled-components" }, { label: "yarn", code: "yarn dlx skills add cherry-design-system/styled-components" }]} />

Preview what would be installed with `--list`, update later with `npx skills update cherry-design-system`, and remove it with `npx skills remove cherry-design-system`.

  </TabContent>
  <TabContent title="Claude Code (manual)">

An Agent Skill is just a folder. Copy it into your skills directory - project-level to share it with your team, or personal for all your projects. Keep the `references/` folder alongside `SKILL.md`.

```bash
# project-level (committed, shared with your team)
cp -r cherry-design-system .claude/skills/

# or personal (all your projects)
cp -r cherry-design-system ~/.claude/skills/
```

  </TabContent>
  <TabContent title="Other agents">

For Cursor, Codex, Zed, and other tools that read a single guide file, copy the skill's self-contained `AGENTS.md` to your repository root (or append it to an existing `AGENTS.md`). It condenses the same rules into one file; the `references/` load on demand.

  </TabContent>
</Tabs>

## What the skill enforces

Once installed, the assistant follows Cherry's rules instead of improvising:

- **Every button is a Cherry `<Button>` or `<IconButton>`** - never a raw `<button>` or another library's button.
- **Every form control is a Cherry component** - `Input`, `Select`, `Textarea`, `Toggle`, `Range`, `Password`, `Dropzone`, `AvatarDropzone` (checkbox and radio are `<Input type="checkbox">` / `<Input type="radio">`).
- **No hardcoded design values** - colors, spacing, radii, shadows, and font sizes come from the theme, with typography mixins for text and `mq()` for breakpoints.
- **Styling props are `$`-prefixed** (`$variant`, `$size`, `$fullWidth`) and stay within their literal unions.
- **The app is wrapped in a Cherry provider**, uses the layout primitives (`Container`, `Grid`, `Col`, `Flex`, `Box`, `MaxWidth`, `Space`), and renders icons with `<Icon name="..." />`.

## Always-current docs

The bundled references are an offline snapshot. This site is the live source of truth, and every page is available as machine-readable markdown so an assistant can fetch the current API on demand:

- **Index of every page:** [`cherry.al/llms.txt`](https://cherry.al/llms.txt)
- **All docs in one file:** [`cherry.al/llms-full.txt`](https://cherry.al/llms-full.txt)
- **Any page as markdown:** append `.md` to its URL, e.g. [`cherry.al/code/button.md`](https://cherry.al/code/button.md)

<Callout type="info">
  The skill is documentation only. It contains no runtime code and is not part of the published npm package.
</Callout>

<Button href="https://github.com/cherry-design-system/styled-components/tree/main/skills/cherry-design-system" icon="code" iconPosition="left">
  View Skill on GitHub
</Button>

---

# Changelog

> Release notes for every cherry-styled-components version.

Source: https://cherry.al/code/changelog

# Changelog

Cherry Styled Components is currently at version `0.2.10`. The entries below are based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

<Update label="0.2.10" description="2026-07-08">

**Removed**

- **Breaking:** removed the custom `IconCheck`, `IconArrow`, and `IconCalendar` exports. They were hand-rolled SVGs duplicating existing Lucide glyphs. The form controls that used them now render the built-in `Icon` component instead: the checkbox check mark uses `Check`, the `Select` dropdown arrow uses `ChevronDown`, and the date/time calendar glyph uses `CalendarDays`. These icons now take their color from `currentColor` (the theme's primary color, applied via CSS) rather than a hard-coded stroke. The checkbox check mark renders with a 6px stroke, and the `Select` arrow now sizes to 24px to match the date/time calendar glyph. Replace any direct usage with `<Icon name="Check" />`, `<Icon name="ChevronDown" />`, or `<Icon name="CalendarDays" />`

</Update>

<Update label="0.2.9" description="2026-07-06">

**Added**

- AI assistant skill in `skills/cherry-design-system/`: a [Claude Agent Skill](https://docs.claude.com/en/docs/claude-code/skills) (`SKILL.md` plus `references/` covering setup, theme tokens, the full component API, and recipes) that teaches LLMs to build with Cherry correctly, always using Cherry components for buttons and form controls, reading design values from the theme, and wiring the provider. Includes a portable `AGENTS.md` for other agents and points at the live docs (`cherry.al/llms.txt` and per-page `.md`). Documentation only, not part of the published npm package; install with `npx skills add cherry-design-system/styled-components`

**Changed**

- `Accordion`: the clickable title is now a native `<button type="button">` (with a button reset) instead of an `<h3 role="button">`, so it is keyboard-focusable and Enter/Space-activatable natively; `aria-expanded` is preserved, and a `:focus-visible` outline in the primary color was added for keyboard users
- `Tabs`: tab labels bumped to `font-weight: 700` (was 600); the `:focus-visible` ring was retuned (corner `radius.xs` → `radius.lg`, inset `-4px` → `-2px`)
- `Input`: removed the unused `children` prop from `InputProps`. `Input` renders a void `<input>`, so any children were silently ignored; dropping it from the type turns that into a compile-time error

</Update>

<Update label="0.2.8" description="2026-07-04">

**Fixed**

- `Input`: small-size date and time inputs now render the calendar icon at 18px instead of the default 24px, with the native `::-webkit-calendar-picker-indicator` click target repositioned to stay aligned with the visible icon

</Update>

<Update label="0.2.7" description="2026-07-04">

**Fixed**

- `Dropzone` / `AvatarDropzone`: text now inherits the surrounding font family instead of pinning the theme's `fonts.text`, matching the `font-family: inherit` convention used by Button, Input, Select, and Textarea. The root `<button>` elements set `font-family: inherit` explicitly, since buttons don't inherit fonts by default

</Update>

<Update label="0.2.6" description="2026-07-04">

**Fixed**

- `Toast`: centered stacks no longer wrap their text prematurely. The notifications list is now a full-width strip (20px side margins) for every alignment instead of being anchored at `left: 50%`, which capped its shrink-to-fit width at about half the viewport, most visibly on mobile
- `Toast`: the notification strip and rows no longer swallow clicks on page content beside them; `pointer-events` is re-enabled only on the visible pill itself

</Update>

<Update label="0.2.5" description="2026-07-03">

**Changed**

- Hover styles apply on all devices again: removed the `@media (hover: hover)` guards around `&:hover` rules in `interactiveStyles`, `errorInteractiveStyles`, `Dropzone`, `AvatarDropzone`, `Tabs`, and `ThemeToggle`

</Update>

<Update label="0.2.4" description="2026-07-03">

**Added**

- `Tabs` / `TabContent`: new tabbed-panels component with tablist/tab/tabpanel ARIA semantics, roving-tabindex arrow-key navigation (ArrowLeft/ArrowRight cycle, Home/End jump), and optional controlled selection via `activeTab` + `onTabChange` (`defaultActiveTab` for uncontrolled use)
- `IconButton`: `$active` prop for a toggle-like "on" state (primary border, translucent primary background); reflected as `aria-pressed` when set

**Changed**

- `ThemeToggle`: swapped the scale hover/press effects for the shared `interactiveStyles` hover border + focus ring, and aligned the sun/moon icons exactly with the sliding knob

</Update>

<Update label="0.2.3" description="2026-07-03">

**Added**

- `Modal`: `style` passthrough on the overlay root, complementing `className` for app-level restyling

**Fixed**

- `Modal`: corrected the restyling guidance in the prop docs. `styled(Modal)` cannot forward the `$`-props API, since styled-components strips transient props before they reach the wrapped component; restyle by passing a `className` and targeting the class hooks instead

</Update>

<Update label="0.2.2" description="2026-07-03">

**Added**

- `Modal`: `$hideCloseButton` prop to omit the built-in close button
- `Modal`: `className` passthrough on the overlay root for app-level restyling; inner parts expose stable class hooks (`.modal-inner`, `.modal-close`, `.modal-title`, `.modal-content`)
- `Modal`: `role="dialog"`, `aria-modal="true"`, and `aria-label` (from `$title`) on the dialog surface

**Changed**

- **Breaking-ish:** `Modal` now unmounts its children once the exit animation finishes instead of keeping them mounted (hidden) while closed. Children such as forms reset their state between openings. The enter/exit motion is unchanged visually (fade + 40px rise) but is now driven by keyframes instead of transitions
- `useOnClickOutside` subscribes its document listener once per mount (latest-ref pattern) instead of re-subscribing whenever callers pass inline ref arrays or callbacks

**Fixed**

- `useOnClickOutside` ignores unattached (null) refs instead of suppressing the callback entirely when any ref in the array is not mounted

</Update>

<Update label="0.2.1" description="2026-07-03">

**Added**

- `removeNotification(id)` on the toast context, returned by `useToastNotifications` alongside `addNotification`; each toast in `notifications` now carries a unique `id`
- Toast stack is an `aria-live="polite"` region, so screen readers announce new toasts

**Changed**

- Toast internals reworked: state and variants are typed `$` props on a new `StyledNotificationItem` instead of className strings, each toast manages its own enter/exit lifecycle, and the space collapse animates the toast's real height via `grid-template-rows` instead of a `max-height` guess, so entering and exiting toasts glide instead of snapping
- Bottom-anchored toasts (`$bottom`) slide up from below instead of dropping down from above

**Fixed**

- Dismissed and auto-hidden toasts are removed from state and the DOM after their exit animation instead of accumulating invisibly forever

</Update>

<Update label="0.2.0" description="2026-07-03">

**Added**

- `ThemeToggle` component: a pill-shaped sun/moon switch for light and dark mode
- `ClientThemeProvider`: SSR-aware theme provider with flash-free dark mode. Renders the server-resolved theme on first paint, reconciles against the `theme` cookie and OS preference on mount, persists changes to cookie and localStorage (no API route needed), migrates legacy localStorage-only preferences, and keeps the html `dark` class and `theme-color` meta tag in sync. Supports `$initial`, `$themeColor`, and `$globalStyles` props
- `themeInitScript` and `createThemeInitScript(darkBackground)`: blocking head script that seeds the `theme` cookie and prevents the dark-mode flash in browsers without color-scheme client hints (Safari, Firefox). Exported from a server-safe module so it can be used in server components
- `resolveTheme(cookieValue, theme, themeDark)` helper for resolving the `theme` cookie to a theme object in server code
- `toggleTheme()` on `ThemeContext`, provided by both theme providers
- `interactiveStyles` and `errorInteractiveStyles` mixins: hover/focus/active border + focus ring treatment for interactive surfaces, in the primary color and the error red respectively

</Update>

<Update label="0.1.19" description="2026-07-02">

**Added**

- `IconButton` component for icon-only actions
- `Password` component with visibility toggle
- `Modal` component
- `Toast` component with theme-aware shadows
- `Accordion` component
- `Dropzone` and `AvatarDropzone` components for file uploads

</Update>

<Update label="0.1.18" description="2026-06-28">

**Added**

- Responsive `$alignItems`, `$alignContent`, and per-breakpoint `$direction` props on `Flex`, backed by new `generateAlignItemsStyles`, `generateAlignContentStyles`, and `generateDirectionStyles` mixins

</Update>

# 0.1.17 and earlier

Changes prior to 0.1.18 were not tracked in this changelog. See the [git history](https://github.com/cherry-design-system/styled-components/commits/main) for details.

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/CHANGELOG.md" icon="code" iconPosition="left">
  View on GitHub
</Button>

---

# Theme

> The Cherry theme object defines media queries, spacing, colors, font sizes, line heights, and shadows.

Source: https://cherry.al/code/theme

# Theme

The Cherry theme is a TypeScript object that defines various aspects of your project. Whether you're working on media queries, spacing sizes, colors, font sizes, or line heights, the Cherry theme has got you covered. Cherry also offers a Figma plugin to extract design tokens - check out the [Figma](/figma) documentation for details.

Wrap your entire application with `CherryThemeProvider` to ensure all components have access to the theme:

```tsx
import {
  CherryThemeProvider,
  theme,
  themeDark,
} from "cherry-styled-components";

export default function App({ Component, pageProps }) {
  return (
    <CherryThemeProvider theme={theme} themeDark={themeDark}>
      <Component {...pageProps} />
    </CherryThemeProvider>
  );
}
```

Cherry exports two ready-made theme objects to start from: `theme` (light) and `themeDark` (dark). `CherryThemeProvider` accepts an optional `themeDark` prop - dark mode switching only happens when you pass it. The provider also exports a `ThemeContext` that gives you `setTheme` and `toggleTheme` for switching themes programmatically. See the [Dark Mode](/code/dark-mode) documentation for details.

## Theme Object

The theme object is type safe and uses TypeScript. The `Theme` interface has eight keys: the seven sections below plus an `isDark` boolean that marks a theme as a dark variant:

<Accordion title="1. Breakpoints">

```tsx
export const breakpoints: Breakpoints = {
  xs: 0,
  sm: 576,
  md: 768,
  lg: 992,
  xl: 1200,
  xxl: 1440,
  xxxl: 1920,
};

export function mq(minWidth: keyof Breakpoints) {
  return `@media screen and (min-width: ${breakpoints[minWidth]}px)`;
}
```

The `mq()` helper turns a breakpoint key into a min-width media query. Use it inside your styled components to apply styles from that breakpoint upwards:

```tsx
import styled from "styled-components";
import { mq } from "cherry-styled-components";

const Wrapper = styled.div`
  padding: 20px;

  ${mq("lg")} {
    padding: 40px;
  }
`;
```

</Accordion>

<Accordion title="2. Spacing">

```tsx
export const spacing: Spacing = {
  maxWidth: { xs: "1280px", xxxl: "1440px" },
  padding: { xs: "20px", lg: "40px" },
  radius: { xs: "6px", lg: "12px", xl: "30px" },
  gridGap: { xs: "20px", lg: "40px" },
};
```

</Accordion>

<Accordion title="3. Colors">

```tsx
export const colors: Colors = {
  primaryLight: "#91aec4",
  primary: "#4d6f8b",
  primaryDark: "#194569",
  secondaryLight: "#a4b17b",
  secondary: "#5c6e46",
  secondaryDark: "#354c2b",
  tertiaryLight: "#ebccb9",
  tertiary: "#816b5a",
  tertiaryDark: "#675445",
  grayLight: "#e5e7eb",
  gray: "#9ca3af",
  grayDark: "#4b5563",
  success: "#84cc16",
  error: "#ef4444",
  warning: "#eab308",
  info: "#06b6d4",
  dark: "#000000",
  light: "#ffffff",
};
```

A dark counterpart, `colorsDark`, is also exported and used by `themeDark`. It flips `dark`/`light`, swaps the grays for dark-surface values, and brightens the primary palette:

```tsx
export const colorsDark: Colors = {
  primaryLight: "#79C5FF",
  primary: "#6198C6",
  primaryDark: "#339DF4",
  secondaryLight: "#a4b17b",
  secondary: "#5c6e46",
  secondaryDark: "#354c2b",
  tertiaryLight: "#ebccb9",
  tertiary: "#816b5a",
  tertiaryDark: "#675445",
  grayLight: "#1a1a1a",
  gray: "#454444",
  grayDark: "#808080",
  success: "#84cc16",
  error: "#ef4444",
  warning: "#eab308",
  info: "#06b6d4",
  dark: "#ffffff",
  light: "#000000",
};
```

</Accordion>

<Accordion title="4. Shadows">

```tsx
export const shadows: Shadows = {
  xs: "0px 4px 4px 0px rgba(18, 18, 18, 0.04), 0px 1px 3px 0px rgba(39, 41, 45, 0.02)",
  sm: "0px 4px 4px 0px rgba(18, 18, 18, 0.08), 0px 1px 3px 0px rgba(39, 41, 45, 0.04)",
  md: "0px 8px 8px 0px rgba(18, 18, 18, 0.16), 0px 2px 3px 0px rgba(39, 41, 45, 0.06)",
  lg: "0px 16px 24px 0px rgba(18, 18, 18, 0.20), 0px 2px 3px 0px rgba(39, 41, 45, 0.08)",
  xl: "0px 24px 32px 0px rgba(18, 18, 18, 0.24), 0px 2px 3px 0px rgba(39, 41, 45, 0.12)",
};
```

A dark counterpart, `shadowsDark`, is also exported and used by `themeDark`. It uses white shadows at the same offsets and opacities so elevation stays visible on dark surfaces:

```tsx
export const shadowsDark: Shadows = {
  xs: "0px 4px 4px 0px rgba(255, 255, 255, 0.04), 0px 1px 3px 0px rgba(255, 255, 255, 0.02)",
  sm: "0px 4px 4px 0px rgba(255, 255, 255, 0.08), 0px 1px 3px 0px rgba(255, 255, 255, 0.04)",
  md: "0px 8px 8px 0px rgba(255, 255, 255, 0.16), 0px 2px 3px 0px rgba(255, 255, 255, 0.06)",
  lg: "0px 16px 24px 0px rgba(255, 255, 255, 0.20), 0px 2px 3px 0px rgba(255, 255, 255, 0.08)",
  xl: "0px 24px 32px 0px rgba(255, 255, 255, 0.24), 0px 2px 3px 0px rgba(255, 255, 255, 0.12)",
};
```

</Accordion>

<Accordion title="5. Fonts">

```tsx
export const fonts: Fonts = {
  text: "Inter",
  head: "Inter",
  mono: "monospace",
};
```

</Accordion>

<Accordion title="6. Font Sizes">

```tsx
export const fontSizes: FontSizes = {
  hero1: { xs: "72px", lg: "128px" },
  hero2: { xs: "60px", lg: "96px" },
  hero3: { xs: "36px", lg: "72px" },
  h1: { xs: "40px", lg: "60px" },
  h2: { xs: "30px", lg: "36px" },
  h3: { xs: "28px", lg: "30px" },
  h4: { xs: "26px", lg: "24px" },
  h5: { xs: "18px", lg: "20px" },
  h6: { xs: "16px", lg: "18px" },
  text: { xs: "14px", lg: "16px" },
  strong: { xs: "14px", lg: "16px" },
  small: { xs: "12px", lg: "14px" },
  blockquote: { xs: "16px", lg: "18px" },
  code: { xs: "14px", lg: "16px" },
  button: { xs: "16px", lg: "16px" },
  buttonBig: { xs: "18px", lg: "18px" },
  buttonSmall: { xs: "14px", lg: "14px" },
  input: { xs: "16px", lg: "16px" },
  inputBig: { xs: "18px", lg: "18px" },
  inputSmall: { xs: "14px", lg: "14px" },
};
```

</Accordion>

<Accordion title="7. Line Heights">

```tsx
export const lineHeights: LineHeights = {
  hero1: { xs: "1.10", lg: "1.10" },
  hero2: { xs: "1.10", lg: "1.10" },
  hero3: { xs: "1.20", lg: "1.10" },
  h1: { xs: "1.50", lg: "1.40" },
  h2: { xs: "1.50", lg: "1.50" },
  h3: { xs: "1.30", lg: "1.50" },
  h4: { xs: "1.30", lg: "1.50" },
  h5: { xs: "1.60", lg: "1.50" },
  h6: { xs: "1.60", lg: "1.60" },
  text: { xs: "1.70", lg: "1.70" },
  strong: { xs: "1.70", lg: "1.70" },
  small: { xs: "1.70", lg: "1.70" },
  blockquote: { xs: "1.70", lg: "1.70" },
  code: { xs: "1.70", lg: "1.70" },
  button: { xs: "1.00", lg: "1.00" },
  buttonBig: { xs: "1.00", lg: "1.00" },
  buttonSmall: { xs: "1.00", lg: "1.00" },
  input: { xs: "1.00", lg: "1.00" },
  inputBig: { xs: "1.00", lg: "1.00" },
  inputSmall: { xs: "1.00", lg: "1.00" },
};
```

</Accordion>

These sections, together with the `isDark` flag, make up the exported `theme` and `themeDark` objects:

```tsx
export const theme: Theme = {
  breakpoints,
  spacing,
  colors,
  shadows,
  fonts,
  fontSizes,
  lineHeights,
  isDark: false,
};

export const themeDark: Theme = {
  breakpoints,
  spacing,
  colors: colorsDark,
  shadows: shadowsDark,
  fonts,
  fontSizes,
  lineHeights,
  isDark: true,
};
```

## Using Shadows

Every theme ships five shadow levels (`xs`, `sm`, `md`, `lg`, `xl`) under `theme.shadows`. Reference them in your styled components to add elevation. When you pass `themeDark` to `CherryThemeProvider`, the dark theme swaps in `shadowsDark`, so elevation adapts to light and dark mode automatically:

```tsx
import styled from "styled-components";

const Card = styled.div`
  background: ${({ theme }) => theme.colors.light};
  border-radius: ${({ theme }) => theme.spacing.radius.lg};
  box-shadow: ${({ theme }) => theme.shadows.md};
`;
```

<iframe className="light-only" src="https://demo.cherry.al/preview/shadows?theme=light" title="Shadow elevations" loading="lazy" style={{ width: "100%", height: "500px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/shadows?theme=dark" title="Shadow elevations" loading="lazy" style={{ width: "100%", height: "500px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

See the [Shadows](/shadows) foundation page for the full list of values.

## Extending the Theme

When extending the Cherry theme, adhere to established patterns. Cherry uses the following size patterns: `xs`, `sm`, `md`, `lg`, `xl`, `xxl`, and `xxxl`. These patterns define not only media queries but also various other sizes.

If you extend the theme, ensure that you add the necessary type definitions to maintain consistency. All theme section interfaces (`Theme`, `Breakpoints`, `Spacing`, `Colors`, `Shadows`, `Fonts`, `FontSizes`, `LineHeights`) are exported, so you can extend them in TypeScript.

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/utils/theme.ts" icon="code" iconPosition="left">
  View Source
</Button>

---

# Dark Mode

> Enable dark mode in Cherry with automatic detection, manual toggle support, and flash-free server-side rendering.

Source: https://cherry.al/code/dark-mode

# Dark Mode

Cherry provides built-in support for dark mode. Pass the `themeDark` prop to the `CherryThemeProvider` component:

```tsx
import {
  CherryThemeProvider,
  theme,
  themeDark,
} from "cherry-styled-components";

export default function App({ children }) {
  return (
    <CherryThemeProvider theme={theme} themeDark={themeDark}>
      {children}
    </CherryThemeProvider>
  );
}
```

## Automatic Detection

Cherry will automatically check whether your system has dark mode enabled. If detected, the default theme will be set to dark. This only happens if you passed the `themeDark` prop to `CherryThemeProvider`.

## Manual Theme Toggle

The easiest way to let users switch themes is the built-in [ThemeToggle](/code/theme-toggle) component. It calls `toggleTheme()` from `ThemeContext` and persists the choice automatically:

```tsx
import { ThemeToggle } from "cherry-styled-components";

export default function Header() {
  return (
    <header>
      <ThemeToggle />
    </header>
  );
}
```

For a custom control, call `toggleTheme` from `ThemeContext` yourself. It persists the choice to `localStorage` and keeps the html `dark` class in sync. Under `CherryThemeProvider`, `setTheme` is the raw state setter and does neither, so the choice is lost on reload; under `ClientThemeProvider` (covered below), `setTheme` also persists:

```tsx
import { ThemeContext } from "cherry-styled-components";
import { useContext } from "react";

export default function Header() {
  const { toggleTheme } = useContext(ThemeContext);
  return (
    <header>
      <button onClick={toggleTheme}>Switch Theme</button>
    </header>
  );
}
```

## Flash-Free Dark Mode with SSR

`CherryThemeProvider` resolves the theme on the client after mount, so in a server-rendered app the first paint is always the light theme, which dark mode users see as a flash. For server-rendered apps (e.g. Next.js App Router), use `ClientThemeProvider` instead:

1. The server reads the `theme` cookie and passes the verdict as `$initial`, so the first paint is already correct.
2. `themeInitScript`, a blocking script in the document head, seeds the cookie from the OS preference on first visits from browsers without color-scheme client hints (Safari, Firefox) and hides the body until the client has applied the right theme.
3. On mount, the provider reconciles the server's guess against the cookie and OS preference and swaps the theme in place if needed.

Theme changes persist to the `theme` cookie and `localStorage` directly. No API route is needed. The layout below also wraps the app in `StyledComponentsRegistry`, the SSR style registry introduced in [Installation](/code/installation):

<Code title="app/layout.tsx" language="tsx" code={`// Server component
  import { cookies } from "next/headers";
  import {
    ClientThemeProvider,
    StyledComponentsRegistry,
    themeInitScript,
  } from "cherry-styled-components";
  import { theme, themeDark } from "./theme";

  export default async function RootLayout({ children }) {
    const cookieTheme = (await cookies()).get("theme")?.value;

    return (
      <html lang="en">
        <head>
          <script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
        </head>
        <body>
          <StyledComponentsRegistry>
            <ClientThemeProvider
              theme={theme}
              themeDark={themeDark}
              $initial={cookieTheme === "dark" ? "dark" : "light"}
            >
              {children}
            </ClientThemeProvider>
          </StyledComponentsRegistry>
        </body>
      </html>
    );
  }`} />

`themeInitScript` hides the body behind a black (`#000`) background while it waits. If your dark theme uses a different page background, build the script with `createThemeInitScript` instead, so the brief pre-hydration frame matches it:

```tsx
import { createThemeInitScript } from "cherry-styled-components";

const themeInitScript = createThemeInitScript("#0a0a0f");
```

For the best first visit in Chrome, opt into color-scheme client hints in your middleware so even the very first server render matches the OS preference:

<Code title="middleware.ts" language="ts" code={`res.headers.set("Accept-CH", "Sec-CH-Prefers-Color-Scheme");
res.headers.set("Vary", "Sec-CH-Prefers-Color-Scheme");
res.headers.set("Critical-CH", "Sec-CH-Prefers-Color-Scheme");

const hint = req.headers.get("Sec-CH-Prefers-Color-Scheme");
if (!req.cookies.get("theme")?.value && hint) {
  res.cookies.set("theme", hint === "dark" ? "dark" : "light", {
    path: "/",
    maxAge: 60 * 60 * 24 * 365,
    sameSite: "lax",
  });
}`} />

Server code that needs the active theme object (for example `generateViewport` for the initial `theme-color`) can use the `resolveTheme` helper:

```ts
import { resolveTheme } from "cherry-styled-components";
import { theme, themeDark } from "./theme";

const active = resolveTheme(cookieTheme, theme, themeDark);
```

`ClientThemeProvider` also keeps a `theme-color` meta tag in sync with the active theme so browser chrome (like the iOS Safari status bar) matches the page. Point `$themeColor` at the theme color your page background uses (default `"light"`), or pass `false` to disable:

```html
<ClientThemeProvider
  theme={theme}
  themeDark={themeDark}
  $themeColor="tertiaryLight"
>
```

If your app ships its own global styles, pass `$globalStyles={false}` and render them as a child so Cherry's defaults don't compete with yours.

In a client-only app there is no server render to flash, so either provider works. To use `ClientThemeProvider`, resolve the initial theme synchronously (cookie, then `localStorage`, then `matchMedia`) before rendering and pass it as `$initial`.

<Callout type="note">
  Both providers expose `setTheme` and `toggleTheme` through the same
  `ThemeContext`, and both work with the `ThemeToggle` component. Existing apps
  using `CherryThemeProvider` keep working unchanged.
</Callout>

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/styled-components/client-theme-provider.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Global Styles

> Cherry's global CSS reset and base styles for consistent rendering across browsers.

Source: https://cherry.al/code/global-styles

# Global Styles

Global styles consist of a basic set of CSS rules designed to reset certain browser behaviors. Both `CherryThemeProvider` and `ClientThemeProvider` inject the Cherry global styles automatically. If your app ships its own global styles, pass `$globalStyles={false}` to `ClientThemeProvider` and render yours as a child instead. Outside the providers, include them manually:

```tsx
import { GlobalStyles } from "cherry-styled-components";
```

`GlobalStyles` is a function that takes a `Theme` and returns a global-style component built with `createGlobalStyle`. Call it with your theme and render the result, as in this minimal wrapper. Unlike the real `CherryThemeProvider`, it skips the dark theme handling and toggle context:

```tsx
"use client";
import React from "react";
import { ThemeProvider as StyledThemeProvider } from "styled-components";
import { GlobalStyles, Theme } from "cherry-styled-components";

function ManualThemeProvider({
  children,
  theme,
}: {
  children: React.ReactNode;
  theme: Theme;
}) {
  const GlobalStylesComponent = GlobalStyles(theme);

  return (
    <StyledThemeProvider theme={theme}>
      <GlobalStylesComponent />
      {children}
    </StyledThemeProvider>
  );
}

export { ManualThemeProvider };
```

## The Actual Global Styles

Adjust the global styles according to your project's requirements:

<Code title="src/lib/utils/global.tsx" language="tsx" code={`"use client";
  import { createGlobalStyle } from "styled-components";
  import { Theme } from "./theme";

  const GlobalStyles = (theme: Theme) => createGlobalStyle\`
  html,
  body {
    margin: 0;
    padding: 0;
    min-height: 100%;
    scroll-behavior: smooth;
    background-color: \${theme.colors.light};
  }

  body {
    font-family: "Inter", sans-serif;
    -moz-osx-font-smoothing: grayscale;
    -webkit-text-size-adjust: 100%;
    -webkit-font-smoothing: antialiased;
  }

  * {
    box-sizing: border-box;
    min-width: 0;
  }

  pre,
  code,
  kbd,
  samp {
    font-family: monospace, monospace;
  }

  pre,
  code,
  kbd,
  samp,
  blockquote,
  p,
  a,
  h1,
  h2,
  h3,
  h4,
  h5,
  h6,
  ul li,
  ol li {
    margin: 0;
    padding: 0;
    color: \${theme.colors.dark};
  }

  a {
    color: \${theme.isDark ? theme.colors.dark : theme.colors.primary};
  }

  ol,
  ul {
    list-style: none;
    margin: 0;
    padding: 0;
  }

  figure {
    margin: 0;
  }

  fieldset {
    appearance: none;
    border: none;
  }

  button,
  input,
  a,
  img,
  svg,
  svg * {
    transition: all 0.3s ease;
  }

  strong,
  b {
    font-weight: 700;
  }

  hr {
    margin: 20px 0;
    border: none;
    border-bottom: 1px solid \${theme.colors.grayLight};
  }
  \`;

  export { GlobalStyles };`} />

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/utils/global.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Button

> Cherry Button component - primary, secondary, and tertiary variants, sizes, and outline mode.

Source: https://cherry.al/code/button

# Button

<iframe className="light-only" src="https://demo.cherry.al/preview/button?theme=light" title="Button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/button?theme=dark" title="Button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

Buttons are essential components in web development, frequently used for user interactions.

Keep in mind that the `<button>` element inherently includes native browser properties like `onClick`. Cherry UI components introduce custom properties that always begin with a `$` to distinguish them from native props.

For design guidelines and all interactive states, see the [Buttons](/buttons) design page.

The examples below assume the Cherry theme provider from [Installation](/code/installation) is already set up.

```jsx
import React from "react";
import { Button } from "cherry-styled-components";

export default function Page() {
  return <Button>Button</Button>;
}
```

You can change the look of your button by adding a `$variant` prop:

```html
<Button $variant="secondary">Button</Button>
```

You can try more variations and props like `$outline`:

```html
<Button $variant="tertiary" $outline>
  Button
</Button>
```

## Properties

<Field value="children" type="React.ReactNode">
  Button content.
</Field>

<Field value="$variant" type='"primary" | "secondary" | "tertiary"'>
  Color variant of the button. Defaults to `"primary"`.
</Field>

<Field value="$size" type='"default" | "big" | "small"'>
  Size of the button.
</Field>

<Field value="$outline" type="boolean">
  Renders the button with an outline style.
</Field>

<Field value="$error" type="boolean">
  Renders the button in the theme's error color.
</Field>

<Field value="$fullWidth" type="boolean">
  Makes the button span the full width of its container.
</Field>

<Field value="$icon" type="React.ReactNode">
  Icon element rendered inside the button.
</Field>

<Field value="$iconPosition" type='"left" | "right"'>
  Position of the icon relative to the label. Defaults to `"left"`.
</Field>

<Field value="disabled" type="boolean">
  Native attribute. While disabled the button turns gray (`grayLight` background and border, `gray` text), shows `cursor: not-allowed`, and all `$variant` and `$error` styles are suppressed.
</Field>

Button forwards its ref to the underlying `HTMLButtonElement`, and any remaining native `<button>` attributes pass through. The props above are typed by the exported `ButtonProps` interface.

## buttonStyles

Button's CSS is also exported as the `buttonStyles(theme, $variant, $size, $outline, $fullWidth, $error, disabled)` helper, so you can style other elements to look like a Button, like a styled link:

```tsx
import styled from "styled-components";
import { buttonStyles } from "cherry-styled-components";

const ButtonLink = styled.a`
  ${({ theme }) => buttonStyles(theme, "primary")}
`;
```

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/button.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# IconButton

> Cherry IconButton component - a circular icon-only button with three sizes, an error variant, and an active toggle state.

Source: https://cherry.al/code/icon-button

# IconButton

<iframe className="light-only" src="https://demo.cherry.al/preview/icon-button?theme=light" title="Icon button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/icon-button?theme=dark" title="Icon button" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

The IconButton component is a circular, icon-only button for compact actions like edit, delete, or settings.

Keep in mind that the `<button>` element inherently includes native browser properties like `onClick`. Cherry UI components introduce custom properties that always begin with a `$` to distinguish them from native props.

Because the button has no visible text, the `aria-label` property is required.

For design guidelines and all interactive states, see the [Buttons](/buttons) design page.

```jsx
import React from "react";
import { Icon, IconButton } from "cherry-styled-components";

export default function Page() {
  return (
    <IconButton aria-label="Settings">
      <Icon name="Settings" />
    </IconButton>
  );
}
```

With sizes:

```html
<IconButton $size="small" aria-label="Edit">
  <Icon name="Pencil" />
</IconButton>
<IconButton $size="big" aria-label="Add">
  <Icon name="Plus" />
</IconButton>
```

For destructive actions, use the error variant:

```html
<IconButton $error aria-label="Delete">
  <Icon name="Trash2" />
</IconButton>
```

For toggle-like actions that stay "on" (a dropzone that is open, a preview
that is active), use `$active`. The button keeps its primary border with a
subtle tint, and the state is exposed to assistive technology via
`aria-pressed` automatically:

```html
<IconButton $active={isPreviewOpen} aria-label="Toggle preview">
  <Icon name="Eye" />
</IconButton>
```

## Properties

<Field value="children" type="React.ReactNode">
  The icon to render, typically a Cherry `Icon`. It is sized automatically per
  `$size` (12px, 14px, or 16px).
</Field>

<Field value="aria-label" type="string" required>
  Accessible label describing the action. Required because the button has no
  visible text.
</Field>

<Field value="type" type='"button" | "submit" | "reset"'>
  Defaults to `"button"` (instead of the native `"submit"`) so the button does
  not accidentally submit a surrounding form. Pass `type="submit"` to override.
</Field>

<Field value="$size" type='"default" | "big" | "small"'>
  Size of the button: 24px (small), 28px (default), or 32px (big).
</Field>

<Field value="$error" type="boolean">
  Renders the button in the theme's error color for destructive actions.
</Field>

<Field value="$active" type="boolean">
  Marks the button as being in an "on" state: primary border, tinted
  background, and primary icon color. When set (true or false), the value is
  also reflected as `aria-pressed` so screen readers announce the toggle
  state. The active styling is ignored while `disabled`, but `aria-pressed`
  is still emitted.
</Field>

## iconButtonStyles

The css helper behind the component is also exported as
`iconButtonStyles(theme, $size, $error, disabled, $active)`. Use it to apply
the exact IconButton look to a custom styled component:

```tsx
import styled from "styled-components";
import { iconButtonStyles } from "cherry-styled-components";

const RoundLink = styled.a`
  ${({ theme }) => iconButtonStyles(theme, "big")};
`;
```

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/icon-button.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Input

> Cherry Input component - text fields, checkboxes, and radio buttons with validation states.

Source: https://cherry.al/code/input

# Input

<iframe className="light-only" src="https://demo.cherry.al/preview/input?theme=light" title="Input" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/input?theme=dark" title="Input" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

The Input component encompasses various text input types, including radio buttons and checkboxes. Inputs can have error or success states to provide feedback to the user. Disabled inputs also get dedicated styling with a `not-allowed` cursor and grayed-out colors, and a disabled checkbox renders a dot instead of the check icon when checked.

Keep in mind that the `<input>` element inherently includes native browser properties like `onChange`. Cherry UI components introduce custom properties that always begin with a `$` to distinguish them from native props.

For design guidelines and all interactive states, see the [Inputs](/inputs) design page.

```jsx
import React from "react";
import { Input } from "cherry-styled-components";

export default function Page() {
  return <Input type="text" placeholder="Placeholder" />;
}
```

You can add a label with the `$label` prop:

```html
<Input type="text" $label="Username" $fullWidth />
```

Checkbox and radio examples:

```html
<Input type="checkbox" defaultChecked />
<Input type="radio" />
```

## Properties

<Field value="type" type="string">
  The type of input element. Accepts any native input type, such as `"text"`, `"email"`, `"checkbox"`, or `"radio"`. Date and time types (`"date"`, `"datetime-local"`, `"month"`, `"week"`, `"time"`) automatically render a calendar icon inside the field.
</Field>

<Field value="$label" type="string">
  Label text. For text-like types the label sits inline before the input and stacks above it when the wrapper wraps, for example with `$fullWidth`; rendered after the control for `checkbox` and `radio`.
</Field>

<Field value="$wrapperClassName" type="string">
  Class name applied to the wrapper element around the input, for restyling from the outside.
</Field>

<Field value="$size" type='"default" | "big" | "small"'>
  Size of the input.
</Field>

<Field value="$error" type="boolean">
  Shows error state styling. Also sets `aria-invalid` on the input element automatically.
</Field>

<Field value="$success" type="boolean">
  Shows success state styling.
</Field>

<Field value="$fullWidth" type="boolean">
  Makes the input span the full width of its container.
</Field>

<Field value="$icon" type="React.ReactNode">
  Icon element rendered inside the input.
</Field>

<Field value="$iconPosition" type='"left" | "right"'>
  Position of the icon relative to the input.
</Field>

## Building blocks

Besides the `Input` component itself, the module exports a few pieces for composing custom fields:

- `InputProps` is the TypeScript interface for all Input props, extending the native `<input>` attributes.
- `StyledInputWrapper` is the flex wrapper element rendered around the label and input.
- `StyledLabel` is the styled `<label>` element used to render the `$label` text.

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/input.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Textarea

> Cherry Textarea component - multiline text input with validation states.

Source: https://cherry.al/code/textarea

# Textarea

<iframe className="light-only" src="https://demo.cherry.al/preview/textarea?theme=light" title="Textarea" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/textarea?theme=dark" title="Textarea" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

Textarea allows for multiple lines of text and shares most of the [Input](/code/input) component's properties: `$label`, `$size`, `$error`, `$success`, `$fullWidth`, and `$wrapperClassName`. Unlike Input, it does not support `$icon` or `$iconPosition`. Textareas can have error or success states to provide feedback to the user.

Keep in mind that the `<textarea>` element inherently includes native browser properties like `onChange`. Cherry UI components introduce custom properties that always begin with a `$` to distinguish them from native props. To pre-fill the content, use the native `value` or `defaultValue` attributes rather than passing children.

For design guidelines and all interactive states, see the [Inputs](/inputs) design page.

```jsx
import React from "react";
import { Textarea } from "cherry-styled-components";

export default function Page() {
  return <Textarea placeholder="Placeholder" />;
}
```

With a label:

```html
<Textarea $label="Username" $fullWidth />
```

With success and error states:

```html
<Textarea $success placeholder="Yay" />
<Textarea $error placeholder="Ops" />
```

## Properties

<Field value="$label" type="string">
  Label text displayed above the textarea.
</Field>

<Field value="$size" type='"default" | "big" | "small"'>
  Size of the textarea.
</Field>

<Field value="$error" type="boolean">
  Shows error state styling.
</Field>

<Field value="$success" type="boolean">
  Shows success state styling.
</Field>

<Field value="$fullWidth" type="boolean">
  Makes the textarea span the full width of its container.
</Field>

<Field value="rows" type="number">
  Number of visible text rows.
</Field>

<Field value="$wrapperClassName" type="string">
  Class name applied to the wrapper element around the textarea, for restyling from the outside.
</Field>

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/textarea.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Select

> Cherry Select component - dropdown menus with validation states.

Source: https://cherry.al/code/select

# Select

<iframe className="light-only" src="https://demo.cherry.al/preview/select?theme=light" title="Select" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/select?theme=dark" title="Select" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

Select shares the same properties as the Input component of type text, but allows for selecting from a list instead of typing. Select can have error or success states to provide feedback to the user.

Keep in mind that the `<select>` element inherently includes native browser properties like `onChange`. Cherry UI components introduce custom properties that always begin with a `$` to distinguish them from native props.

For design guidelines and all interactive states, see the [Inputs](/inputs) design page.

```jsx
import React from "react";
import { Select } from "cherry-styled-components";

export default function Page() {
  return (
    <Select>
      <option value="1">Option 1</option>
      <option value="2">Option 2</option>
      <option value="3">Option 3</option>
    </Select>
  );
}
```

With a label:

```html
<Select $label="Label" $fullWidth>
  <option value="1">Option 1</option>
  <option value="2">Option 2</option>
  <option value="3">Option 3</option>
</Select>
```

With success and error states:

```html
<Select $success>
  <option value="1">Yay</option>
</Select>
<Select $error>
  <option value="1">Ops</option>
</Select>
```

## Properties

<Field value="$label" type="string">
  Label text displayed above the select.
</Field>

<Field value="$size" type='"default" | "big" | "small"'>
  Size of the select.
</Field>

<Field value="$error" type="boolean">
  Shows error state styling.
</Field>

<Field value="$success" type="boolean">
  Shows success state styling.
</Field>

<Field value="$fullWidth" type="boolean">
  Makes the select span the full width of its container.
</Field>

<Field value="$wrapperClassName" type="string">
  Class name applied to the wrapper element around the select, for restyling from the outside.
</Field>

## Building blocks

The `StyledIconWrapper` styled component that positions the dropdown arrow is also exported, so you can reuse it when building custom selects.

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/select.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Password

> Cherry Password component - a password input with a built-in show/hide reveal toggle.

Source: https://cherry.al/code/password

# Password

<iframe className="light-only" src="https://demo.cherry.al/preview/password?theme=light" title="Password" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/password?theme=dark" title="Password" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

The Password component wraps the Cherry Input with `type="password"` and adds a show/hide reveal toggle pinned inside the field.

It accepts every Input property except `type`, `$icon`, and `$iconPosition`: `type` is owned by the component to flip between masked and plain text, and the icon slot is reserved for the reveal button. Small fields automatically get a matching small reveal button.

Keep in mind that the `<input>` element inherently includes native browser properties like `onChange`. Cherry UI components introduce custom properties that always begin with a `$` to distinguish them from native props.

For design guidelines and all interactive states, see the [Inputs](/inputs) design page.

```jsx
import React from "react";
import { Password } from "cherry-styled-components";

export default function Page() {
  return <Password $label="Password" $fullWidth id="password" />;
}
```

With sizes and validation states:

```html
<Password $size="big" $fullWidth />
<Password $error $fullWidth />
```

## Properties

<Field value="$label" type="string">
  Label text displayed above the input.
</Field>

<Field value="$size" type='"default" | "big" | "small"'>
  Size of the input. The `small` size also shrinks the reveal button.
</Field>

<Field value="$error" type="boolean">
  Shows error state styling on the field and the reveal button.
</Field>

<Field value="$success" type="boolean">
  Shows success state styling.
</Field>

<Field value="$fullWidth" type="boolean">
  Makes the input span the full width of its container.
</Field>

<Field value="$wrapperClassName" type="string">
  Class name applied to the wrapper element around the input, for restyling from the outside.
</Field>

<Callout type="note">
  The reveal toggle manages `aria-pressed` and swaps its accessible label
  between "Show password" and "Hide password" automatically.
</Callout>

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/password.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Toggle

> Cherry Toggle component - a stylish checkbox/radio alternative with validation states.

Source: https://cherry.al/code/toggle

# Toggle

<iframe className="light-only" src="https://demo.cherry.al/preview/toggle?theme=light" title="Toggle" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/toggle?theme=dark" title="Toggle" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

The Toggle component is a stylish input checkbox or radio element.

Keep in mind that the `<input>` element inherently includes native browser properties like `onChange`. Cherry UI components introduce custom properties that always begin with a `$` to distinguish them from native props.

For design guidelines and all interactive states, see the [Inputs](/inputs) design page.

```jsx
import React from "react";
import { Toggle } from "cherry-styled-components";

export default function Page() {
  return <Toggle defaultChecked />;
}
```

With a label. Pass an `id` so the label is associated with the input; without it, clicking the label won't toggle the switch:

```html
<Toggle id="newsletter" $label="Label" $fullWidth />
```

With success and error states:

```html
<Toggle $success />
<Toggle $error />
```

Disabled toggles get built-in styling with a `not-allowed` cursor and gray colors:

```html
<Toggle disabled />
```

The underlying input always renders with `role="switch"`, so assistive technologies announce it as a switch.

## Properties

<Field value="type" type='"checkbox" | "radio"'>
  The underlying input type. Defaults to `"checkbox"`.
</Field>

<Field value="$label" type="string">
  Label text displayed alongside the toggle. Requires an `id` on the toggle so the label's `htmlFor` points to the input; otherwise label clicks won't toggle it.
</Field>

<Field value="$size" type='"default" | "big" | "small"'>
  Size of the toggle.
</Field>

<Field value="$error" type="boolean">
  Shows error state styling.
</Field>

<Field value="$success" type="boolean">
  Shows success state styling.
</Field>

<Field value="$fullWidth" type="boolean">
  Makes the toggle span the full width of its container.
</Field>

<Field value="$wrapperClassName" type="string">
  Class name applied to the wrapper element around the toggle, for restyling from the outside.
</Field>

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/toggle.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Range

> Cherry Range component - validation states and label support.

Source: https://cherry.al/code/range

# Range

<iframe className="light-only" src="https://demo.cherry.al/preview/range?theme=light" title="Range" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/range?theme=dark" title="Range" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

Range inputs allow users to select a value from a range. Range accepts the `$label`, `$size`, `$error`, `$success`, `$fullWidth`, and `$wrapperClassName` properties also found on the Input component, but not `$icon` or `$iconPosition`, and the native `size` attribute is omitted. Range can have error or success states to provide feedback to the user.

Keep in mind that the `<input>` element inherently includes native browser properties like `min`, `max`, `step`, and `onChange`. Cherry UI components introduce custom properties that always begin with a `$` to distinguish them from native props. Range also forwards its `ref` to the underlying `<input type="range">` element.

For design guidelines and all interactive states, see the [Inputs](/inputs) design page.

```jsx
import React from "react";
import { Range } from "cherry-styled-components";

export default function Page() {
  return <Range />;
}
```

With a label:

```html
<Range id="volume" $label="Label" $fullWidth />
```

The label is only associated with the input when an `id` is passed, so include one whenever you use `$label`.

With native `min`, `max`, and `step` attributes and a controlled value:

```jsx
const [value, setValue] = React.useState(50);

<Range
  min={0}
  max={100}
  step={5}
  value={value}
  onChange={(e) => setValue(Number(e.target.value))}
/>;
```

With different sizes:

```html
<Range $size="small" />
<Range $size="big" />
```

With success and error states:

```html
<Range $success />
<Range $error />
```

Disabled ranges get dedicated styling with a gray track and thumb and a `not-allowed` cursor:

```html
<Range disabled />
```

## Properties

<Field value="$label" type="string">
  Label text displayed above the range. Pass an `id` on the Range so the label
  is associated with the input.
</Field>

<Field value="$size" type='"default" | "big" | "small"'>
  Size of the range slider.
</Field>

<Field value="$error" type="boolean">
  Shows error state styling and sets `aria-invalid` on the input.
</Field>

<Field value="$success" type="boolean">
  Shows success state styling.
</Field>

<Field value="$fullWidth" type="boolean">
  Makes the range span the full width of its container.
</Field>

<Field value="$wrapperClassName" type="string">
  Class name applied to the wrapper element around the range slider, for restyling from the outside.
</Field>

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/range.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Dropzone

> Cherry Dropzone component - a file input drop target with drag & drop, validation, and preview thumbnails.

Source: https://cherry.al/code/dropzone

# Dropzone

<iframe className="light-only" src="https://demo.cherry.al/preview/dropzone?theme=light" title="Dropzone" loading="lazy" style={{ width: "100%", height: "400px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/dropzone?theme=dark" title="Dropzone" loading="lazy" style={{ width: "100%", height: "400px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

<iframe className="light-only" src="https://demo.cherry.al/preview/dropzone-inline?theme=light" title="Inline dropzone" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/dropzone-inline?theme=dark" title="Inline dropzone" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

The Dropzone component is a file input rendered as a dashed drop target. It supports click-to-browse and drag & drop, validates files against `accept`, `$maxFiles`, and `$maxBytes`, and shows preview thumbnails with remove buttons for the selected files.

The upload itself stays in your hands: the component only manages the file list and hands you `File` objects.

For design guidelines and all interactive states, see the [Inputs](/inputs) design page.

```jsx
import React from "react";
import { Dropzone } from "cherry-styled-components";

export default function Page() {
  return (
    <Dropzone
      accept="image/png,image/jpeg,image/webp"
      multiple
      $maxFiles={5}
      $maxBytes={5 * 1024 * 1024}
      $prompt="Drag images here"
      $browse="or click to browse"
      $hint="PNG, JPG or WebP · up to 5MB · max 5 files"
      $icon="ImageUp"
      onFilesChange={(files) => console.log(files)}
      onFilesRejected={(rejections) => console.warn(rejections)}
    />
  );
}
```

The inline variant is a compact horizontal row with a transparent background for embedding inside forms or modals. Without `multiple`, selecting a new file replaces the current one:

```html
<Dropzone $inline accept="image/*" $prompt="Drag an image here" />
```

## Properties

<Field value="$prompt" type="string">
  Bold primary prompt line. Defaults to `"Drag & drop files here"`.
</Field>

<Field value="$browse" type="string">
  Optional "or click to browse" sub-line beneath the prompt.
</Field>

<Field value="$hint" type="string">
  Optional smaller hint line for accepted types and limits.
</Field>

<Field value="$icon" type="IconProps">
  Name of the Lucide icon shown in the rounded tile. `IconProps` is a string union of all Lucide icon names, not an object. Defaults to `"FileUp"`.
</Field>

<Field value="$inline" type="boolean">
  Compact horizontal variant with a transparent background.
</Field>

<Field value="$maxFiles" type="number">
  Maximum number of files kept at once (with `multiple`).
</Field>

<Field value="$maxBytes" type="number">
  Maximum size per file in bytes.
</Field>

<Field value="onFilesChange" type="(files: File[]) => void">
  Called with the full current file list whenever it changes.
</Field>

<Field value="onFilesRejected" type="(rejections: DropzoneRejection[]) => void">
  Called with the rejected files and a typed reason (`"type"`, `"size"`, or
  `"count"`) so you can surface errors however you like, for example with a
  Toast.
</Field>

<Field value="accept" type="string">
  Native accept filter. Also enforced for dropped files, including `.ext` and
  `type/*` patterns.
</Field>

<Field value="multiple" type="boolean">
  Allows selecting several files. Without it, a new file replaces the current
  one.
</Field>

<Field value="disabled" type="boolean">
  Disables the whole control: click-to-browse, drag & drop, and the thumbnail
  remove buttons stop working, and the drop target gets disabled styling. The
  drop target also disables itself once the file limit is reached.
</Field>

All other native input attributes (`name`, `id`, `form`, `required`, and so
on) are passed through to the hidden `<input type="file" />`, and a `ref` is
forwarded to that same input.

## matchesAccept

The `matchesAccept(file, accept?)` helper the component uses to validate
dropped files is also exported. It checks a `File` against a comma-separated
`accept` string, supporting `.ext` suffixes, `type/*` wildcards, and exact MIME
types, and returns `true` when no `accept` string is given:

```jsx
import { matchesAccept } from "cherry-styled-components";

matchesAccept(file, ".pdf,image/*"); // true for report.pdf or photo.png
```

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/dropzone.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# AvatarDropzone

> Cherry AvatarDropzone component - a circular single-file dropzone for profile pictures in three sizes.

Source: https://cherry.al/code/avatar-dropzone

# AvatarDropzone

<iframe className="light-only" src="https://demo.cherry.al/preview/avatar-dropzone?theme=light" title="Avatar dropzone" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/avatar-dropzone?theme=dark" title="Avatar dropzone" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

The AvatarDropzone component is a circular, single-file dropzone for profile pictures. While empty it shows a dashed circle with an icon; a selected image fills the circle and can be removed with the corner button. Selecting a new file replaces the current one.

For design guidelines and all interactive states, see the [Inputs](/inputs) design page.

```jsx
import React from "react";
import { AvatarDropzone } from "cherry-styled-components";

export default function Page() {
  return (
    <AvatarDropzone
      $maxBytes={5 * 1024 * 1024}
      onFileChange={(file) => console.log(file)}
      onFileRejected={({ file, reason }) => console.warn(file.name, reason)}
    />
  );
}
```

With sizes:

```html
<AvatarDropzone $size="small" />
<AvatarDropzone $size="big" />
```

## Properties

<Field value="$size" type='"default" | "big" | "small"'>
  Size of the circle: 64px (small), 96px (default), or 128px (big).
</Field>

<Field value="$icon" type="IconProps">
  Name of the Lucide icon shown while empty. `IconProps` is a string union of all Lucide icon names, not an object. Defaults to `"User"`.
</Field>

<Field value="$maxBytes" type="number">
  Maximum file size in bytes.
</Field>

<Field value="aria-label" type="string">
  Accessible label for the drop target. Defaults to `"Upload profile
  picture"`.
</Field>

<Field value="onFileChange" type="(file: File | null) => void">
  Called with the selected picture, or `null` when it is removed.
</Field>

<Field value="onFileRejected" type="(rejection: DropzoneRejection) => void">
  Called when a file is rejected for being the wrong type or too big.
</Field>

<Field value="accept" type="string">
  Native accept filter. Defaults to `"image/*"`.
</Field>

<Field value="disabled" type="boolean">
  Disables the dropzone: the tile is dimmed and clicks and drops are ignored.
</Field>

AvatarDropzone forwards its ref to the hidden file input, and any remaining native `<input>` attributes (`name`, `id`, `onBlur`, and so on) pass through to it. The props above are typed by the exported `AvatarDropzoneProps` interface.

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/avatar-dropzone.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Modal

> Cherry Modal component - an animated dialog rendered in a portal with Escape and outside-click dismissal.

Source: https://cherry.al/code/modal

# Modal

<iframe className="light-only" src="https://demo.cherry.al/preview/modal?theme=light" title="Modal" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/modal?theme=dark" title="Modal" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

The Modal component renders an animated dialog on top of the page. It portals into `document.body` so the overlay always sits above transformed or clipped ancestors, and it closes on Escape, on a click outside, or with the built-in close button.

The Modal is a controlled component: the parent owns the open state. The dialog surface carries `role="dialog"` and `aria-modal="true"`, and takes its accessible name from `$title`.

For design guidelines and all interactive states, see the [Overlays](/overlays) design page.

```jsx
"use client";
import React, { useState } from "react";
import { Button, Modal } from "cherry-styled-components";

export default function Page() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open Modal</Button>
      <Modal
        $isOpen={isOpen}
        $onClose={() => setIsOpen(false)}
        $title="Modal Title"
      >
        Modal content goes here.
      </Modal>
    </>
  );
}
```

With a custom width for larger content:

```html
<Modal $isOpen={isOpen} $onClose={close} $width={800}>
  Content
</Modal>
```

## Restyling

To restyle the modal from your app, pass a `className` (or `style`). Both are applied to the overlay root, and the inner parts expose stable class hooks: `.modal-inner`, `.modal-close`, `.modal-title`, and `.modal-content`.

```html
<Modal $isOpen={isOpen} $onClose={close} className="checkout-modal">
  Content
</Modal>
```

```css
.checkout-modal .modal-inner {
  border-radius: 24px;
}
```

<Callout type="warning">
  Wrapping with `styled(Modal)` does not work: styled-components strips
  transient `$`-props before they reach the wrapped component, so the modal
  never receives `$isOpen` or `$onClose`. Target a passed class instead.
</Callout>

## Properties

<Field value="children" type="React.ReactNode">
  The modal content. It scrolls internally when taller than the viewport.
</Field>

<Field value="$isOpen" type="boolean" required>
  Whether the modal is visible. The modal animates in and out on change.
</Field>

<Field value="$onClose" type="() => void" required>
  Called when the user dismisses the modal (Escape, outside click, or the
  close button).
</Field>

<Field value="$title" type="string">
  Optional title rendered with a divider below it. Also used as the dialog's
  `aria-label`.
</Field>

<Field value="$width" type="number">
  Maximum width in pixels on large screens. Falls back to `500px` when unset.
</Field>

<Field value="$hideCloseButton" type="boolean">
  Omits the built-in close button in the top-right corner. Escape and outside
  click still dismiss the modal.
</Field>

<Field value="className" type="string">
  Applied to the overlay root, for app-level restyling. See the Restyling
  section above.
</Field>

<Field value="style" type="React.CSSProperties">
  Inline styles applied to the overlay root.
</Field>

<Callout type="note">
  The Modal is SSR-safe: it renders nothing on the server and during the first
  client render, then portals once hydration has completed.
</Callout>

<Callout type="note">
  The modal unmounts its children once the exit animation finishes, so state
  inside the modal (such as form inputs) resets between openings. To keep
  state across openings, lift it into the parent.
</Callout>

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/modal.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Toast

> Cherry Toast component - provider, hook, and animated toast stack with semantic colors and auto-hide.

Source: https://cherry.al/code/toast

# Toast

<iframe className="light-only" src="https://demo.cherry.al/preview/toast?theme=light" title="Toast notifications" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/toast?theme=dark" title="Toast notifications" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

Cherry's toast system shows short, animated notifications in a fixed stack. It consists of three parts: a provider that holds the state, a component that renders the stack, and a hook to fire notifications from anywhere in the tree.

For design guidelines and all interactive states, see the [Overlays](/overlays) design page.

Wrap your app with the provider and render the stack once. The example assumes the Cherry theme provider from [Installation](/code/installation) is already set up; rendering a toast without a theme throws:

```jsx
"use client";
import React from "react";
import {
  ToastNotifications,
  ToastNotificationsProvider,
} from "cherry-styled-components";

export default function App({ children }) {
  return (
    <ToastNotificationsProvider>
      <ToastNotifications />
      {children}
    </ToastNotificationsProvider>
  );
}
```

Fire notifications with the `useToastNotifications` hook:

```jsx
"use client";
import React from "react";
import { Button, useToastNotifications } from "cherry-styled-components";

export default function SaveButton() {
  const { addNotification } = useToastNotifications();

  return (
    <Button
      onClick={() =>
        addNotification("Changes saved successfully.", {
          color: "success",
          autoHide: 4000,
        })
      }
    >
      Save
    </Button>
  );
}
```

A toast without `autoHide` stays until the user dismisses it with the built-in close button. Either way, once a toast has animated out it is removed from the stack entirely. The stack is an `aria-live="polite"` region, so screen readers announce new toasts as they appear.

## Properties

`useToastNotifications` returns `{ notifications, addNotification, removeNotification }`. The `notifications` array holds the toasts currently in the stack; each entry carries a unique numeric `id` plus its `text`, resolved `color`, and `autoHide` value.

### addNotification

<Field value="text" type="string" required>
  The message to display.
</Field>

<Field value="config.color" type='"info" | "success" | "error" | "warning"'>
  Semantic color for the status icon. Defaults to `"info"`.
</Field>

<Field value="config.autoHide" type="number">
  Milliseconds before the toast hides itself. Omit to keep it until dismissed.
</Field>

### removeNotification

Removes a toast from state immediately, skipping the exit animation. You rarely need this yourself: the close button and `autoHide` already remove toasts after their exit animation.

<Field value="id" type="number" required>
  The `id` of the toast to remove, as found on the entries of the
  `notifications` array.
</Field>

### ToastNotifications

<Field value="$align" type='"center" | "left" | "right"'>
  Horizontal position of the stack. Defaults to `"center"`.
</Field>

<Field value="$bottom" type="boolean">
  Anchors the stack to the bottom of the viewport instead of the top.
</Field>

## Exports

The library also exports the types `ToastColor` (`"info" | "success" | "error" | "warning"`), `ToastAlign` (`"center" | "left" | "right"`), and `ToastConfig` (`{ color?, autoHide? }`; `addNotification` defaults `color` to `"info"` and `autoHide` to `0`, which keeps the toast until dismissed). For advanced use it exposes `ToastNotificationsContext`, the context behind the hook, and the styled primitives `StyledNotifications` and `StyledNotificationItem`.

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/toast.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Accordion

> Cherry Accordion component - animated disclosure with a card style and an inline variant.

Source: https://cherry.al/code/accordion

# Accordion

<iframe className="light-only" src="https://demo.cherry.al/preview/accordion?theme=light" title="Accordion" loading="lazy" style={{ width: "100%", height: "340px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/accordion?theme=dark" title="Accordion" loading="lazy" style={{ width: "100%", height: "340px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

<iframe className="light-only" src="https://demo.cherry.al/preview/accordion-inline?theme=light" title="Inline accordion" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/accordion-inline?theme=dark" title="Inline accordion" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

The Accordion component shows and hides content behind a clickable title. It animates open and close, rotates its chevron to match, and respects `prefers-reduced-motion`.

For design guidelines and all interactive states, see the [Accordions](/accordions) design page.

```jsx
import React from "react";
import { Accordion } from "cherry-styled-components";

export default function Page() {
  return (
    <Accordion title="What is Cherry?">
      Cherry is a design system for the modern web.
    </Accordion>
  );
}
```

The inline variant drops the border, radius, and side padding for embedding inside cards or lists:

```html
<Accordion title="Inline accordion" $inline>
  Content
</Accordion>
```

By default the accordion manages its own state. Pass `open` and `onToggle` to control it from the parent:

```html
<Accordion title="Controlled" open={isOpen} onToggle={setIsOpen}>
  Content
</Accordion>
```

## Properties

<Field value="children" type="React.ReactNode" required>
  The collapsible content.
</Field>

<Field value="title" type="React.ReactNode" required>
  The always-visible clickable title.
</Field>

<Field value="$inline" type="boolean">
  Removes the border, radius, and side padding for a flush, compact look.
</Field>

<Field value="defaultOpen" type="boolean">
  Renders the accordion open initially (uncontrolled mode).
</Field>

<Field value="open" type="boolean">
  Controlled open state. When provided, the parent owns open/close; pair it
  with `onToggle`.
</Field>

<Field value="onToggle" type="(isOpen: boolean) => void">
  Called with the next state whenever the title is clicked.
</Field>

All other standard `div` attributes (`className`, `id`, `style`, `aria-*`, and
so on) are passed through to the root element; the native `title` and
`onToggle` attributes are replaced by the props above.

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/accordion.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Tabs

> Cherry Tabs component - accessible tabbed panels with keyboard navigation and controlled or uncontrolled selection.

Source: https://cherry.al/code/tabs

# Tabs

<iframe className="light-only" src="https://demo.cherry.al/preview/tabs?theme=light" title="Tabs" loading="lazy" style={{ width: "100%", height: "360px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/tabs?theme=dark" title="Tabs" loading="lazy" style={{ width: "100%", height: "360px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

The Tabs component groups related content into panels behind a horizontal list of triggers. Wrap each panel in a `TabContent` with a `title`; only the active panel is rendered.

Tabs follow the WAI-ARIA tabs pattern: the triggers form a `tablist` with roving tabindex, ArrowLeft and ArrowRight cycle through the tabs (wrapping at the edges), Home and End jump to the first and last tab, and moving focus also selects the tab.

For design guidelines and all interactive states, see the [Tabs](/tabs) design page.

```jsx
import React from "react";
import { Tabs, TabContent } from "cherry-styled-components";

export default function Page() {
  return (
    <Tabs>
      <TabContent title="Overview">Overview panel content.</TabContent>
      <TabContent title="Details">Details panel content.</TabContent>
      <TabContent title="Settings">Settings panel content.</TabContent>
    </Tabs>
  );
}
```

By default Tabs manage their own selection, starting at `defaultActiveTab` (index 0 if omitted). Pass `activeTab` to control the selection from the parent, paired with `onTabChange`:

```jsx
const [tab, setTab] = useState(0);

<Tabs activeTab={tab} onTabChange={setTab}>
  <TabContent title="Overview">Overview panel content.</TabContent>
  <TabContent title="Details">Details panel content.</TabContent>
</Tabs>;
```

## Properties

### Tabs

<Field value="children" type="React.ReactNode">
  The panels, typically `TabContent` elements. Any valid React element with a
  non-empty string `title` prop becomes a tab (the element type itself is not
  checked); children without one are ignored.
</Field>

<Field value="activeTab" type="number">
  Optional controlled active tab index. When provided the parent owns the
  selection; pair it with `onTabChange`.
</Field>

<Field value="defaultActiveTab" type="number">
  Initial tab index for uncontrolled usage. Defaults to `0`.
</Field>

<Field value="onTabChange" type="(index: number) => void">
  Called with the new index whenever a tab is selected, by click or keyboard.
</Field>

All other standard `div` attributes (`className`, `id`, `style`, `aria-*`, and
so on) are passed through to the root element; only the native `onChange`
attribute is excluded.

### TabContent

<Field value="title" type="string" required>
  The tab trigger label. Required and must be non-empty.
</Field>

<Field value="children" type="React.ReactNode">
  The panel content rendered while this tab is active.
</Field>

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/tabs.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Icon

> Cherry Icon component - renders any Lucide icon by name with color, size, and accessibility control.

Source: https://cherry.al/code/icon

# Icon

The Icon component renders any icon from the [Lucide](https://lucide.dev) icon set by name. It is the same component Cherry uses internally (for example in Dropzone tiles and the Modal close button), and it powers the `$icon` props on components like Dropzone and AvatarDropzone.

For design guidelines and all interactive states, see the [Icons](/icons) design page.

```jsx
import React from "react";
import { Icon } from "cherry-styled-components";

export default function Page() {
  return <Icon name="Cherry" size={24} />;
}
```

Icons are decorative by default: without an `aria-label` they render with `aria-hidden`, so screen readers skip them. Pass an `aria-label` to make an icon meaningful; it then gets `role="img"` and the label is announced:

```html
<Icon name="TriangleAlert" color="#ef4444" aria-label="Warning" />
```

If the given name does not match a Lucide icon, the component renders nothing.

## Properties

<Field value="name" type="IconProps" required>
  Name of the Lucide icon to render, e.g. `"Cherry"` or `"FileUp"`. The exported `IconProps` type is the string union of all Lucide icon names.
</Field>

<Field value="color" type="string">
  Icon color. Defaults to the inherited text color.
</Field>

<Field value="size" type="number">
  Icon size in pixels. Defaults to `24`, from Lucide's default attributes.
</Field>

<Field value="className" type="string">
  Class name applied to the rendered SVG.
</Field>

<Field value="aria-label" type="string">
  Accessible label. When set, the icon gets `role="img"` and is announced by screen readers; when omitted, the icon is `aria-hidden`.
</Field>

## Internal usage

Cherry renders this same `Icon` component inside its own form controls, so their glyphs stay consistent with any icons you add yourself: the checkbox check mark in [Input](/code/input) uses `Check`, the dropdown arrow in [Select](/code/select) uses `ChevronDown`, and the calendar glyph on date and time inputs uses `CalendarDays`. These are colored with the theme's primary color through CSS (`currentColor`), so they follow the active palette in light and dark mode.

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/icon.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# ThemeToggle

> Cherry ThemeToggle component - a pill-shaped sun and moon switch for light and dark mode.

Source: https://cherry.al/code/theme-toggle

# ThemeToggle

<iframe className="light-only" src="https://demo.cherry.al/preview/theme-toggle?theme=light" title="Theme toggle" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/theme-toggle?theme=dark" title="Theme toggle" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

The ThemeToggle is a pill-shaped switch for light and dark mode. It shows a sun and a moon side by side, with a soft circular highlight that slides over the active icon when the theme changes.

ThemeToggle works with the providers described on the [Dark Mode](/code/dark-mode) page.

It works out of the box inside `CherryThemeProvider` or `ClientThemeProvider`: clicking it flips the current theme, persists the choice (to the `theme` cookie and `localStorage` under `ClientThemeProvider`, to `localStorage` under `CherryThemeProvider`), and keeps the `dark` class on the `<html>` element in sync. No wiring is needed. See [Dark Mode](/code/dark-mode) for the flash-free SSR setup.

Keep in mind that the `<button>` element inherently includes native browser properties like `onClick`. Cherry UI components introduce custom properties that always begin with a `$` to distinguish them from native props.

```jsx
import React from "react";
import { ThemeToggle } from "cherry-styled-components";

export default function Page() {
  return <ThemeToggle />;
}
```

A custom `onClick` runs after the theme switch, which is handy for analytics:

```html
<ThemeToggle onClick={() => trackEvent("theme toggled")} />
```

Hide it (for example while the theme is still resolving on the server) with the `$hidden` prop:

```html
<ThemeToggle $hidden={!mounted} />
```

<Callout type="note">
  ThemeToggle requires a `themeDark` to be passed to the theme provider. Without
  it there is nothing to switch to, and clicking the button does nothing.
</Callout>

## Properties

<Field value="$hidden" type="boolean">
  Hides the toggle with `display: none`, for example while the theme is still
  resolving on the server.
</Field>

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/theme-toggle.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Container

> Cherry Container component - fluid width, text alignment, and responsive padding.

Source: https://cherry.al/code/container

# Container

The Container component provides features such as fluid width, text alignment, and padding adjustments based on screen size. Use it to create responsive layouts as a wrapper for other components and content. By default the container is centered with a max-width of 1280px (1440px from the `xxxl` breakpoint) and 20px padding (40px from the `lg` breakpoint).

```jsx
import React from "react";
import { Container } from "cherry-styled-components";

export default function Page() {
  return <Container $textAlign="center">Your content goes here!</Container>;
}
```

## Properties

<Field value="children" type="React.ReactNode">
  Container content.
</Field>

<Field value="className" type="string">
  Class name applied to the container element.
</Field>

<Field value="$fluid" type="boolean">
  Makes the container full-width without max-width constraints.
</Field>

<Field value="$textAlign" type='"right" | "left" | "center"'>
  Text alignment within the container.
</Field>

<Field value="$padding" type='number | "none"'>
  Base padding value in pixels. Replaces both the 20px default and the 40px `lg`-breakpoint default. Pass a number here: `"none"` is only handled by the breakpoint-specific props and produces invalid CSS on `$padding`, so use `$xsPadding="none"` to remove padding instead.
</Field>

<Field value="$xsPadding" type='number | "none"'>
  Padding at `xs` breakpoint.
</Field>

<Field value="$smPadding" type='number | "none"'>
  Padding at `sm` breakpoint.
</Field>

<Field value="$mdPadding" type='number | "none"'>
  Padding at `md` breakpoint.
</Field>

<Field value="$lgPadding" type='number | "none"'>
  Padding at `lg` breakpoint.
</Field>

<Field value="$xlPadding" type='number | "none"'>
  Padding at `xl` breakpoint.
</Field>

<Field value="$xxlPadding" type='number | "none"'>
  Padding at `xxl` breakpoint.
</Field>

<Field value="$xxxlPadding" type='number | "none"'>
  Padding at `xxxl` breakpoint.
</Field>

The Container also accepts all standard HTML `div` attributes and forwards its `ref` to the underlying `div` element.

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/container.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Box

> Cherry Box component - extends Container with additional visual styling for tiles and card layouts.

Source: https://cherry.al/code/box

# Box

<iframe className="light-only" src="https://demo.cherry.al/preview/box?theme=light" title="Box" loading="lazy" style={{ width: "100%", height: "340px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/box?theme=dark" title="Box" loading="lazy" style={{ width: "100%", height: "340px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

The Box component is a styled variant of the Container component. It accepts exactly the same props and adds no new ones; the only difference is visual styling: a `theme.colors.light` background, rounded corners from `theme.spacing.radius.lg` (12px by default), and a 1px `theme.colors.grayLight` border. Use it to create visually appealing boxes, tiles, or containers within your applications.

```jsx
import React from "react";
import { Box } from "cherry-styled-components";

export default function Page() {
  return <Box>Boxing things around!</Box>;
}
```

## Properties

<Field value="children" type="React.ReactNode">
  Box content.
</Field>

<Field value="className" type="string">
  Additional CSS class for the box.
</Field>

<Field value="$fluid" type="boolean">
  Makes the box full-width without max-width constraints.
</Field>

<Field value="$textAlign" type='"right" | "left" | "center"'>
  Text alignment within the box.
</Field>

<Field value="$padding" type='number | "none"'>
  Base padding value.
</Field>

<Field value="$xsPadding" type='number | "none"'>
  Padding at `xs` breakpoint.
</Field>

<Field value="$smPadding" type='number | "none"'>
  Padding at `sm` breakpoint.
</Field>

<Field value="$mdPadding" type='number | "none"'>
  Padding at `md` breakpoint.
</Field>

<Field value="$lgPadding" type='number | "none"'>
  Padding at `lg` breakpoint.
</Field>

<Field value="$xlPadding" type='number | "none"'>
  Padding at `xl` breakpoint.
</Field>

<Field value="$xxlPadding" type='number | "none"'>
  Padding at `xxl` breakpoint.
</Field>

<Field value="$xxxlPadding" type='number | "none"'>
  Padding at `xxxl` breakpoint.
</Field>

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/box.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# MaxWidth

> Cherry MaxWidth component - constrains content width with responsive breakpoints.

Source: https://cherry.al/code/max-width

# MaxWidth

The MaxWidth component is a container that allows you to set a maximum width for its content. Useful for creating centered layouts with width constraints.

```jsx
import React from "react";
import { MaxWidth, Box } from "cherry-styled-components";

export default function Page() {
  return (
    <MaxWidth $size={150}>
      <Box>150px</Box>
    </MaxWidth>
  );
}
```

## Properties

<Field value="children" type="React.ReactNode">
  Content to constrain.
</Field>

<Field value="$size" type="number">
  Maximum width in pixels.
</Field>

<Field value="$xs" type="number">
  Max width at `xs` breakpoint.
</Field>

<Field value="$sm" type="number">
  Max width at `sm` breakpoint.
</Field>

<Field value="$md" type="number">
  Max width at `md` breakpoint.
</Field>

<Field value="$lg" type="number">
  Max width at `lg` breakpoint.
</Field>

<Field value="$xl" type="number">
  Max width at `xl` breakpoint.
</Field>

<Field value="$xxl" type="number">
  Max width at `xxl` breakpoint.
</Field>

<Field value="$xxxl" type="number">
  Max width at `xxxl` breakpoint.
</Field>

<Field value="$m0" type="boolean">
  Removes horizontal centering (sets margin to `0` instead of `auto`).
</Field>

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/max-width.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Flex

> Cherry Flex component - responsive flexbox layouts with gap and alignment control.

Source: https://cherry.al/code/flex

# Flex

<iframe className="light-only" src="https://demo.cherry.al/preview/flex?theme=light" title="Flex" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/flex?theme=dark" title="Flex" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

The Flex component is a flexible container for creating responsive layouts. It's useful for arranging child elements in a row or column, adjusting the gap between them, and controlling alignment. Flex adapts to different screen sizes with responsive props like `$xsGap` and `$smJustifyContent`. You will see this pattern throughout the Cherry Design System.

```jsx
import React from "react";
import { Flex, Box } from "cherry-styled-components";

export default function Page() {
  return (
    <Flex $justifyContent="center">
      <Box>Box</Box>
      <Box>Box</Box>
    </Flex>
  );
}
```

Responsive variants apply from their breakpoint upwards. This example stacks the boxes in a column, then switches to a centered row from the `lg` breakpoint:

```jsx
import React from "react";
import { Flex, Box } from "cherry-styled-components";

export default function Page() {
  return (
    <Flex $direction="column" $lgDirection="row" $lgJustifyContent="center">
      <Box>Box</Box>
      <Box>Box</Box>
    </Flex>
  );
}
```

## Properties

<Field value="children" type="React.ReactNode">
  Flex container content.
</Field>

<Field value="$justifyContent" type='"center" | "flex-start" | "flex-end" | "space-between" | "space-around" | "space-evenly"'>
  Justify content alignment along the main axis. Defaults to `"flex-start"`. Also available as responsive variants: `$xsJustifyContent`, `$smJustifyContent`, `$mdJustifyContent`, `$lgJustifyContent`, `$xlJustifyContent`, `$xxlJustifyContent`, `$xxxlJustifyContent`.
</Field>

<Field value="$alignItems" type='"stretch" | "center" | "flex-start" | "flex-end" | "baseline"'>
  Align items along the cross axis. Defaults to `"stretch"`. Also available as responsive variants: `$xsAlignItems`, `$smAlignItems`, `$mdAlignItems`, `$lgAlignItems`, `$xlAlignItems`, `$xxlAlignItems`, `$xxxlAlignItems`.
</Field>

<Field value="$alignContent" type='"stretch" | "center" | "flex-start" | "flex-end" | "space-between" | "space-around" | "space-evenly"'>
  Align content distributes wrapped lines along the cross axis. Defaults to `"stretch"`. Also available as responsive variants: `$xsAlignContent`, `$smAlignContent`, `$mdAlignContent`, `$lgAlignContent`, `$xlAlignContent`, `$xxlAlignContent`, `$xxxlAlignContent`.
</Field>

<Field value="$wrap" type='"wrap" | "nowrap" | "wrap-reverse"'>
  Flex wrap behavior. Defaults to `"wrap"`.
</Field>

<Field value="$gap" type='number | "none"'>
  Gap between flex items. Defaults to the theme's `gridGap` (`20px`, and `40px` from the `lg` breakpoint). Also available as responsive variants: `$xsGap`, `$smGap`, `$mdGap`, `$lgGap`, `$xlGap`, `$xxlGap`, `$xxxlGap`. Note that on the base `$gap`, `"none"` behaves like `undefined`, so the theme default still applies; only the responsive variants map `"none"` to `0`.
</Field>

<Field value="$direction" type='"row" | "column" | "row-reverse" | "column-reverse"'>
  Flex direction. Defaults to `"row"`. Also available as responsive variants: `$xsDirection`, `$smDirection`, `$mdDirection`, `$lgDirection`, `$xlDirection`, `$xxlDirection`, `$xxxlDirection`.
</Field>

<Field value="$fullWidth" type="boolean">
  Makes the flex container span the full width of its parent.
</Field>

Flex also accepts all standard `div` attributes (`className`, `id`, `onClick`, etc.) and forwards its `ref` to the underlying `div` element.

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/flex.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Grid

> Cherry Grid component - responsive CSS grid layouts.

Source: https://cherry.al/code/grid

# Grid

<iframe className="light-only" src="https://demo.cherry.al/preview/grid?theme=light" title="Grid" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />
<iframe className="dark-only" src="https://demo.cherry.al/preview/grid?theme=dark" title="Grid" loading="lazy" style={{ width: "100%", height: "320px", border: "1px solid var(--color-grayLight)", borderRadius: "12px" }} />

The Cherry Grid system simplifies creating responsive layouts using the modern CSS grid property. It allows you to define the grid structure, including the number of columns and the gaps.

```jsx
import React from "react";
import { Container, Grid, Col, Input, Button } from "cherry-styled-components";

export default function Page() {
  return (
    <Container>
      <Grid $xsCols={1} $lgCols={3}>
        <Col $lgSpan={3}>
          <Input type="text" $fullWidth />
        </Col>
        <Button $variant="primary">Save</Button>
        <Button $variant="secondary">Cancel</Button>
        <Button $outline>Remind Later</Button>
      </Grid>
    </Container>
  );
}
```

## Properties

<Field value="children" type="React.ReactNode">
  Grid content.
</Field>

<Field value="$gap" type='number | "none"'>
  Gap between grid items in pixels. Defaults to the theme's `gridGap` (`20px` below the `lg` breakpoint, `40px` from `lg` up). Also available as responsive variants: `$xsGap`, `$smGap`, `$mdGap`, `$lgGap`, `$xlGap`, `$xxlGap`, `$xxxlGap`. Note that `"none"` only maps to `0` on the responsive variants; on the base `$gap` prop it falls back to the theme default, so use `$gap={0}` to remove the gap at all sizes.
</Field>

<Field value="$cols" type="number">
  Number of columns. Defaults to `3`. Also available as responsive variants: `$xsCols`, `$smCols`, `$mdCols`, `$lgCols`, `$xlCols`, `$xxlCols`, `$xxxlCols`.
</Field>

<Callout type="info">
  See the [Col](/code/col) component for controlling how children span across grid columns.
</Callout>

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/grid.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Col

> Cherry Col component - responsive column spans within Grid layouts.

Source: https://cherry.al/code/col

# Col

The Col component complements the Grid component by allowing you to create responsive column layouts. Specify the number of columns a child element should occupy.

The example below assumes the Cherry theme provider from [Installation](/code/installation) is already set up.

```jsx
import React from "react";
import { Container, Grid, Col, Input, Button } from "cherry-styled-components";

export default function Page() {
  return (
    <Container>
      <Grid $xsCols={1} $lgCols={3}>
        <Col $lgSpan={3}>
          <Input type="text" $fullWidth />
        </Col>
        <Button $variant="primary">Save</Button>
        <Button $variant="secondary">Cancel</Button>
        <Button $outline>Remind Later</Button>
      </Grid>
    </Container>
  );
}
```

In this example:

- The Col wrapping the Input spans 1 column on `xs` screens and all 3 columns on `lg` screens.
- The three Buttons each span 1 column at all breakpoints.

## Properties

<Field value="children" type="React.ReactNode">
  Column content.
</Field>

<Field value="$span" type="number">
  Number of columns to span. Also available as responsive variants: `$xsSpan`, `$smSpan`, `$mdSpan`, `$lgSpan`, `$xlSpan`, `$xxlSpan`, `$xxxlSpan`.
</Field>

<Callout type="info">
  See the [Grid](/code/grid) component for defining the grid structure.
</Callout>

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/col.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Space

> Cherry Space component - responsive vertical and horizontal spacing between elements.

Source: https://cherry.al/code/space

# Space

Space is an element that allows you to create spaces between elements. Whether you need horizontal or vertical spacing, the Space component has got you covered. It seamlessly adapts to different media queries.

The example below assumes the Cherry theme provider from [Installation](/code/installation) is already set up.

```jsx
import React from "react";
import { Container, Button, Space } from "cherry-styled-components";

export default function Page() {
  return (
    <Container>
      <Button>Button</Button>
      <Space $xs={20} $lg={40} />
      <Button>Button</Button>
    </Container>
  );
}
```

In the example above, two buttons have a space of 20px on extra small screens and 40px on large screens.

Every size prop also accepts the string `"none"`, which sets `display: none` and hides the spacer entirely at that breakpoint.

## Properties

<Field value="$size" type='number | "none"'>
  Space size in pixels.
</Field>

<Field value="$xs" type='number | "none"'>
  Size at `xs` breakpoint.
</Field>

<Field value="$sm" type='number | "none"'>
  Size at `sm` breakpoint.
</Field>

<Field value="$md" type='number | "none"'>
  Size at `md` breakpoint.
</Field>

<Field value="$lg" type='number | "none"'>
  Size at `lg` breakpoint.
</Field>

<Field value="$xl" type='number | "none"'>
  Size at `xl` breakpoint.
</Field>

<Field value="$xxl" type='number | "none"'>
  Size at `xxl` breakpoint.
</Field>

<Field value="$xxxl" type='number | "none"'>
  Size at `xxxl` breakpoint.
</Field>

<Field value="$horizontal" type="boolean">
  Creates horizontal spacing instead of vertical.
</Field>

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/space.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Mixins

> Cherry's reusable CSS mixins: interaction affordances, resets, and form element helpers.

Source: https://cherry.al/code/mixins

# Mixins

Cherry exports the CSS mixins its own components are built from, so custom elements in your app can share the exact same look and behavior. All of them are plain `styled-components` css fragments or helper functions - interpolate them into any styled component.

## interactiveStyles

The hover, focus, and active affordance used for interactive surfaces like cards, tiles, and block-level links: a transparent 1px border that picks up the primary color on hover, plus a soft focus ring. Pair it with `resetButton` for clickable elements that aren't Buttons.

```tsx
import styled from "styled-components";
import { interactiveStyles, resetButton } from "cherry-styled-components";

const ClickableCard = styled.button`
  ${resetButton}
  ${interactiveStyles}
  border-radius: 12px;
  padding: 20px;
`;
```

## errorInteractiveStyles

The destructive-action sibling of `interactiveStyles`: identical hover, focus, and active behavior, but in the theme error red (the same red the `$error` Button uses). Use it for delete and remove affordances.

```tsx
import styled from "styled-components";
import { errorInteractiveStyles, resetButton } from "cherry-styled-components";

const RemoveTile = styled.button`
  ${resetButton}
  ${errorInteractiveStyles}
  border-radius: 12px;
  padding: 20px;
`;
```

## Resets

- `resetButton` - Strips native button styling (appearance, border, background, padding, margin) and sets `box-sizing: border-box`, `cursor: pointer`, and `outline: none`. Since the focus outline is removed, pair it with `interactiveStyles` or provide your own focus style. The base of Button, IconButton, and ThemeToggle.
- `resetInput` - Minimal input reset used by the form components.

## Form helpers

- `fullWidthStyles(fullWidth)` - Returns `width: 100%` when the flag is set. Backs the `$fullWidth` prop across components. Unlike the other two helpers, its parameter has no `$` sigil.
- `statusBorderStyles($error, $success, theme)` - Border color for error and success validation states.
- `formElementHeightStyles($size)` - Shared height for form elements in the three sizes (`small`, `default`, `big`).

## Responsive style generators

Used internally by the layout components, and available for custom components that take per-breakpoint props:

- `generateGapStyles`, `generateColsStyles`, `generateColSpanStyles`
- `generatePaddingStyles`, `generateJustifyContentStyles`
- `generateAlignItemsStyles`, `generateAlignContentStyles`, `generateDirectionStyles`

Each takes `(size: keyof Breakpoints<number>, value)` and returns the declaration wrapped in the `mq(size)` min-width media query for that breakpoint (`xs`, `sm`, `md`, `lg`, `xl`, `xxl`, `xxxl`):

```tsx
import styled from "styled-components";
import {
  generateGapStyles,
  generateDirectionStyles,
} from "cherry-styled-components";

const Toolbar = styled.div`
  display: flex;
  ${generateGapStyles("xs", 10)}
  ${generateGapStyles("lg", 20)}
  ${generateDirectionStyles("xs", "column")}
  ${generateDirectionStyles("lg", "row")}
`;
```

The component style mixins `buttonStyles` and `iconButtonStyles` are documented on the [Button](/code/button) and [IconButton](/code/icon-button) pages.

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/utils/mixins.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Typography

> Cherry typography helpers - CSS mixins for every text style in the type scale.

Source: https://cherry.al/code/typography

# Typography

Every text style in the Cherry type scale is available as a CSS mixin. Each helper takes the theme and returns the responsive `font-size` and `line-height` for its style: the mobile (`xs`) values apply as the base, and the desktop (`lg`) values kick in from the `lg` breakpoint (992px by default) via the `mq()` media query helper. Interpolate a helper into any styled component to give one element the type of another - the classic case is an `h2` that should look like an `h1`:

```tsx
import styled from "styled-components";
import { styledH1 } from "cherry-styled-components";

const SectionTitle = styled.h2`
  ${({ theme }) => styledH1(theme)}
`;
```

The values are read from `theme.fontSizes` and `theme.lineHeights`, so any overrides in a custom [Theme](/code/theme) flow through automatically. The full scale with design specs lives on the [Typography](/typography) page.

## Helpers

Sizes below are shown as font-size / line-height for the `xs` and `lg` values of the default theme.

### Hero

| Helper        | Theme key | XS          | LG           |
| ------------- | --------- | ----------- | ------------ |
| `styledHero1` | `hero1`   | 72px / 1.10 | 128px / 1.10 |
| `styledHero2` | `hero2`   | 60px / 1.10 | 96px / 1.10  |
| `styledHero3` | `hero3`   | 36px / 1.20 | 72px / 1.10  |

### Headings

| Helper     | Theme key | XS          | LG          |
| ---------- | --------- | ----------- | ----------- |
| `styledH1` | `h1`      | 40px / 1.50 | 60px / 1.40 |
| `styledH2` | `h2`      | 30px / 1.50 | 36px / 1.50 |
| `styledH3` | `h3`      | 28px / 1.30 | 30px / 1.50 |
| `styledH4` | `h4`      | 26px / 1.30 | 24px / 1.50 |
| `styledH5` | `h5`      | 18px / 1.60 | 20px / 1.50 |
| `styledH6` | `h6`      | 16px / 1.60 | 18px / 1.60 |

### Text

| Helper             | Theme key    | XS          | LG          |
| ------------------ | ------------ | ----------- | ----------- |
| `styledText`       | `text`       | 14px / 1.70 | 16px / 1.70 |
| `styledStrong`     | `strong`     | 14px / 1.70 | 16px / 1.70 |
| `styledSmall`      | `small`      | 12px / 1.70 | 14px / 1.70 |
| `styledBlockquote` | `blockquote` | 16px / 1.70 | 18px / 1.70 |
| `styledCode`       | `code`       | 14px / 1.70 | 16px / 1.70 |

### Controls

| Helper            | Theme key   | XS          | LG          |
| ----------------- | ----------- | ----------- | ----------- |
| `styledButton`    | `button`    | 16px / 1.00 | 16px / 1.00 |
| `styledButtonBig` | `buttonBig` | 18px / 1.00 | 18px / 1.00 |
| `styledInput`     | `input`     | 16px / 1.00 | 16px / 1.00 |
| `styledInputBig`  | `inputBig`  | 18px / 1.00 | 18px / 1.00 |

<Callout type="note">
  The helpers set only `font-size` and `line-height`. Font-weight and
  font-family are not included, so heading weights come from the browser's bold
  defaults for `h1` to `h6` unless you set `font-weight` yourself.
</Callout>

## createTypographyStyle

All of the helpers above are built with the `createTypographyStyle` factory. It takes a key of the theme's `FontSizes` interface and returns a `(theme: Theme) => css` function that outputs the responsive declarations for that key. The theme scale also includes `buttonSmall` and `inputSmall` keys that have no prebuilt helper - use the factory to cover those:

```tsx
import styled from "styled-components";
import { createTypographyStyle } from "cherry-styled-components";

const styledButtonSmall = createTypographyStyle("buttonSmall");

const TinyLabel = styled.span`
  ${({ theme }) => styledButtonSmall(theme)}
`;
```

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/utils/typography.tsx" icon="code" iconPosition="left">
  View Source
</Button>

---

# Hooks

> Cherry utility hooks - useOnClickOutside for dismissing menus, popovers, and other floating UI.

Source: https://cherry.al/code/hooks

# Hooks

Cherry exports utility hooks alongside its components.

## useOnClickOutside

Calls a callback when a click lands outside all of the given elements. Useful for dismissing menus, popovers, and other floating UI. Cherry's own Modal uses it to close on outside clicks.

```tsx
useOnClickOutside(refs: RefObject<HTMLElement | null>[], cb: () => void): void
```

```jsx
"use client";
import React, { useRef, useState } from "react";
import { useOnClickOutside, Button } from "cherry-styled-components";

export default function Menu() {
  const [open, setOpen] = useState(false);
  const menuRef = useRef(null);
  const buttonRef = useRef(null);

  useOnClickOutside([menuRef, buttonRef], () => setOpen(false));

  return (
    <>
      <Button ref={buttonRef} onClick={() => setOpen(!open)}>
        Menu
      </Button>
      {open && <div ref={menuRef}>...</div>}
    </>
  );
}
```

Behavior details:

- Listens for `mousedown` on the document and fires the callback when the click target is inside none of the passed refs.
- Unattached refs (with a `null` current value) are ignored: a click counts as outside unless it lands inside a currently mounted ref target.
- The document listener is subscribed once per mount. You can safely pass inline arrays and inline callbacks; the hook keeps the latest values in a ref instead of re-subscribing on every render.

## Parameters

<Field value="refs" type="RefObject<HTMLElement | null>[]" required>
  Refs to the elements that count as "inside". Clicks within any of them do not trigger the callback.
</Field>

<Field value="cb" type="() => void" required>
  Callback invoked when a click lands outside all ref targets.
</Field>

<Button href="https://github.com/cherry-design-system/styled-components/blob/main/src/lib/utils/use-on-click-outside.tsx" icon="code" iconPosition="left">
  View Source
</Button>