# Yle Design System (YDS) — Complete Documentation

---

# Get started

# For AI agents

Coding agents such as Claude Code and Cursor can build with YDS: they read the documentation as Markdown and install the same packages developers do. Agents do best when the project tells them where the docs are, which rules to follow and how the app is set up. This page collects the techniques that make that work, most of them from the YDS Agentic Proto Kit.

## Start from the proto kit

The [YDS Agentic Proto Kit](https://github.com/Yleisradio/yds-agentic-proto-kit) is a starter project for prototyping with YDS and AI agents: React, TypeScript and Vite, with everything on this page already in place.

- YDS 3.0 set up: tokens on `:root`, cascade layers, components, icons, infographics and custom themes
- A copy of the YDS docs in `.yds-docs/`
- Agent instructions in `AGENTS.md`, shared by Claude Code and Cursor
- Skills for building UI, charts and custom themes

```bash
cp .env.example .env.local   # then add your GitHub token
npm run setup
npm run dev
```

The token is the same one developers use: see [Install the packages](#install-the-packages).

## Read the documentation

| File | Contents |
| --- | --- |
| [`/llms.txt`](/llms.txt) | Index of every page, with links to the Markdown versions. Follows the [llms.txt](https://llmstxt.org/) convention. |
| [`/llm/…`](/llm/components/Button/Button.md) | One page as Markdown, for example `/llm/components/Button/Button.md` |
| [`/llms-full.txt`](/llms-full.txt) | Every page in one file |

Start from `llms.txt` and fetch only the pages the task needs. `llms-full.txt` is around 800 KB, more than most agents can hold in context at once.

The Markdown versions keep the page content and replace the interactive parts:

- **Component previews** become a *Live preview* link to the page on this site. Code examples stay as code blocks.
- **Token tables** list the CSS custom property and the JavaScript constant for each token, for example `--yds-spacing-16` and `spacing.SPACING_16`.
- **Figma and Storybook links** stay at the top of the page.

## Keep a copy of the docs in the project

Agents read local files faster and more reliably than they fetch URLs. A copy in the project also keeps the docs in step with the package versions you use. This downloads every page and the index into `.yds-docs/`:

```bash
BASE=https://design-system.yle.fi
mkdir -p .yds-docs
curl -fsSL "$BASE/llm/README.md" -o .yds-docs/README.md
curl -fsSL "$BASE/llms.txt" | grep -o '/llm/[^)]*\.md' | while read -r page; do
  file=".yds-docs/${page#/llm/}"
  mkdir -p "$(dirname "$file")"
  curl -fsSL "$BASE$page" -o "$file"
done
```

Run it again when you upgrade YDS packages.

## Write the agent instructions

### One file for every tool

Keep the rules in `AGENTS.md` and point the other tools to it, so they never drift apart:

- **Claude Code:** `CLAUDE.md` contains a single line, `@AGENTS.md`, which imports the file.
- **Cursor:** a rule in `.cursor/rules/` applies to `**/*.tsx` files and refers to `AGENTS.md` for the details.

### Make the agent look things up

Without instructions, agents guess component APIs from general React knowledge. Tell the agent to read the docs first, and give it the index so it knows which pages exist:

```md
## YDS documentation index

> Prefer retrieval-led reasoning over pre-training-led reasoning for any YDS task.
> Read the relevant file from `.yds-docs/` instead of relying on training data.

<!-- YDS-DOCS-INDEX:START -->
- [Button](.yds-docs/components/Button/Button.md)
- …
<!-- YDS-DOCS-INDEX:END -->
```

The proto kit fills the index automatically: its docs script copies `.yds-docs/README.md` between the markers and rewrites the links to point into `.yds-docs/`.

### State the rules, with wrong and right examples

Short rules with a wrong and a right example work better than long explanations. The rules that matter most:

- **Use YDS components** from `@yleisradio/yds-components-react` instead of custom HTML for anything YDS already provides.
- **Use tokens, never hardcoded values.** Token values already include units, so don't append `px`.
- **Use semantic theme colours.** `var(--yds-color-text-default)` follows the theme; `var(--yds-color-gray-95)` doesn't. Don't import `lightTheme` or `darkTheme` for UI colours either: they're literal hex values. In TypeScript, `defaultTheme.TEXT_DEFAULT` is the typed equivalent of the CSS variable.
- **No 2.x patterns.** Don't read `theme.yds` or add a `styled.d.ts` with `yds`, `ydsThemeName` or `ydsThemeProps`; they don't exist in 3.0.
- **Icons come from** `@yleisradio/yds-icons-react`. Point the agent to the icon list in the docs.
- **Say what to do when YDS has no match:** build it from YDS tokens. The proto kit also allows `lucide-react`, sparingly, for missing icons.
- **Translate Figma designs, don't copy them.** Code from the Figma MCP server is a reference: map its components and variables to YDS components and tokens.

```css
/* WRONG */
.title {
  color: #1a1a1a;
  font-size: 24px;
  padding: 16px;
}

/* RIGHT */
.title {
  color: var(--yds-color-text-default);
  font-size: var(--yds-typography-default-2xl-bold-font-size);
  font-weight: var(--yds-typography-default-2xl-bold-font-weight);
  line-height: var(--yds-typography-default-2xl-bold-line-height);
  padding: var(--yds-spacing-16);
}
```

### Load detailed workflows only when needed

Keep `AGENTS.md` short and move task-specific detail into skills that the agent loads when the task calls for them. The proto kit has three, for both Claude Code and Cursor:

| Skill | When it loads |
| --- | --- |
| `use-yds` | Building a screen, page or component: checking the docs, picking components, styling with CSS Modules, verifying the build |
| `use-yds-infographics` | Charts and weather icons: required CSS imports, chart props and data format, the icon catalogue |
| `use-yds-theme-custom` | Product or brand themes: generating light and dark themes from two colours with `@yleisradio/yds-theme-custom` |

## Work from Figma designs

Connect the [Figma MCP server](https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server) to the agent and give it links to Figma frames. The agent then reads the layout, components and variables directly instead of guessing from a screenshot. This works best when the design uses the YDS Figma libraries, because its components and variables map to YDS components and tokens in code.

The server returns generic React code, so keep the "translate, don't copy" rule above in the agent instructions. [Prototyping with YDS and AI](./for-designers.md#prototyping-with-yds-and-ai) has the step-by-step version for designers.

## Set the app up the way YDS expects

Agents get the YDS 3.0 setup wrong most often in the same few places. Have the project set up correctly from the start, and repeat these points in the instructions:

- **Tokens on `:root`:** one CSS file imports the token CSS from `@yleisradio/yds-core`. See [Put tokens on `:root`](../using-yds/development/get-started-with-v3.md#3-put-tokens-on-root).
- **Layer order first:** declare `@layer reset, yds, app;` before any component CSS loads, and put app styles in `@layer app`. An unlayered reset strips spacing from components.
- **No app-wide theme provider:** `YdsThemeProvider` themes a subtree. Use it only for a nested or custom theme.
- **Extend components with `className`:** never target their internal class names or use `!important`.
- **Infographics:** import `@yleisradio/yds-infographic-components-react/style.css` and the infographic token CSS, or charts render unstyled.

```css
/* global.css, imported first */
@layer reset, yds, app;

@layer reset {
  *,
  *::before,
  *::after {
    box-sizing: border-box;
  }
}
```

```tsx
// main.tsx
import './global.css';
import './yds-tokens.css';

import { ToastProvider, ToastNotifications } from '@yleisradio/yds-components-react';

<ToastProvider>
  <App />
  <ToastNotifications />
</ToastProvider>;
```

Bundler settings, Vite included, are in [Get started with 3.0](../using-yds/development/get-started-with-v3.md#4-let-the-bundler-compile-css-modules).

## Install the packages

Agents need the same GitHub Packages access as developers: see [Get access to the packages](./for-developers.md#get-access-to-the-packages). Keep the token where the agent can't read it:

- Store the token in `.env.local` and generate `.npmrc` from it with a setup script, as the proto kit does. Both files are gitignored.
- List both files in `.claudeignore` and `.cursorignore`, so the agent never reads the token into its context.
- In Docker builds, pass the token as a [build secret](https://docs.docker.com/build/building/secrets/) so it isn't stored in an image layer.

## Let the agent check its work

- Ask the agent to run the type check and lint after every change. The `use-yds` skill ends with `npm run build` and `npm run lint`.
- In Claude Code, allow the project's own scripts (`npm run dev`, `build`, `lint`, `format`) in `.claude/settings.json`, so the agent can run them without asking each time.
- Add the dev server to `.claude/launch.json`, so the agent can open the app in a preview and look at the result.

# For designers

There are two ways to design with YDS. Both use the same components and tokens, so the result stays consistent with Yle's services either way. Choose whichever suits the task, or combine them.

- **[Using YDS in Figma](#using-yds-in-figma):** detailed UI design, design reviews and handoff. You work with the YDS Figma libraries and produce a design file.
- **[Prototyping with YDS and AI](#prototyping-with-yds-and-ai):** trying out ideas quickly, interactive flows and real data. An AI coding agent builds a working prototype from YDS components.

## Using YDS in Figma

The YDS Figma libraries contain the same components, tokens and icons that the code packages implement. A design built from them can be implemented with existing components.

### Enable the libraries

1. Open a design file in Yle's Figma.
2. In the **Assets** panel, open **Libraries**.
3. Enable the libraries you need:
   - [YDS Foundation](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation): tokens, light and dark themes, text styles and components. Needed for all UI work.
   - [YDS Global Colors](https://www.figma.com/design/3ARTAZ2XrJHPq2g8iSBORW/YDS-Global-Colors): global palettes and colour swatches.
   - [YDS Icons and Logos](https://www.figma.com/design/lSboxfILj3Thr1o145POJv/YDS-Icons-and-Logos): basic icons, illustrative icons, logos and graphical assets.
   - [YDS Infographics](https://www.figma.com/design/ttv0a97s8ViuxBHtRyn3n2/YDS-Infographics): colour themes, weather symbols and examples of simple infographic components.

The Yle Next font is available in Yle's Figma without installing anything. Use the YDS text styles instead of setting font properties by hand.

If you can't open the libraries, ask on the [#design-system](https://yle.slack.com/archives/C01KDJ7JX5Y) Slack channel.

### Design with tokens

- **Use theme colours for UI.** Theme colours are semantic, grouped by purpose: background, text, action, border, feedback and so on. They have a light and a dark value, so a design built with them works in both themes. Use the global palette only when no theme colour fits. See [Theme colors](../design-tokens/theme-colors.md).
- **Space with the spacing scale.** Spacing follows an 8 px rhythm, with 2 px and 4 px for fine adjustments inside components. See [Spacing](../design-tokens/spacing.md).
- **Use text styles for typography.** See [Typography](../design-tokens/typography.md).
- **Check the themes the service uses.** Yle services use both light and dark themes; Yle Areena uses only the dark theme.

### Accessibility checks

YDS colour pairings meet WCAG 2.2 AA contrast when used as documented. When a design combines colours in other ways, check the contrast yourself, for example with a contrast plugin such as Able. Colour-vision simulation, for example with the Color Blind plugin, shows whether information depends on colour alone.

### Handing off to developers

- Every component and token page on this site links to its Figma node and Storybook story at the top.
- Refer to components by the names used on this site; code uses the same names.
- For animation, describe the motion with the transition tokens. See [Motion](../design-principles/motion-language-principles.md) and [Transitions](../design-tokens/transitions.md).

## Prototyping with YDS and AI

An AI coding agent such as Claude Code or Cursor can build a working prototype from real YDS components while you describe what you want in plain language. The prototype looks and behaves like a Yle service, runs in the browser, and can use real data.

### Get started

1. Get a copy of the [YDS Agentic Proto Kit](https://github.com/Yleisradio/yds-agentic-proto-kit). It comes with the agent instructions that keep the agent on YDS components and tokens.
2. Create a GitHub token for installing the YDS packages. The proto kit has a [step-by-step guide](https://github.com/Yleisradio/yds-agentic-proto-kit/blob/main/docs/github-npm-token.md).
3. Copy `.env.example` to `.env.local` and paste the token there yourself. The agent is set up not to read that file.
4. Open the project in your AI coding tool and ask it to run `npm run setup` and start the dev server.

[For AI agents](./for-ai-agents.md) explains how the proto kit works and how to set up your own project the same way.

### Start from a Figma design

For the best results, connect the [Figma MCP server](https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server) to your AI coding tool. The agent can then read a frame straight from Figma, with its layout, components and variables, instead of working from a written description or a screenshot.

1. Set up the Figma MCP server in your AI coding tool. Figma recommends the remote server.
2. Design or sketch the screen with the YDS libraries. Use YDS components and variables rather than detached copies and hand-picked values, so the agent can tell which YDS component and token each part is.
3. Copy the link to the frame and give it to the agent in the proto kit, for example: *"Build this screen with YDS components and tokens:"* followed by the link.

The Figma MCP server returns generic React code as a reference. Ask the agent to rebuild the screen with YDS components and tokens instead of copying that code's markup and values.

### Tips for prompting

- **Name the components.** "A list of ChoiceButtons with a primary Button below" gets closer than "some options and a submit button". The [Components](../components/index.md) page shows what is available.
- **Check both themes** and try the prototype with a keyboard. The components are accessible, but how they are combined is up to the prototype.
- **Ask the agent to explain** which components and tokens it used, if you plan to hand the idea off as a design.

## Before designing something new

Whichever way you use YDS:

1. Check [Components](../components/index.md) or the YDS Foundation library in Figma. An existing component, or a variant of one, may already cover the need.
2. Check the [project board](https://github.com/orgs/Yleisradio/projects/32) and [open issues](https://github.com/Yleisradio/yle-design-system/issues) to see if what you need is in progress.
3. Think beyond your own service: would other services need this too? Write down the use cases.
4. If something is missing from YDS: Propose it. See [Support and contributing](./support.md).

# For developers

YDS ships as npm packages for web and React Native, plus static files for native apps. See [Overview](./overview.md#packages) for the full package list.

## Get access to the packages

The packages are published to Yle's GitHub Packages registry, so installing them needs a GitHub account with access to the Yleisradio organisation.

1. Point the `@yleisradio` scope to GitHub Packages in the project's `.npmrc`:

   ```ini
   @yleisradio:registry=https://npm.pkg.github.com/
   ```

2. Create a [personal access token (classic)](https://github.com/settings/tokens) with the `read:packages` scope. Fine-grained tokens don't work with the npm registry.

3. Authorise the token for the Yleisradio organisation: in the token list, select **Configure SSO** and **Authorize** next to *yleisradio*. Without this step, installs fail with `401 Unauthorized`.

4. [Authenticate npm with the token](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-with-a-personal-access-token), for example in `.npmrc`:

   ```ini
   //npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
   ```

   Keep the token itself out of version control.

5. Give the same access to every environment that installs packages: CI, deployment builds and AI agent sandboxes. In GitHub Actions:

   ```yaml
   - uses: actions/setup-node@v4
     with:
       node-version: '22'
       registry-url: https://npm.pkg.github.com/
       scope: '@yleisradio'
   - run: npm ci
     env:
       NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
   ```

## Choose your starting point

| You're building | Start here |
| --- | --- |
| A React web app | [Get started with yds-components-react 3.0](../using-yds/development/get-started-with-v3.md) |
| A web app without React (Vue, Svelte, plain HTML) | [Without React](../using-yds/development/get-started-with-v3.md#without-react) |
| Your own styles with YDS tokens | [Using tokens](../design-tokens/index.md#using-tokens) |
| Icons only | [Icons and Logos](../icons-and-logos/index.md#installation) |
| A React Native app | [React Native](#react-native) |
| A native iOS or Android app | [Native apps](#native-apps) |
| Charts and infographics | [Infographics](#infographics) |

Every web setup loads the Yle Next font: see [Load Yle Next](../using-yds/development/get-started-with-v3.md#2-load-yle-next).

## React Native

```bash
npm install @yleisradio/yds-core @yleisradio/yds-components-react-native @yleisradio/yds-icons-react-native react-native-svg
```

Wrap the component tree in the theme provider:

```tsx
import { YdsThemeProvider, Tag } from '@yleisradio/yds-components-react-native';

<YdsThemeProvider theme="light">
  <Tag>Hello world</Tag>
</YdsThemeProvider>;
```

Components available for React Native are tagged **React Native** on the [Components](../components/index.md) page.

## Native apps

YDS doesn't provide native iOS or Android components, but native apps can use its assets:

- **Icons:** archives of basic and illustrative icons, SVG for iOS and VectorDrawable for Android. See [CDN](./overview.md#cdn).
- **Colours:** Android colour resources (`colors.xml`, `theme-dark.xml`) are included in `@yleisradio/yds-core` under `tokens/build/android/`.

## Infographics

```bash
npm install @yleisradio/yds-core @yleisradio/yds-infographic-components-react @yleisradio/yds-infographic-icons-react
```

`@yleisradio/yds-core` exports the infographic colour themes as `infographicLight`, `infographicDark` and `infographicDefault` (CSS custom properties).

## Contributing code

Local setup, commit conventions and the release flow are in the repository [README](https://github.com/Yleisradio/yle-design-system#development). Before opening a pull request for anything larger than a fix, see [Support and contributing](./support.md).

# Introduction

Yle Design System (YDS) is the shared foundation for Yle's digital services. Designers and developers get the same building blocks — design tokens, components, icons and guidelines — so services stay consistent, accessible and on-brand without every team solving the same problems again.

## Why YDS exists

- **A shared language.** Designers and developers use the same names for the same things, in Figma and in code.
- **Build once, use everywhere.** Common UI solutions are built and tested once and reused across services, so teams can focus on what is new.
- **Accessibility and brand built in.** Components and tokens carry Yle's visual identity and accessibility requirements, so services don't have to reinvent them.

## What YDS covers

- **Design tokens:** colours and themes, typography, spacing, border radius, borders, shadows and transitions.
- **Components:** accessible, generic UI building blocks such as buttons, form controls, notifications, dialogs and navigation, for React and React Native, with matching Figma components.
- **Icons and logos:** basic icons, illustrative icons, Yle logos and graphical assets such as age-rating badges.
- **Infographics:** colour themes, icons and chart components for data visualisation.
- **Guidelines:** usage, content and accessibility guidance for each component, plus design principles such as motion.

## What YDS doesn't cover

- **Service-specific components and layouts.** YDS components are deliberately generic building blocks. Services compose them into their own views, and components that only one service needs stay in that service.
- **Native iOS and Android components.** Native apps can use YDS icons and colour tokens, but YDS doesn't provide native UI components.
- **Brand guidelines beyond digital UI.** Marketing and other non-digital touchpoints follow Yle's brand guidelines.

## Who it's for

- **Designers** work with the Figma libraries or prototype with AI agents. See [For designers](./for-designers.md).
- **Developers** use the npm packages. See [For developers](./for-developers.md).
- **Everyone building Yle's services**, product owners and editors included, can use these docs to see what is available and how it is meant to be used.
- **AI agents** read the documentation as plain Markdown and install the same packages. See [For AI agents](./for-ai-agents.md).

## Accessibility

YDS aims to meet [WCAG 2.2](https://www.w3.org/TR/WCAG22/) level AA in every component and token pairing. Components handle keyboard interaction, focus, semantics and colour contrast. Services remain responsible for their content, page structure and how components are combined. Each component page has an Accessibility section that lists what the component provides.

## How YDS is maintained

Yle's design system team maintains YDS. Designers and developers from Yle's services contribute to it, and new components start from needs in the services. See [Support and contributing](./support.md) for how to ask, report and propose.

## Next steps

- [Overview](./overview.md): what the system consists of and where to find each part.
- [For designers](./for-designers.md)
- [For developers](./for-developers.md)
- [For AI agents](./for-ai-agents.md)
- [Components](../components/index.md)

# Overview

YDS is made of a few parts that share the same tokens and names. Design tokens start as Figma variables and are built into code formats in `@yleisradio/yds-core`, so a colour or spacing value means the same thing in a design file and in an application.

| Part | Used for | Where |
| --- | --- | --- |
| Documentation | Guidelines, usage, API reference | This site |
| Figma libraries | Designing with components, tokens and icons | [YDS Foundation](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation) and others, see below |
| npm packages | Building with tokens, components, icons and fonts | Yle's GitHub Packages registry, see below |
| Storybook | Trying out components and their props | [Storybook](https://ds-storybook.test.yle.fi/) |
| CDN | Fonts and native icon files without installing packages | `design-system.cdn.yle.fi`, see below |
| Source code | Packages, docs and Storybook | [GitHub](https://github.com/Yleisradio/yle-design-system) |

## What each part contains

```mermaid
block-beta
  columns 4

  hFigma["Figma libraries"] hRepo["YDS repository"]:2 hDelivery["Delivery"]

  foundation["<b>YDS Foundation</b><br/>tokens, themes,<br/>text styles, components"]
  core["<b>yds-core</b><br/>tokens and themes<br/><span class='yds-tag'>all</span>"]
  themeCustom["<b>yds-theme-custom</b><br/>custom themes<br/><span class='yds-tag'>all</span>"]
  storybook["<b>Storybook</b><br/>interactive<br/>component examples"]

  globalColors["<b>YDS Global Colors</b><br/>global palettes,<br/>colour swatches"]
  icons["<b>yds-icons</b><br/>UI icons<br/><span class='yds-tag'>all</span> <span class='yds-tag'>react</span> <span class='yds-tag'>react native</span>"]
  infographicIcons["<b>yds-infographic-icons</b><br/>weather icons<br/><span class='yds-tag'>all</span> <span class='yds-tag'>react</span> <span class='yds-tag'>react native</span>"]
  npm["<b>npm packages</b><br/>GitHub Packages<br/>registry"]

  infographics["<b>YDS Infographics</b><br/>colour themes, weather<br/>symbols, chart examples"]
  componentsReact["<b>yds-components</b><br/>UI components<br/><span class='yds-tag'>react</span>"]
  componentsNative["<b>yds-components</b><br/>UI components<br/><span class='yds-tag'>react native</span>"]
  cdn["<b>CDN</b><br/>fonts and icons<br/>for native apps"]

  iconsLogos["<b>YDS Icons and Logos</b><br/>icons, illustrative icons,<br/>logos, graphical assets"]
  infographicComponents["<b>yds-infographic-<br/>components</b><br/>charts <span class='yds-tag'>react</span>"]
  fonts["<b>yds-fonts</b><br/>Yle Next font files<br/><span class='yds-tag'>all</span>"]
  site["<b>Docs site</b><br/>Markdown and<br/>llms.txt for agents"]

  space
  docs["<b>Documentation</b><br/>guidelines, usage, API reference"]:2
  space

  classDef header fill:none,stroke:none,font-weight:bold
  classDef prerelease stroke-dasharray:5 4
  class hFigma,hRepo,hDelivery header
  class themeCustom,componentsNative,infographicComponents prerelease
```

- **Tags** show the platform packages: <span className="yds-tag">all</span> works anywhere (CSS, JavaScript, SVG); <span className="yds-tag">react</span> and <span className="yds-tag">react native</span> are separate packages with those suffixes. For example, `yds-components` <span className="yds-tag">react</span> is `@yleisradio/yds-components-react`.
- **Dotted boxes** are 0.x packages: usable, but their APIs may still change between minor versions.
- **In the diagram below**, `yds-core` stands for the token and theme packages, `yds-icons` for the icon packages and `yds-components` for the component packages.

## How the parts connect

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 14, "rankSpacing": 40}}}%%
flowchart LR
  hFigma[Figma libraries]:::header ~~~ hRepo[YDS repository]:::header ~~~ hDelivery[Delivery]:::header ~~~ hUse[Using YDS]:::header

  foundation[YDS Foundation]
  globalColors[YDS Global Colors]
  infographics[YDS Infographics]
  iconsLogos[YDS Icons and Logos]

  components[yds-components]
  tokens[yds-core]
  icons[yds-icons]
  docsSource[Documentation]

  storybook[Storybook]
  npm[npm packages]
  cdn[CDN]
  site[Docs site and llms.txt]

  services[Yle services]
  prototypes[AI prototypes]

  foundation --> components
  foundation & globalColors & infographics --> tokens
  infographics & iconsLogos --> icons
  iconsLogos ~~~ docsSource
  components --> storybook & npm
  tokens & icons --> npm & cdn
  docsSource --> site
  npm --> services & prototypes
  cdn --> services
  site -.-> services & prototypes

  classDef header fill:none,stroke:none,font-weight:bold
```

- **Tokens** are defined as Figma variables and built into CSS, JavaScript, SCSS, Less and Android formats in `@yleisradio/yds-core`.
- **Icons** are drawn in Figma, exported as SVG and generated into the icon packages for web, React and React Native.
- **Components** are built on the tokens and icons, shown in Storybook and released as npm packages together with the token and icon packages.
- **Services and prototypes** install the packages and follow the documentation. What they learn comes back as feedback and contributions to the Figma libraries and the code.

## Figma libraries

| Library | Contents |
| --- | --- |
| [YDS Foundation](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation) | Design tokens as Figma variables, light and dark themes, text styles and shared components |
| [YDS Global Colors](https://www.figma.com/design/3ARTAZ2XrJHPq2g8iSBORW/YDS-Global-Colors) | Global palettes and colour swatches |
| [YDS Icons and Logos](https://www.figma.com/design/lSboxfILj3Thr1o145POJv/YDS-Icons-and-Logos) | Basic icons, illustrative icons, logos and graphical assets |
| [YDS Infographics](https://www.figma.com/design/ttv0a97s8ViuxBHtRyn3n2/YDS-Infographics) | Infographic colour themes, weather symbols and examples of simple infographic components |

How to enable them: [Using YDS in Figma](./for-designers.md#using-yds-in-figma).

## Packages

All packages are published under the `@yleisradio` scope to Yle's GitHub Packages registry. Installing them requires access: see [For developers](./for-developers.md#get-access-to-the-packages).

| Package | Contents | Platform |
| --- | --- | --- |
| `@yleisradio/yds-core` | Design tokens and themes as CSS custom properties, JS/TS constants, SCSS, Less and Android colour resources | All |
| `@yleisradio/yds-fonts` | Yle Next font files | All |
| `@yleisradio/yds-components-react` | React components | Web |
| `@yleisradio/yds-components-react-native` | React Native components | Mobile |
| `@yleisradio/yds-icons` | Icon SVG files and icon name types | All |
| `@yleisradio/yds-icons-react` | Icons as React components | Web |
| `@yleisradio/yds-icons-react-native` | Icons as React Native components | Mobile |
| `@yleisradio/yds-theme-custom` | Generating accessible custom themes from a colour combination | Web |
| `@yleisradio/yds-infographic-components-react` | Column, line, area and donut charts, legends and accessible data tables | Web |
| `@yleisradio/yds-infographic-icons` | Infographic icon SVG files, such as weather symbols | All |
| `@yleisradio/yds-infographic-icons-react` | Infographic icons as React components | Web |
| `@yleisradio/yds-infographic-icons-react-native` | Infographic icons as React Native components | Mobile |

Release notes for every package are in [GitHub releases](https://github.com/Yleisradio/yle-design-system/releases).

## Storybook

[Storybook](https://ds-storybook.test.yle.fi/) shows every React component in isolation, with controls for trying out props and states. Component pages on this site link to the matching story.

React Native components have their own Storybook in the [YDS repository](https://github.com/Yleisradio/yle-design-system). It isn't published on the web: run it locally on an iOS or Android simulator with `yarn storybook:native`. See the repository README for setup.

## CDN

`design-system.cdn.yle.fi` serves static files that don't need a package install:

- **Fonts:** [`fonts.css`](https://design-system.cdn.yle.fi/fonts/fonts.css) loads Yle Next with `@font-face` rules. See [Load Yle Next](../using-yds/development/get-started-with-v3.md#2-load-yle-next).
- **iOS icons (SVG):** [basic icons](https://design-system.cdn.yle.fi/icons/ios/icons.tar.gz), [illustrative icons](https://design-system.cdn.yle.fi/icons/ios/illustrative-icons.tar.gz)
- **Android icons (VectorDrawable):** [basic icons](https://design-system.cdn.yle.fi/icons/android/icons.tar.gz), [illustrative icons](https://design-system.cdn.yle.fi/icons/android/illustrative-icons.tar.gz)

# Support and contributing

| I want to… | Where |
| --- | --- |
| Ask a question or get help | [#design-system](https://yle.slack.com/archives/C01KDJ7JX5Y) on Slack |
| Discuss about technical issue | [#ds-kehitys](https://yle.slack.com/archives/C02G2TP79HB) on Slack |
| Report a bug | [New issue](https://github.com/Yleisradio/yle-design-system/issues/new/choose) → **Bug report** |
| Suggest a change to an existing component, token or icon | [New issue](https://github.com/Yleisradio/yle-design-system/issues/new/choose) → **Change request** |
| Propose a new component or feature | [New issue](https://github.com/Yleisradio/yle-design-system/issues/new/choose) → **New feature** |
| Explore an early design idea | [New issue](https://github.com/Yleisradio/yle-design-system/issues/new/choose) → **Concept design** |
| See what is being worked on | [Project board](https://github.com/orgs/Yleisradio/projects/32) |
| See what has changed | [GitHub releases](https://github.com/Yleisradio/yle-design-system/releases) |
| Fix or improve a docs page | **Edit this page** link at the top of the page |

Release announcements are also posted on #design-system.

## Before you ask

Search these docs, [Storybook](https://ds-storybook.test.yle.fi/) and [existing issues](https://github.com/Yleisradio/yle-design-system/issues?q=is%3Aissue), open and closed. Someone may have asked already.

## Reporting a bug

A good bug report includes:

- the package and its version
- where it happens: browser, device, React or React Native version
- steps to reproduce, with a code sample or a link if possible
- what you expected and what happened instead.

Don't put security-sensitive details in an issue. Contact the team on Slack and they'll point you to a private channel.

## Proposing a change or a new component

Open an issue before you start designing or building. The team checks that the proposal fits the system:

- Does more than one service need it, or could it be generalised so that they would?
- Could an existing component be extended instead?
- Is it accessible and built on existing design tokens?
- Does it work in both light and dark themes?

Once the proposal is agreed, the design is done in the YDS Figma libraries and the implementation as a pull request.

## Contributing code

Pull requests are welcome. Before opening one:

- Set up the repository with the [README](https://github.com/Yleisradio/yle-design-system#development) instructions.
- Write commit messages as [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/).
- Add a [changeset](https://github.com/Yleisradio/yle-design-system/blob/main/.changeset/README.md) for every change that should release a new package version.
- Document new components with the [docs page template](https://github.com/Yleisradio/yle-design-system/blob/main/docs/template.mdx).

More detail: [CONTRIBUTING.md](https://github.com/Yleisradio/yle-design-system/blob/main/CONTRIBUTING.md).

---

# Components

# Accordion

An Accordion lets users hide and reveal sections of related content. It helps reduce visual clutter by showing only section titles by default, while allowing users to expand the content they need.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?m=auto&node-id=285-1938&t=lI9imRC4H4TmzLE4-1)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-accordion--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Accordion/Accordion.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/Accordion/)*

<details open>
<summary>Code example</summary>

```tsx
import { Accordion, AccordionItem } from '@yleisradio/yds-components-react';

<Accordion>
  <AccordionItem title="First Item">
    Content for first item
  </AccordionItem>
  <AccordionItem title="Second Item">
    Content for second item
  </AccordionItem>
</Accordion>
```
</details>

## Why to use

Accordion helps users navigate large amounts of content by grouping related information into collapsible sections. It reduces visual clutter and cognitive load by showing only section titles by default, while still allowing users to access detailed content when needed. Accordions are especially useful when most users need only part of the available information, such as in help content, rules, or frequently asked questions.

## When to use

Use an Accordion when content can be divided into independent, optional sections and it is not essential for all content to be visible at once. Accordions work well when users benefit from scanning headings first and choosing what to expand.

> **Do**
> - Use an Accordion for supplementary or secondary content.
> - Use when sections can be read independently, in any order.
> - Use for FAQs, instructions, rules, help content, and settings.
> - Use when reducing vertical scrolling improves clarity and scannability.

> **Don't**
> - Don’t hide critical or mandatory information inside an Accordion.
> - Don’t use Accordion for navigation between views — use [NavigationTabs](../NavigationTabs/NavigationTabs.md) or [SectionTabs](../SectionTabs/SectionTabs.md) instead.
> - Don’t use Accordion when content requires focused attention or user action — use a [Dialog](../Dialog/Dialog.md) ([Modal](../Modal/Modal.md) or [BottomSheet](../BottomSheet/BottomSheet.md)) instead.
> - Don’t use Accordion when there is only one short expandable section — use read more buttton/show more button instead.
> - Don’t nest Accordions inside other Accordions.

## Content Guidelines

Accordion titles are the primary decision point for users. Users decide whether to expand a section based on the title alone, so titles must clearly describe what the content contains.

> **Do**
> - Use short, descriptive titles that summarize the content (e.g. “Säännöt ja pistejako”, “Palkinnot”, “Mikä Tietäjä on?”).
> - Phrase titles in a way that matches the content type — questions work well for FAQs.
> - Keep wording parallel across items to support scanning.
> - Place the most commonly needed or most important item first.

> **Don't**
> - Don’t use vague titles like “Lisätietoja” or “Muut”.
> - Don’t use long sentences or explanatory text as titles.
> - Don’t repeat the same wording across multiple items.
> - Don’t rely on the expanded content to explain what the section is about.

## Anatomy

![Accordion anatomy](../../img/accordion-anatomy.svg)

1. **Icon** – Visual indicator that shows whether the section is expanded or collapsed.
2. **Title** – The clickable header that summarizes the content of the section.
3. **Group container** – Wraps the title and content and manages spacing, alignment, borders, and wrapping.
4. **Closed item** – The closed state of the accordion item.
5. **Open item** – The open state of the accordion item.
6. **Content** – The section that contains the detailed content, revealed when the item is expanded.
7. **Border** – Optional visual separator between sections.

## Key Accordion Props

Use these props to configure the Accordion component.

### children

The AccordionItem components to display.

| Type              | Example                                                                                                                                                                                               | Description                    |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| `React.ReactNode` | <div style={{ width: '300px' }}><Accordion><AccordionItem title="Item 1"><span>Content 1</span></AccordionItem><AccordionItem title="Item 2"><span>Content 2</span></AccordionItem></Accordion></div> | Child AccordionItem components |

<details>
<summary>Code example</summary>

```tsx
  <Accordion>
    <AccordionItem title="Item 1">Content 1</AccordionItem>
    <AccordionItem title="Item 2">Content 2</AccordionItem>
  </Accordion>
  ```
</details>

## Key AccordionItem Props

Use these props to configure the AccordionItem component.

### title

The title text or content displayed in the accordion header.

| Type              | Example                                                                                                          | Description                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `React.ReactNode` | <div style={{ width: '300px' }}><AccordionItem title="Section Title" ><span>Content</span></AccordionItem></div> | Title content for the accordion item |

<details>
<summary>Code example</summary>

```tsx
  <AccordionItem title="Section Title">Content</AccordionItem>
  <AccordionItem title={<strong>Bold Title</strong>}>Content</AccordionItem>
  ```
</details>

### variant

Visual style variant of the accordion item.

| Value      | Example                                                                                                                   | Description                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `default`  | <div style={{ width: '300px' }}><AccordionItem variant="default" title="Item"><span>Content</span></AccordionItem></div>  | Default style with border       |
| `noBorder` | <div style={{ width: '300px' }}><AccordionItem variant="noBorder" title="Item"><span>Content</span></AccordionItem></div> | Style without border or padding |

<details>
<summary>Code example</summary>

```tsx
  <AccordionItem variant="default" title="With Border">
    Content
  </AccordionItem>
  <AccordionItem variant="noBorder" title="Without Border">
    Content
  </AccordionItem>
  ```
</details>

### size

Size of the accordion item.

| Value | Example                                                                                                          | Description         |
| ----- | ---------------------------------------------------------------------------------------------------------------- | ------------------- |
| `sm`  | <div style={{ width: '300px' }}><AccordionItem size="sm" title="Item"><span>Content</span></AccordionItem></div> | Small size          |
| `md`  | <div style={{ width: '300px' }}><AccordionItem size="md" title="Item"><span>Content</span></AccordionItem></div> | Default medium size |
| `lg`  | <div style={{ width: '300px' }}><AccordionItem size="lg" title="Item"><span>Content</span></AccordionItem></div> | Large size          |

<details>
<summary>Code example</summary>

```tsx
  <AccordionItem size="sm" title="Small">
    Content
  </AccordionItem>
  <AccordionItem size="md" title="Medium">
    Content
  </AccordionItem>
  <AccordionItem size="lg" title="Large">
    Content
  </AccordionItem>
  ```
</details>

### defaultOpen

Whether the accordion item should be open by default.

| Type      | Example                                                                                                            | Description                      |
| --------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
| `boolean` | <div style={{ width: '300px' }}><AccordionItem defaultOpen title="Item"><span>Content</span></AccordionItem></div> | Opens the item on initial render |

<details>
<summary>Code example</summary>

```tsx
  <AccordionItem defaultOpen title="Open by Default">
    Content
  </AccordionItem>
  <AccordionItem defaultOpen={false} title="Closed by Default">
    Content
  </AccordionItem>
  ```
</details>

### isDisabled

Whether the accordion item is disabled.

| Type      | Example                                                                                                           | Description                                  |
| --------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `boolean` | <div style={{ width: '300px' }}><AccordionItem isDisabled title="Item"><span>Content</span></AccordionItem></div> | Disables interaction with the accordion item |

<details>
<summary>Code example</summary>

```tsx
  <AccordionItem isDisabled title="Disabled Item">
    Content
  </AccordionItem>
  ```
</details>

### removePadding

Removes padding from the accordion content.

| Type      | Example                                                                                                              | Description                       |
| --------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `boolean` | <div style={{ width: '300px' }}><AccordionItem removePadding title="Item"><span>Content</span></AccordionItem></div> | Removes padding from content area |

<details>
<summary>Code example</summary>

```tsx
  <AccordionItem removePadding title="No Padding">
    Content
  </AccordionItem>
  ```
</details>

### contentProps

Additional props for the content container.

| Type                                                              | Example                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Description                              |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `{ padding?: 'default' \| 'horizontal' \| 'vertical' \| 'none' }` | <div style={{ width: '300px' }}><Accordion><AccordionItem title="Padding: default" contentProps={{padding: 'default'}}><span>Content</span></AccordionItem><AccordionItem contentProps={{ padding: 'horizontal' }} title="Padding: horizontal"><span>Content</span></AccordionItem><AccordionItem contentProps={{ padding: 'vertical' }} title="Padding: vertical"><span>Content 3</span></AccordionItem><AccordionItem contentProps={{ padding: 'none' }} title="Padding: none"><span>Content 4</span></AccordionItem></Accordion></div> | Custom padding configuration for content |

<details>
<summary>Code example</summary>

```tsx
  <AccordionItem contentProps={{ padding: 'default' }} title="Item">
    Content
  </AccordionItem>
  <AccordionItem contentProps={{ padding: 'horizontal' }} title="Item">
    Content
  </AccordionItem>
  <AccordionItem contentProps={{ padding: 'vertical' }} title="Item">
    Content
  </AccordionItem>
  <AccordionItem contentProps={{ padding: 'none' }} title="Item">
    Content
  </AccordionItem>
  ```
</details>

## Behavior

- Each accordion item expands and collapses independently.
- Multiple items can be open at the same time.
- Clicking the title toggles the expanded state.
- The icon (chevron) rotates or switches to reflect expanded vs collapsed state.

## Accessibility

- Provide a unique id on each AccordionItem for proper labeling and control linkage.
- Accordion headers must be focusable and keyboard-activatable so users can expand and collapse items with the keyboard (for example, using Enter or Space).<br />
  ([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard))
- Ensure both the header and the panel have an accessible name by using clear, descriptive titles and avoiding empty panels.<br />
  ([WCAG 2.4.6 — Headings and Labels](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels))

## Implementation examples

### FAQ

Use an Accordion for frequently asked questions so users can expand only the answers they need.

*[Live preview](https://design-system.yle.fi/docs/components/Accordion/)*

<details open>
<summary>Code example</summary>

```tsx
  <Accordion>
    <AccordionItem title="Miten voin peruuttaa tilauksen?">
      Tilauksen voit peruuttaa Asetukset-sivulta tai ottamalla yhteyttä asiakaspalveluun.
    </AccordionItem>
    <AccordionItem title="Milloin tilaus toimitetaan?">
      Toimitus tapahtuu 1–3 arkipäivän kuluessa tilauksesta.
    </AccordionItem>
    <AccordionItem title="Voinko vaihtaa maksutapaani?">
      Kyllä, maksutavan voit vaihtaa tilin asetuksista milloin tahansa.
    </AccordionItem>
  </Accordion>
  ```
</details>

### One item open by default

Use `defaultOpen` to show one section expanded on first load so users see sample content without clicking.

*[Live preview](https://design-system.yle.fi/docs/components/Accordion/)*

<details open>
<summary>Code example</summary>

```tsx
  <Accordion>
    <AccordionItem title="First Item">Content for first item</AccordionItem>
    <AccordionItem title="Second Item" defaultOpen>
      Content for second item (open by default)
    </AccordionItem>
    <AccordionItem title="Third Item">Content for third item</AccordionItem>
  </Accordion>
  ```
</details>

## API Reference

### Accordion Props

The Accordion component accepts all standard HTML `<div>` attributes in addition to the following props:

| Prop       | Type              | Required | Default | Description                         |
| ---------- | ----------------- | -------- | ------- | ----------------------------------- |
| `children` | `React.ReactNode` | No       | —       | AccordionItem components to display |

### AccordionItem Props

The AccordionItem component accepts all standard HTML `<span>` attributes in addition to the following props:

| Prop            | Type                                                              | Required | Default     | Description                            |
| --------------- | ----------------------------------------------------------------- | -------- | ----------- | -------------------------------------- |
| `title`         | `React.ReactNode`                                                 | Yes      | —           | Title content for the accordion item   |
| `id`            | `string`                                                          | No       | —           | Unique identifier for accessibility    |
| `variant`       | `'default' \| 'noBorder'`                                         | No       | `'default'` | Visual style variant                   |
| `size`          | `'sm' \| 'md' \| 'lg'`                                            | No       | `'md'`      | Size of the accordion item             |
| `defaultOpen`   | `boolean`                                                         | No       | `false`     | Whether the item is open by default    |
| `isDisabled`    | `boolean`                                                         | No       | `false`     | Whether the item is disabled           |
| `removePadding` | `boolean`                                                         | No       | —           | Removes padding from content area      |
| `contentProps`  | `{ padding?: 'default' \| 'horizontal' \| 'vertical' \| 'none' }` | No       | `{}`        | Additional props for content container |
| `children`      | `React.ReactNode`                                                 | No       | —           | Content displayed when expanded        |

### Type Definitions

```tsx
export type AccordionSize = 'sm' | 'md' | 'lg';
export type Padding = 'default' | 'horizontal' | 'vertical' | 'none';

export interface AccordionContentDSProps {
  padding?: Padding;
}

export interface AccordionItemDSProps {
  id?: string;
  variant?: 'default' | 'noBorder';
  title: React.ReactNode;
  size?: AccordionSize;
  defaultOpen?: boolean;
  isDisabled?: boolean;
  contentProps?: AccordionContentDSProps;
  children?: React.ReactNode;
  removePadding?: boolean;
}

export interface AccordionDSProps {
  children?: React.ReactNode;
}

export type AccordionProps = HTMLAttributes<HTMLDivElement> & AccordionDSProps;
export type AccordionItemProps = HTMLAttributes<HTMLSpanElement> & AccordionItemDSProps;
```

## Related Components

- [Button](../Button/Button.md) – Can be used inside accordion content
- [SectionTabs](../SectionTabs/SectionTabs.md) – Alternative component for organizing content
- [NavigationTabs](../NavigationTabs/NavigationTabs.md) – Alternative component for navigation between views
- [Dialog](../Dialog/Dialog.md) – Alternative component for showing content in a modal
- [BottomSheet](../BottomSheet/BottomSheet.md) – Alternative component for showing content in a bottom sheet

import {
  Link2,
  Mail,
  Whatsapp,
  Facebook,
  TwitterX,
  Linkedin,
  Share,
} from '@yleisradio/yds-icons-react';
import { Resources } from 'yds-documentation/src/components/Resources/Resources';
import { ComponentPreview } from 'yds-documentation/src/components/ComponentPreview/ComponentPreview';

# ActionMenu

ActionMenu is a button that opens a dropdown list of actions. It groups multiple related actions into a compact control without changing the component’s state when an item is selected.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=8809-10634&p=f&t=U4uSG0M5o85iz0VX-0)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-actionmenu--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/ActionMenu/ActionMenu.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/ActionMenu/)*

<details open>
<summary>Code example</summary>

```tsx
import { ActionMenu, MenuItem, MenuSeparator } from '@yleisradio/yds-components-react';

<ActionMenu text="Actions" id="action-menu-1" menuId="menu-1">
  <MenuItem onSelect={() => {}}>Option 1</MenuItem>
  <MenuItem onSelect={() => {}}>Option 2</MenuItem>
  <MenuSeparator />
  <MenuItem onSelect={() => {}}>Option 3</MenuItem>
</ActionMenu>
```
</details>

## Why to use

ActionMenu provides a clear and space-efficient way to expose multiple related actions from a single entry point. Instead of showing several buttons side by side, ActionMenu keeps the interface uncluttered while still making all actions easily accessible.

It is built on top of Menu, ensuring consistent positioning, keyboard navigation, and accessibility across products while supporting typical action-based use cases such as sharing, editing, or managing content.

## When to use

Use ActionMenu when the user needs to trigger one of several related actions that do not affect the component’s state.

> **Do**
> - Use when multiple related actions are available from the same context.
> - Use for secondary or contextual actions such as sharing, editing, or managing content.
> - Use when space is limited and showing all actions at once would clutter the UI.

> **Don't**
> - Don’t use for selecting values or changing component state (use [DropdownMenu](../DropdownMenu/DropdownMenu.md) instead).
> - Don’t use for navigation between views or pages.
> - Don’t use for a single action (use a [Button](../Button/Button.md) instead).

## Content Guidelines

ActionMenu items represent actions, not values.

> **Do**
> - Use verbs for menu items (e.g. “Jaa”, “Muokkaa”, “Poista”).
> - Keep labels concise and action-oriented.
> - Group related actions using separators when necessary.

> **Don't**
> - Don’t use nouns or descriptive values as menu items.
> - Don’t use vague labels like “OK” or “Kyllä”.
> - Don’t mix actions with selection-type options in the same menu.

## Anatomy

![ActionMenu anatomy](../../img/actionmenu-anatomy.svg)

1. **ActionMenu button** – The trigger that opens the list of actions.
2. **Label** – Text describing the category of actions (e.g. “Actions”, “Share”).
3. **Chevron icon** – Indicates that the button opens a dropdown.
4. **Menu surface** – The floating container holding the action items.
5. **MenuItem (action)** – A single actionable option inside the menu.
6. **MenuItem icon (optional)** – An optional leading icon inside a `MenuItem`
7. **MenuSeparator (optional)** – Groups related actions.

## Key ActionMenu Props

Use these props to configure the ActionMenu component.

### text

The text displayed on the action menu button.

| Type     | Example                                                                                                             | Description       |
| -------- | ------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `string` | <ActionMenu text="Actions" id="menu-1" menuId="menu-1"><MenuItem onSelect={() => {}}>Option</MenuItem></ActionMenu> | Button label text |

<details>
<summary>Code example</summary>

```tsx
  <ActionMenu text="Actions" id="menu-1" menuId="menu-1">
    <MenuItem onSelect={() => {}}>Option</MenuItem>
  </ActionMenu>
  ```
</details>

### children

Menu items to display in the dropdown menu.

| Type              | Example                                                                                       | Description                    |
| ----------------- | --------------------------------------------------------------------------------------------- | ------------------------------ |
| `React.ReactNode` | <ActionMenu text="Actions" id="menu-1" menuId="menu-1"><MenuItem>Item</MenuItem></ActionMenu> | MenuItem components to display |

<details>
<summary>Code example</summary>

```tsx
  <ActionMenu text="Actions" id="menu-1" menuId="menu-1">
    <MenuItem onSelect={() => {}}>Option 1</MenuItem>
    <MenuItem onSelect={() => {}}>Option 2</MenuItem>
  </ActionMenu>
  ```
</details>

### dropdown

Whether to show a dropdown chevron icon.

| Value   | Example                                                                                                                              | Description            |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
| `true`  | <ActionMenu dropdown={true} text="Actions" id="menu-1" menuId="menu-1"><MenuItem onSelect={() => {}}>Option</MenuItem></ActionMenu>  | Shows the chevron icon |
| `false` | <ActionMenu dropdown={false} text="Actions" id="menu-1" menuId="menu-1"><MenuItem onSelect={() => {}}>Option</MenuItem></ActionMenu> | Hides the chevron icon |

<details>
<summary>Code example</summary>

```tsx
  <ActionMenu dropdown={true} text="Actions" id="menu-1" menuId="menu-1">
    <MenuItem onSelect={() => {}}>Option</MenuItem>
  </ActionMenu>
  <ActionMenu dropdown={false} text="Actions" id="menu-2" menuId="menu-2">
    <MenuItem onSelect={() => {}}>Option</MenuItem>
  </ActionMenu>
  ```
</details>

### openMenuOnClick

Whether clicking the button opens the menu.

| Type      | Example                                                                           | Description                      |
| --------- | --------------------------------------------------------------------------------- | -------------------------------- |
| `boolean` | <ActionMenu openMenuOnClick={false} text="Actions" id="menu-1" menuId="menu-1" /> | Controls if click opens the menu |

<details>
<summary>Code example</summary>

```tsx
  <ActionMenu openMenuOnClick={true} text="Actions" id="menu-1" menuId="menu-1">
    <MenuItem onSelect={() => {}}>Option</MenuItem>
  </ActionMenu>
  ```
</details>

### menuSize

Size of the menu items.

| Value | Example                                                                                                                           | Description               |
| ----- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `sm`  | <ActionMenu menuSize="sm" text="Actions" id="menu-1" menuId="menu-1"><MenuItem onSelect={() => {}}>Option</MenuItem></ActionMenu> | Small menu items          |
| `md`  | <ActionMenu menuSize="md" text="Actions" id="menu-1" menuId="menu-1"><MenuItem onSelect={() => {}}>Option</MenuItem></ActionMenu> | Default medium menu items |

<details>
<summary>Code example</summary>

```tsx
  <ActionMenu menuSize="sm" text="Actions" id="menu-1" menuId="menu-1">
    <MenuItem onSelect={() => {}}>Option</MenuItem>
  </ActionMenu>
  <ActionMenu menuSize="md" text="Actions" id="menu-2" menuId="menu-2">
    <MenuItem onSelect={() => {}}>Option</MenuItem>
  </ActionMenu>
  ```
</details>

### alignMenu

Horizontal alignment of the menu relative to the button.

| Value   | Example                                                                                                                               | Description                        |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `left`  | <ActionMenu alignMenu="left" text="Actions" id="menu-1" menuId="menu-1"><MenuItem onSelect={() => {}}>Option</MenuItem></ActionMenu>  | Aligns menu to the left            |
| `right` | <ActionMenu alignMenu="right" text="Actions" id="menu-1" menuId="menu-1"><MenuItem onSelect={() => {}}>Option</MenuItem></ActionMenu> | Aligns menu to the right (default) |

<details>
<summary>Code example</summary>

```tsx
  <ActionMenu alignMenu="left" text="Actions" id="menu-1" menuId="menu-1">
    <MenuItem onSelect={() => {}}>Option</MenuItem>
  </ActionMenu>
  <ActionMenu alignMenu="right" text="Actions" id="menu-2" menuId="menu-2">
    <MenuItem onSelect={() => {}}>Option</MenuItem>
  </ActionMenu>
  ```
</details>

### position

Preferred direction in which the menu opens relative to the trigger button. The menu automatically adjusts if it would be clipped by the viewport.

| Value    | Example                                                                                                                                | Description                        |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `bottom` | <ActionMenu position="bottom" text="Actions" id="menu-1" menuId="menu-1"><MenuItem onSelect={() => {}}>Option</MenuItem></ActionMenu> | Opens below the button (default)   |
| `top`    | <ActionMenu position="top" text="Actions" id="menu-1" menuId="menu-1"><MenuItem onSelect={() => {}}>Option</MenuItem></ActionMenu>    | Opens above the button             |
| `left`   | <ActionMenu position="left" text="Actions" id="menu-1" menuId="menu-1"><MenuItem onSelect={() => {}}>Option</MenuItem></ActionMenu>   | Opens to the left of the button    |
| `right`  | <ActionMenu position="right" text="Actions" id="menu-1" menuId="menu-1"><MenuItem onSelect={() => {}}>Option</MenuItem></ActionMenu>  | Opens to the right of the button   |

<details>
<summary>Code example</summary>

```tsx
  <ActionMenu position="bottom" text="Actions" id="menu-1" menuId="menu-1">
    <MenuItem onSelect={() => {}}>Option</MenuItem>
  </ActionMenu>
  <ActionMenu position="top" text="Actions" id="menu-2" menuId="menu-2">
    <MenuItem onSelect={() => {}}>Option</MenuItem>
  </ActionMenu>
  <ActionMenu position="left" text="Actions" id="menu-3" menuId="menu-3">
    <MenuItem onSelect={() => {}}>Option</MenuItem>
  </ActionMenu>
  <ActionMenu position="right" text="Actions" id="menu-4" menuId="menu-4">
    <MenuItem onSelect={() => {}}>Option</MenuItem>
  </ActionMenu>
  ```
</details>

## Behavior

- Selecting an item triggers the associated action immediately.
- The ActionMenu label does not change based on selection.
- The menu opens from the trigger and closes after selection, outside click, or cancellation.
- The `position` prop controls the preferred direction in which the menu opens: `'bottom'` (default), `'top'`, `'left'`, or `'right'`. The menu automatically adjusts if it would be clipped by the viewport.
- Keyboard interaction:
  - Arrow keys navigate between actions.
  - Enter activates the focused action.
  - Escape closes the menu.

## Accessibility

- Ensure full keyboard support for all interactions.<br />
  (WCAG 2.1.1 — [Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html))
- Menu items have clear visual focus indicators.<br />
  ([WCAG 2.4.7 — Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html))
- Each menu item exposes a clear, descriptive action name to assistive technologies.<br />
  (WCAG 4.1.2 — [Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html))
- The menu state (open/closed) is communicated programmatically.
- Actions are perceivable and understandable without relying on icons alone.

## Implementation Examples

### Share menu

Social sharing links. There's a package for [Share Button](https://github.com/Yleisradio/share-button) available for easier sharing functionality.

*[Live preview](https://design-system.yle.fi/docs/components/ActionMenu/)*

<details>
<summary>Code example</summary>

```tsx
import { ActionMenu, MenuItem } from '@yleisradio/yds-components-react';
import { Link2, Mail, Whatsapp, Facebook, TwitterX, Linkedin } from '@yleisradio/yds-icons-react';

<ActionMenu text="Jaa" id="share-menu" menuId="share-menu-list">
  <MenuItem icon={<Link2 />} onSelect={() => navigator.clipboard.writeText('https://example.com')}>Kopioi linkki</MenuItem>
  <MenuItem icon={<Mail />} onSelect={() => window.open('mailto:?subject=Title&body=https://example.com')}>Sähköposti</MenuItem>
  <MenuItem icon={<Whatsapp />} onSelect={() => window.open('https://wa.me/?text=https://example.com', '_blank')}>WhatsApp</MenuItem>
  <MenuItem icon={<Facebook />} onSelect={() => window.open('https://www.facebook.com/sharer/sharer.php?u=https://example.com', '_blank')}>Facebook</MenuItem>
  <MenuItem icon={<TwitterX />} onSelect={() => window.open('https://x.com/intent/post?url=https://example.com', '_blank')}>X-viestipalvelu</MenuItem>
  <MenuItem icon={<Linkedin />} onSelect={() => window.open('https://www.linkedin.com/sharing/share-offsite/?url=https://example.com', '_blank')}>LinkedIn</MenuItem>
</ActionMenu>
```
</details>

## API Reference

### Props

The ActionMenu component accepts all standard Button props (except `as` and `onClick`) in addition to the following props:

| Prop              | Type                | Required | Default   | Description                           |
| ----------------- | ------------------- | -------- | --------- | ------------------------------------- |
| `text`            | `string`            | Yes      | —         | Button label text                     |
| `id`              | `string`            | Yes      | —         | Unique identifier for the button      |
| `menuId`          | `string`            | Yes      | —         | Unique identifier for the menu        |
| `children`        | `React.ReactNode`   | Yes      | —         | MenuItem components to display        |
| `dropdown`        | `boolean`           | No       | `true`    | Whether to show dropdown chevron icon |
| `openMenuOnClick` | `boolean`           | No       | `true`    | Whether clicking opens the menu       |
| `onClose`         | `() => void`        | No       | —         | Callback fired when menu closes       |
| `onOpen`          | `() => void`        | No       | —         | Callback fired when menu opens        |
| `menuSize`        | `'sm' \| 'md'`      | No       | `'md'`    | Size of menu items                    |
| `alignMenu`       | `'left' \| 'right'` | No       | `'right'` | Horizontal alignment of menu          |
| `position`        | `'top' \| 'right' \| 'bottom' \| 'left'` | No | `'bottom'` | Preferred direction the menu opens |

### Type Definitions

```tsx
export interface ActionMenuDSProps {
  text: string;
  id: string;
  menuId: string;
  children: ReactNode;
  dropdown?: boolean;
  openMenuOnClick?: boolean;
  onClose?: () => void;
  onOpen?: () => void;
  menuSize?: 'md' | 'sm';
  alignMenu?: 'left' | 'right';
  position?: 'top' | 'right' | 'bottom' | 'left';
}

export type ActionMenuProps = ActionMenuDSProps & Omit<ButtonProps<'button'>, 'as' | 'onClick'>;
```

## Related Components

- [DropdownMenu](../DropdownMenu/DropdownMenu.md) – Alternative component for selectable menu options
- [Button](../Button/Button.md) – ActionMenu extends Button functionality
- [Menu](../Menu/Menu.md) - Base component for ActionMenu

# Badge

Badges are used to indicate a notification, item count, or other contextual information related to a navigation destination.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=4240-129)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-badge--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Badge/Badge.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/Badge/)*

<details open>
<summary>Code example</summary>

```tsx
import { Badge } from '@yleisradio/yds-components-react';

<Badge variant="primary" size="xl">3</Badge>
```
</details>

## Why to Use

The Badge component visually indicates a status, count, or notification associated with another UI element. It helps users quickly identify new information, pending actions, or system alerts without needing to open the full view. They are typically displayed inside or attached to another component, such as an icon, button, or tab.

Badges are commonly used in navigation or profile contexts — for example, to show the number of unread messages, notifications, or active tasks. They are non-interactive and rely on their placement and appearance to convey meaning clearly.

## When to Use

Use Badge when you want to draw attention to updates, counts, or statuses related to another UI element.

## Content guidelines

> **Do**
> - Attach the badge directly to a relevant component (e.g. icon, button, tab).
> - Use it to display numeric counts or simple state indicators.
> - Choose a size that keeps the content legible relative to the parent.

> **Don’t**
> - Don’t use Badge as an interactive control.

## Key Props

Use the following props to customize the Badge component to fit your needs.

### size

Controls the visual dimensions and typography. Smaller sizes (`sm`, `md`) are suited to minimal indicators (dots); larger sizes (`lg`, `xl`) accommodate numeric content.

| Value | Example | Description |
|------|---------|------------------|
| `sm` | <Badge size="sm" /> | Tiny status indicator without text. Used in upper right corner of navigation item. |
| `md` | <Badge size="md" /> | Small status/count indicator without text. Used in upper right corner of navigation item. |
| `lg` | <Badge size="lg">3</Badge> | Default size. |
| `xl` | <Badge size="xl">12</Badge> | Prominent counts or emphasis. For inline use. |

<details>
<summary>Code example</summary>

```tsx
<Badge size="sm" />
<Badge size="md" />
<Badge size="lg">3</Badge>
<Badge size="xl">12</Badge>
```
</details>

### color

Defines semantic color scheme.

| Value | Example | Description |
|-------|---------|---------|
| `default` | <Badge color="default" size="lg">4</Badge> | Standard action background; generic counts. |
| `negative` | <Badge color="negative" size="lg">2</Badge> | Neutral/subtle emphasis; lower visual weight. |
| `highlight` | <Badge color="highlight" size="lg">12</Badge> | High-attention feedback. Use sparingly. |

<details>
<summary>Code example</summary>

```tsx
<Badge color="default" size="lg">4</Badge>
<Badge color="negative" size="lg">2</Badge>
<Badge color="highlight" size="lg">12</Badge>
```
</details>

### variant

Alters structural presentation (border & padding). `primary` is a filled pill; `secondary` applies an outline for large sizes (`lg`, `xl`).

| Value | Example | Description |
|---------|---------|-------------|
| `primary` | <Badge variant="primary" size="xl">12</Badge> | Filled default style. |
| `secondary` | <Badge variant="secondary" size="xl">12</Badge> | Outline improves contrast against background but reduces badge size |

<details>
<summary>Code example</summary>

```tsx
<Badge variant="primary" size="lg">3</Badge>
<Badge variant="secondary" size="lg">3</Badge>
<Badge variant="primary" size="xl">12</Badge>
<Badge variant="secondary" size="xl">12</Badge>
```
</details>

## Accessibility

- Use `aria-label` when numeric value or color alone lacks context (e.g. `<Badge aria-label="7 unread messages">7</Badge>`).
- Keep numbers short; truncate or summarize large counts (e.g. `99+`).
- Use ARIA attributes (e.g., aria-label, aria-live) to make changes accessible.
- Avoid animations or flashing that may cause distraction or accessibility issues.

<details>
<summary>Code example</summary>

```tsx
<Badge size="lg" aria-label="7 unread messages">7</Badge>
```
</details>

[See more examples in Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-badge--docs)

## API Reference

### Props

The Badge component accepts all standard HTML `<span>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `size` | `BadgeSizeProp` | No | `'lg'` | Size of the Badge |
| `children` | `React.ReactNode` | No | — | |
| `color` | `BadgeColorProp` | No | `'default'` | Color of the Badge |
| `variant` | `BadgeVariantProp` | No | `'primary'` | Visual presentation of the Badge |

### Type Definitions

```tsx
export type BadgeSizeProp = 'xl' | 'lg' | 'md' | 'sm';
export type BadgeColorProp = 'default' | 'negative' | 'highlight';
export type BadgeVariantProp = 'primary' | 'secondary';

export interface BadgeDSProps {
  size?: BadgeSizeProp;
  children?: React.ReactNode;
  color?: BadgeColorProp;
  variant?: BadgeVariantProp;
}

export type BadgeProps = HTMLAttributes<HTMLSpanElement> & BadgeDSProps;
```

## Related Components

- [Button](../Button/Button.md) – Badges often attach to buttons to show counts.
- [NavigationTabs](../NavigationTabs/NavigationTabs.md) – Use Badges to show per-tab notification or item counts.
- [Tag](../Tag/Tag.md) – Static keyword label without counts.
- [TagLink](../TagLink/TagLink.md) – Interactive keyword navigation.
- [TagFilter](../TagFilter/TagFilter.md) – Removable filter chips.

# BannerNotification

A BannerNotification displays important temporary messages that affect the entire view or service, appearing below the header and remaining visible until dismissed.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?m=auto&node-id=7323-2007&t=lI9imRC4H4TmzLE4-1)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-bannernotification--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/BannerNotification/BannerNotification.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

<ComponentPreview style={{ display: 'block' }}>
  <BannerNotification level="warning" title="Scheduled maintenance">
    The service will be unavailable on Sunday from 02:00 to 04:00.
  </BannerNotification>
</ComponentPreview>

<details open>
<summary>Code example</summary>

```tsx
import { BannerNotification } from '@yleisradio/yds-components-react';

<BannerNotification level="warning" title="Scheduled maintenance">
  The service will be unavailable on Sunday from 02:00 to 04:00.
</BannerNotification>
```
</details>

## Why to use

BannerNotifications communicate important service- or view-wide information that users must notice. They are designed for messages that affect the entire experience, such as maintenance, outages, or access limitations, and therefore require high visibility and persistence.

Unlike Inline Notifications, which relate to specific content, or Toasts, which are brief and transient, BannerNotifications provide sustained awareness across the whole view.

## When to use

BannerNotifications are used to communicate important information that affects the entire page or service and must be noticed by all users.

> **Do**
> - Use a BannerNotification for service-wide or view-wide messages.
> - Use it for system states such as maintenance, outages, access restrictions, or critical warnings.
> - Use it when the message must remain visible until acknowledged or resolved.
> - Use it when users may need to take action outside the current context.

> **Don’t**
> - Don’t use BannerNotifications for local or field-level issues — use Inline [Notification](../Notification/Notification.md).
> - Don’t use them for short-lived confirmations or feedback — use a [Toast](../ToastNotification/ToastNotification.md).
> - Don’t show multiple banners at the same time.
> - Don’t make critical system messages dismissible without another way to access the information.

### Differences between Notification Types

| Type                    | Purpose                                                                               | Placement                                                            | Use case                  |
| ----------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------- |
| **Banner Notification** | A notification covering the entire view or service (e.g., maintenance, error state).  | Fixed, below the header.                                             | “Maintenance in progress” |
| **Inline Notification** | A local notification within content or a form (e.g., field error).                    | Embedded in content.                                                 | “This field is required”  |
| **Toast Notification**  | A short-lived, automatically disappearing feedback message (e.g., save confirmation). | Floating near the bottom of the screen, sliding in and out smoothly. | “Saved successfully”      |

## Content Guidelines

BannerNotification content should be clear, scannable, and focused on impact. Users should immediately understand what is happening and why it matters.

> **Do**
> - Use a clear, descriptive title (e.g., “Huoltokatko”).
> - Start with what is happening and why it matters (e.g., “Palvelu ei ole käytettävissä sunnuntaina 02.00–04.00”).
> - Keep body copy short (one–two sentences).
> - Add next steps when relevant (e.g., “Yritä uudelleen”, “Näytä lisätiedot”).
> - Use actions only when the user can meaningfully act.

> **Don’t**
> - Don’t write long or dense text.
> - Don’t repeat title text in the body.
> - Don’t use vague phrasing (e.g., “Tapahtui virhe”).
> - Don’t use jargon or filler.

## Anatomy

![BannerNotification anatomy](../../img/banner-notification-anatomy.svg)

1. **Icon** – Icon indicating the message level (info, success, warning, error).
2. **Title** – Short heading.
3. **Body** – Main message content.
4. **Secondary Button (Actions)** – Optional supporting or alternative action.
5. **Primary Button (Actions)** – Main action guiding the user’s next step.
6. **Close Button** – Optional dismiss control that allows the user to close non-critical or informational notifications.

## Key BannerNotification Props

Use these props to configure the BannerNotification component.

### level

Sets semantic and visual level (icon + colors).

| Value     | Example                                                                                                         | Description                       |
| --------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `info`    | <div style={{width: '300px' }}><BannerNotification level="info">General information.</BannerNotification></div> | Neutral informational context.    |
| `success` | <BannerNotification level="success">Task completed.</BannerNotification>                                        | Positive confirmation.            |
| `warning` | <BannerNotification level="warning">Check details.</BannerNotification>                                         | Caution, requires attention soon. |
| `error`   | <BannerNotification level="error">Action failed.</BannerNotification>                                           | Critical or blocking issue.       |

<details>
<summary>Code example</summary>

```tsx
  <BannerNotification level="info">General information.</BannerNotification>
  <BannerNotification level="success">Task completed.</BannerNotification>
  <BannerNotification level="warning">Check details.</BannerNotification>
  <BannerNotification level="error">Action failed.</BannerNotification>
  ```
</details>

### title

Optional short heading preceding body.

| Type        | Example                                                                                                       | Description                 |
| ----------- | ------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `ReactNode` | <div style={{width: '300px' }}><BannerNotification title="Update">Service updated.</BannerNotification></div> | Concise summary of message. |

<details>
<summary>Code example</summary>

```tsx
  <BannerNotification title="Update">Service updated.</BannerNotification>
  ```
</details>

### children (body)

Main descriptive text.

| Type        | Example                                                                                                              | Description                  |
| ----------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `ReactNode` | <div style={{width: '300px' }}><BannerNotification title="Maintenance">Will occur Sunday.</BannerNotification></div> | Explains status or guidance. |

<details>
<summary>Code example</summary>

```tsx
  <BannerNotification title="Maintenance">Will occur Sunday.</BannerNotification>
  <BannerNotification>Standalone message without title.</BannerNotification>
  ```
</details>

### hideIcon

Suppresses level icon (text/color still convey status).

| Type      | Example                                                                                                 | Description                      |
| --------- | ------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `boolean` | <div style={{width: '300px' }}><BannerNotification hideIcon>Plain text only.</BannerNotification></div> | Removes icon for minimal layout. |

<details>
<summary>Code example</summary>

```tsx
  <BannerNotification hideIcon>Plain text only.</BannerNotification>
  ```
</details>

### onClose (close button)

| Type         | Example                                                                                                                        | Description                                                                                                         |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `() => void` | <div style={{width: '300px' }}><BannerNotification onClose={() => {}} title="Dismissable">Close me.</BannerNotification></div> | If provided, displays close button at the right side. Closing the notification needs to be handled in the callback. |

<details>
<summary>Code example</summary>

```tsx const [show, setShow] = useState(true);
  {show && (
    <BannerNotification onClose={() => setShow(false)} title="Dismissable">
      Close me.
    </BannerNotification>
  )}
  ```
</details>

### actions

Inline actionable elements (e.g., Retry, View details).

| Type        | Example                                                                                                                                                                                                                                                                                                         | Description                    |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| `ReactNode` | <div style={{width: '300px' }}><BannerNotification actions={<div style={{ display: 'flex', gap: 8}}><Button size="xs" text="Participate" /><Button variant="secondary" size="xs" text="Dismiss" /></div>} title="Beta test">We are looking for user to participate in our beta test.</BannerNotification></div> | Buttons aligned within banner. |

<details>
<summary>Code example</summary>

```tsx
  <BannerNotification
    actions={
      <div style={{ display: 'flex', gap: 8 }}>
        <Button size="xs" text="Participate" />
        <Button variant="secondary" size="xs" text="Dismiss" />
      </div>
    }
    title="Beta test"
  >
    We are looking for users to participate in our beta test.
  </BannerNotification>
  ```
</details>

### contentContainer

Custom wrapper component to constrain or style inner content.

| Type                               | Example                                                   | Description                         |
| ---------------------------------- | --------------------------------------------------------- | ----------------------------------- |
| `ComponentType<PropsWithChildren>` | [See implementation examples](#constrained-content-width) | Limits width / adds layout styling. |

## Behavior

- BannerNotifications appear directly below the global header and span the full width of the viewport.
- They remain visible until dismissed by the user or until the underlying condition is resolved.
- Only one BannerNotification should be shown per view at a time.
- BannerNotifications should not overlap or obscure primary page content.
- When actions are present, they are clearly labeled and consistently aligned.
- Dismissal is optional and should be avoided for critical system messages.

## Accessibility

- Place logically after the header in DOM order for easy navigation.
- Ensure close button includes a descriptive aria-label (e.g., “Close notification”).
- Ensure full keyboard accessibility and visible focus states for actions and controls.
- Critical information should remain available until resolved or acknowledged.

## Implementation examples

### With actions

<ComponentPreview style={{ display: 'block' }}>
  <BannerNotification
    level="info"
    title="Vahvista, että kotikuntasi on Suomessa"
    actions={<Button size="xs" text="Vahvista kotikuntasi" />}
  >
    <span>Ohjelma katsottavissa EU:n alueella.</span>
  </BannerNotification>
</ComponentPreview>

<details open>
<summary>Code example</summary>

```tsx
  <BannerNotification
    level="info"
    title="Vahvista, että kotikuntasi on Suomessa"
    actions={<Button size="xs" text="Vahvista kotikuntasi" />}
  >
    <span>Ohjelma katsottavissa EU:n alueella.</span>
  </BannerNotification>
  ```
</details>

### Constrained content width

*[Live preview](https://design-system.yle.fi/docs/components/BannerNotification/)*

## API Reference

### Props

The BannerNotification component accepts all standard HTML `<div>` attributes in addition to the following props:

| Prop               | Type                               | Required | Default  | Description |
| ------------------ | ---------------------------------- | -------- | -------- | ----------- |
| `children`         | `React.ReactNode`                  | No       | —        |             |
| `title`            | `React.ReactNode`                  | No       | —        |             |
| `level`            | `NotificationLevel`                | No       | `'info'` |             |
| `hideIcon`         | `boolean`                          | No       | —        |             |
| `onClose`          | `() => void`                       | No       | —        |             |
| `actions`          | `React.ReactNode`                  | No       | —        |             |
| `contentContainer` | `ComponentType<PropsWithChildren>` | No       | —        |             |

### Type Definitions

```tsx
export type NotificationLevel = 'info' | 'success' | 'warning' | 'error';

export interface BannerNotificationDSProps {
  children?: React.ReactNode;
  title?: React.ReactNode;
  level?: NotificationLevel;
  hideIcon?: boolean;
  onClose?: () => void;
  actions?: React.ReactNode;
  contentContainer?: ComponentType<PropsWithChildren>;
}

export type BannerNotificationProps = Omit<
  HTMLAttributes<HTMLDivElement>,
  keyof BannerNotificationDSProps
> &
  BannerNotificationDSProps;
```

## Related Components

- [Notification](../Notification/Notification.md) – Inline contextual messages.
- [Toast Notification](../ToastNotification/ToastNotification.md) – Short-lived floating feedback.

# BottomSheet

BottomSheet displays content in a panel that slides up from the bottom of the viewport. It is optimized for mobile and touch-based interactions and can be either modal or non-modal. BottomSheet handles gestures, positioning, overlay behavior, and accessibility, and often contains a Dialog component for structured content.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?m=auto&node-id=9821-1268&t=lI9imRC4H4TmzLE4-1)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-bottomsheet--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/BottomSheet/BottomSheet.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/BottomSheet/)*

<details open>
<summary>Code example</summary>

```tsx
import { BottomSheet, useBottomSheet, Button, Dialog } from '@yleisradio/yds-components-react';

const { bottomSheetRef, openBottomSheet, closeBottomSheet } = useBottomSheet();

<>
  <Button onClick={openBottomSheet}>Open Bottom Sheet</Button>
  <BottomSheet bottomSheetRef={bottomSheetRef}>
    <Dialog
      title="BottomSheet Title"
      actions={
        <>
          <Button text="OK" />
        </>
      }
    >
      <p>BottomSheet content goes here</p>
    </Dialog>
  </BottomSheet>
</>
```
</details>

## Why to use

Use BottomSheet to present contextual content, actions, or settings while preserving the user’s sense of place. It provides a mobile-friendly alternative to Modal with natural touch interactions, flexible sizing, and optional non-modal behavior. BottomSheet standardizes mobile dialog behavior across YDS and ensures accessible gesture and keyboard handling.

## When to use

Use BottomSheet when content is closely related to the current view and especially in mobile or touch-first contexts.

> **Do**
> - Use BottomSheet for mobile dialogs, filters, and settings.
> - Use it when content should feel lightweight and dismissible.
> - Combine BottomSheet with [Dialog](../Dialog/Dialog.md) for structured content.

> **Don't**
> - Don’t use BottomSheet for critical confirmations that require full attention.
> - Don’t use BottomSheet for complex, multi-step workflows.
> - Don’t replace desktop modals with BottomSheet unnecessarily.

## Content Guidelines

Use these guidelines when placing content inside a BottomSheet.

> **Do**
> - Keep content task-focused and lightweight.
> - Prefer short forms and clear actions.
> - Use clear completion actions such as “Done” or “Apply”.

> **Don't**
> - Don’t overload the sheet with long scrolling content unless using the expanded size.
> - Don’t hide critical actions below excessive content.
> - Don’t rely on drag-to-close as the only way to dismiss the sheet.

## Anatomy

![BottomSheet anatomy](../../img/bottomsheet-anatomy.svg)

1. **Drag handle / close affordance** – Visual indicator that the sheet can be dragged or dismissed.
2. **Sheet container** – The surface that slides up from the bottom and contains all sheet content.
3. **Bottom Sheet title** – Required heading that describes the purpose of the sheet.
4. **Content area** – The main content section for text or interactive elements. Supports internal scrolling when content exceeds available height.
5. **Actions area (optional)** – Footer area for primary and secondary actions, aligned consistently across devices.

## Key BottomSheet Props

Use these props to configure the BottomSheet component.

### bottomSheetRef

Ref handle for controlling the bottom sheet (open/close). Use with `useBottomSheet` hook.

| Type                                 | Example               | Description                         |
| ------------------------------------ | --------------------- | ----------------------------------- |
| `React.RefObject<BottomSheetHandle>` | <BottomSheeExample /> | Ref handle for programmatic control |

<details>
<summary>Code example</summary>

```tsx
const { bottomSheetRef, openBottomSheet, closeBottomSheet } = useBottomSheet();

<BottomSheet bottomSheetRef={bottomSheetRef}>
  <div>Content here</div>
  <Button onClick={closeBottomSheet}>Done</Button>
</BottomSheet>
```
</details>

### title

Optional heading text displayed in the sheet header.

| Type     | Example                                | Description                     |
| -------- | -------------------------------------- | ------------------------------- |
| `string` | <BottomSheeExample title="Settings" /> | Title text for the bottom sheet |

<details>
<summary>Code example</summary>

```tsx
const { bottomSheetRef, openBottomSheet, closeBottomSheet } = useBottomSheet();

<BottomSheet title="Settings" bottomSheetRef={bottomSheetRef}>
  <div>Content here</div>
  <Button onClick={closeBottomSheet}>Done</Button>
</BottomSheet>
```
</details>

### titleAs

HTML tag name to render for the title.

| Type     | Example                            | Description                         |
| -------- | ---------------------------------- | ----------------------------------- |
| `string` | <BottomSheeExample titleAs="h3" /> | HTML element for title (e.g., 'h2') |

<details>
<summary>Code example</summary>

```tsx
const { bottomSheetRef, openBottomSheet, closeBottomSheet } = useBottomSheet();

<BottomSheet titleAs="h3" bottomSheetRef={bottomSheetRef}>
  <div>Content here</div>
  <Button onClick={closeBottomSheet}>Done</Button>
</BottomSheet>
```
</details>

### dragToClose

Enables pointer drag gesture and handle for closing the sheet.

| Value   | Example                                   | Description                          |
| ------- | ----------------------------------------- | ------------------------------------ |
| `true`  | <BottomSheeExample dragToClose={true} />  | Enables drag-to-close functionality  |
| `false` | <BottomSheeExample dragToClose={false} /> | Disables drag-to-close functionality |

<details>
<summary>Code example</summary>

```tsx
const { bottomSheetRef, openBottomSheet, closeBottomSheet } = useBottomSheet();

<BottomSheet dragToClose bottomSheetRef={bottomSheetRef}>
  <div>Content here</div>
  <Button onClick={closeBottomSheet}>Done</Button>
</BottomSheet>
```
</details>

### align

Horizontal alignment of the sheet.

| Value    | Example                              | Description                    |
| -------- | ------------------------------------ | ------------------------------ |
| `center` | <BottomSheeExample align="center" /> | Centers the sheet horizontally |
| `left`   | <BottomSheeExample align="left" />   | Aligns sheet to the left       |
| `right`  | <BottomSheeExample align="right" />  | Aligns sheet to the right      |

<details>
<summary>Code example</summary>

```tsx
const { bottomSheetRef, openBottomSheet, closeBottomSheet } = useBottomSheet();

<BottomSheet align="center" bottomSheetRef={bottomSheetRef}>
  <div>Content here</div>
  <Button onClick={closeBottomSheet}>Done</Button>
</BottomSheet>
```
</details>

### nonModal

If true, renders a non-modal dialog (no backdrop, background remains interactive).

| Value   | Example                                | Description               |
| ------- | -------------------------------------- | ------------------------- |
| `true`  | <BottomSheeExample nonModal={true} />  | Makes the sheet non-modal |
| `false` | <BottomSheeExample nonModal={false} /> | Makes the sheet modal     |

<details>
<summary>Code example</summary>

```tsx
const { bottomSheetRef, openBottomSheet, closeBottomSheet } = useBottomSheet();

<BottomSheet nonModal={true} bottomSheetRef={bottomSheetRef}>
  <div>Content here</div>
  <Button onClick={closeBottomSheet}>Done</Button>
</BottomSheet>
```
</details>

### closeOnOutsideClick

If true, clicking outside the sheet closes it (modal only).

| Value   | Example                                           | Description                             |
| ------- | ------------------------------------------------- | --------------------------------------- |
| `true`  | <BottomSheeExample closeOnOutsideClick={true} />  | Controls outside click closing behavior |
| `false` | <BottomSheeExample closeOnOutsideClick={false} /> | Controls outside click closing behavior |

<details>
<summary>Code example</summary>

```tsx
const { bottomSheetRef, openBottomSheet, closeBottomSheet } = useBottomSheet();

<BottomSheet closeOnOutsideClick={true} bottomSheetRef={bottomSheetRef}>
  <div>Content here</div>
  <Button onClick={closeBottomSheet}>Done</Button>
</BottomSheet>
```
</details>

### size

Size variant of the bottom sheet.

| Value      | Example                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Description           |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `compact`  | <BottomSheeExample size="compact"><div style={{ padding: '0 1.5rem 1.5rem', lineHeight: '2' }}>What is Lorem Ipsum? Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum. Why do we use it? It is a long established fact that a reader will be distracted by the readable content of a page when looking at its layout. The point of using Lorem Ipsum is that it has a more-or-less normal distribution of letters, as opposed to using 'Content here, content here', making it look like readable English. Many desktop publishing packages and web page editors now use Lorem Ipsum as their default model text, and a search for 'lorem ipsum' will uncover many web sites still in their infancy. Various versions have evolved over the years, sometimes by accident, sometimes on purpose (injected humour and the like). Where does it come from? Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words, consectetur, from a Lorem Ipsum passage, and going through the cites of the word in classical literature, discovered the undoubtable source. Lorem Ipsum comes from sections 1.10.32 and 1.10.33 of "de Finibus Bonorum et Malorum" (The Extremes of Good and Evil) by Cicero, written in 45 BC. This book is a treatise on the theory of ethics, very popular during the Renaissance. The first line of Lorem Ipsum, "Lorem ipsum dolor sit amet..", comes from a line in section 1.10.32. The standard chunk of Lorem Ipsum used since the 1500s is reproduced below for those interested. Sections 1.10.32 and 1.10.33 from "de Finibus Bonorum et Malorum" by Cicero are also reproduced in their exact original form, accompanied by English versions from the 1914 translation by H. Rackham. Where can I get some? There are many variations of passages of Lorem Ipsum available, but the majority have suffered alteration in some form, by injected humour, or randomised words which don't look even slightly believable. If you are going to use a passage of Lorem Ipsum, you need to be sure there isn't anything embarrassing hidden in the middle of text. All the Lorem Ipsum generators on the Internet tend to repeat predefined chunks as necessary, making this the first true generator on the Internet. It uses a dictionary of over 200 Latin words, combined with a handful of model sentence structures, to generate Lorem Ipsum which looks reasonable. The generated Lorem Ipsum is therefore always free from repetition, injected humour, or non-characteristic words etc.</div></BottomSheeExample>  | Compact size variant  |
| `default`  | <BottomSheeExample size="default"><div style={{ padding: '0 1.5rem 1.5rem', lineHeight: '2' }}>What is Lorem Ipsum? Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum. Why do we use it? It is a long established fact that a reader will be distracted by the readable content of a page when looking at its layout. The point of using Lorem Ipsum is that it has a more-or-less normal distribution of letters, as opposed to using 'Content here, content here', making it look like readable English. Many desktop publishing packages and web page editors now use Lorem Ipsum as their default model text, and a search for 'lorem ipsum' will uncover many web sites still in their infancy. Various versions have evolved over the years, sometimes by accident, sometimes on purpose (injected humour and the like). Where does it come from? Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words, consectetur, from a Lorem Ipsum passage, and going through the cites of the word in classical literature, discovered the undoubtable source. Lorem Ipsum comes from sections 1.10.32 and 1.10.33 of "de Finibus Bonorum et Malorum" (The Extremes of Good and Evil) by Cicero, written in 45 BC. This book is a treatise on the theory of ethics, very popular during the Renaissance. The first line of Lorem Ipsum, "Lorem ipsum dolor sit amet..", comes from a line in section 1.10.32. The standard chunk of Lorem Ipsum used since the 1500s is reproduced below for those interested. Sections 1.10.32 and 1.10.33 from "de Finibus Bonorum et Malorum" by Cicero are also reproduced in their exact original form, accompanied by English versions from the 1914 translation by H. Rackham. Where can I get some? There are many variations of passages of Lorem Ipsum available, but the majority have suffered alteration in some form, by injected humour, or randomised words which don't look even slightly believable. If you are going to use a passage of Lorem Ipsum, you need to be sure there isn't anything embarrassing hidden in the middle of text. All the Lorem Ipsum generators on the Internet tend to repeat predefined chunks as necessary, making this the first true generator on the Internet. It uses a dictionary of over 200 Latin words, combined with a handful of model sentence structures, to generate Lorem Ipsum which looks reasonable. The generated Lorem Ipsum is therefore always free from repetition, injected humour, or non-characteristic words etc.</div></BottomSheeExample>  | Default size variant  |
| `expanded` | <BottomSheeExample size="expanded"><div style={{ padding: '0 1.5rem 1.5rem', lineHeight: '2' }}>What is Lorem Ipsum? Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum. Why do we use it? It is a long established fact that a reader will be distracted by the readable content of a page when looking at its layout. The point of using Lorem Ipsum is that it has a more-or-less normal distribution of letters, as opposed to using 'Content here, content here', making it look like readable English. Many desktop publishing packages and web page editors now use Lorem Ipsum as their default model text, and a search for 'lorem ipsum' will uncover many web sites still in their infancy. Various versions have evolved over the years, sometimes by accident, sometimes on purpose (injected humour and the like). Where does it come from? Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words, consectetur, from a Lorem Ipsum passage, and going through the cites of the word in classical literature, discovered the undoubtable source. Lorem Ipsum comes from sections 1.10.32 and 1.10.33 of "de Finibus Bonorum et Malorum" (The Extremes of Good and Evil) by Cicero, written in 45 BC. This book is a treatise on the theory of ethics, very popular during the Renaissance. The first line of Lorem Ipsum, "Lorem ipsum dolor sit amet..", comes from a line in section 1.10.32. The standard chunk of Lorem Ipsum used since the 1500s is reproduced below for those interested. Sections 1.10.32 and 1.10.33 from "de Finibus Bonorum et Malorum" by Cicero are also reproduced in their exact original form, accompanied by English versions from the 1914 translation by H. Rackham. Where can I get some? There are many variations of passages of Lorem Ipsum available, but the majority have suffered alteration in some form, by injected humour, or randomised words which don't look even slightly believable. If you are going to use a passage of Lorem Ipsum, you need to be sure there isn't anything embarrassing hidden in the middle of text. All the Lorem Ipsum generators on the Internet tend to repeat predefined chunks as necessary, making this the first true generator on the Internet. It uses a dictionary of over 200 Latin words, combined with a handful of model sentence structures, to generate Lorem Ipsum which looks reasonable. The generated Lorem Ipsum is therefore always free from repetition, injected humour, or non-characteristic words etc.</div></BottomSheeExample> | Expanded size variant |

<details>
<summary>Code example</summary>

```tsx
  <BottomSheet size="compact" bottomSheetRef={bottomSheetRef}>
    <Dialog title="Content">Content</Dialog>
  </BottomSheet>
  ```
</details>

## Behavior

- BottomSheet slides in from the bottom of the viewport and animates smoothly when opening and closing.
- The sheet opens when `openBottomSheet()` is called or when the ref’s `open()` method is invoked.
- The sheet closes when `closeBottomSheet()` is called, the close button or drag handle is activated, the Escape key is pressed, or the user drags the sheet down past the close threshold.
- Drag-to-close interaction is enabled when `dragToClose={true}`. If the drag distance exceeds the threshold (100px), the sheet closes; otherwise, it snaps back into place.
- Modal bottom sheets (default) block background interaction and disable body scrolling.
- Non-modal bottom sheets (`nonModal={true}`) allow background interaction and do not disable body scrolling.
- Focus and keyboard behavior adapt based on modality.
- The Escape key always closes modal bottom sheets and closes non-modal sheets only when focus is inside the sheet.
- Clicking outside the sheet closes it only when `closeOnOutsideClick={true}` and the sheet is modal.
- The `onClose` callback fires after the sheet has fully closed (native dialog `close` event).
- Size variants (`compact`, `default`, `expanded`) control how much vertical space the sheet initially occupies.

## Accessibility

- BottomSheet uses the native HTML `<dialog>` element to ensure correct semantics and screen reader support
  ([WCAG 4.1.2 — Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value)).
- Modal BottomSheets trap keyboard focus while open and prevent interaction with background content, whereas non-modal BottomSheets allow background interaction and only handle keyboard events when focus is inside the sheet.
- The sheet can always be closed using the Escape key
  ([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard)).
- Drag-to-close is a supplementary interaction; keyboard and button-based closing must always be available.

## Implementation Examples

### Game instructions BottomSheet with Dialog

*[Live preview](https://design-system.yle.fi/docs/components/BottomSheet/)*

### Nickname BottomSheet with custom content

*[Live preview](https://design-system.yle.fi/docs/components/BottomSheet/)*

<details>
<summary>Code example</summary>

```tsx
import { BottomSheet, useBottomSheet, Button, TextInput } from '@yleisradio/yds-components-react';

const { bottomSheetRef, openBottomSheet, closeBottomSheet } = useBottomSheet();

<BottomSheet bottomSheetRef={bottomSheetRef} title="Aseta itsellesi nimimerkki">
  <div>Nimimerkin pitää olla asiallinen ja noudattaa hyvää makua.</div>
  <TextInput label="Nimimerkki" placeholder="Aseta nimimerkki" />
  <Button onClick={closeBottomSheet}>Hyväksy</Button>
</BottomSheet>
```
</details>

## API Reference

### Props

The BottomSheet component accepts all standard HTML `<dialog>` attributes in addition to the following props:

| Prop                  | Type                                   | Required | Default     | Description                                    |
| --------------------- | -------------------------------------- | -------- | ----------- | ---------------------------------------------- |
| `bottomSheetRef`      | `React.RefObject<BottomSheetHandle>`   | No       | —           | Ref handle for controlling the bottom sheet    |
| `title`               | `string`                               | No       | —           | Optional heading text displayed in header      |
| `titleAs`             | `string`                               | No       | —           | HTML tag name to render for title (e.g., 'h2') |
| `onClose`             | `() => void`                           | No       | —           | Callback fired after sheet closes              |
| `dragToClose`         | `boolean`                              | No       | `true`      | Enables drag-to-close functionality            |
| `align`               | `'center' \| 'left' \| 'right'`        | No       | `'center'`  | Horizontal alignment of the sheet              |
| `nonModal`            | `boolean`                              | No       | `false`     | Renders as non-modal dialog                    |
| `closeOnOutsideClick` | `boolean`                              | No       | `true`      | Closes sheet on outside click (modal only)     |
| `size`                | `'compact' \| 'default' \| 'expanded'` | No       | `'default'` | Size variant of the bottom sheet               |
| `children`            | `React.ReactNode`                      | No       | —           | Content displayed inside the sheet             |

### Type Definitions

```tsx
export interface BottomSheetDSProps {
  bottomSheetRef?: React.RefObject<BottomSheetHandle>;
  title?: string;
  titleAs?: string;
  onClose?: () => void;
  children?: React.ReactNode;
  dragToClose?: boolean;
  align?: 'center' | 'left' | 'right';
  nonModal?: boolean;
  closeOnOutsideClick?: boolean;
  size?: 'compact' | 'default' | 'expanded';
}

export type BottomSheetProps = HTMLAttributes<HTMLDialogElement> & BottomSheetDSProps;

export type BottomSheetHandle = {
  open: () => void;
  close: () => void;
};
```

### useBottomSheet Hook

The `useBottomSheet` hook provides a convenient way to manage bottom sheet state.

#### Returns

| Property           | Type                                 | Description                                     |
| ------------------ | ------------------------------------ | ----------------------------------------------- |
| `bottomSheetRef`   | `React.RefObject<BottomSheetHandle>` | Ref object to pass to the BottomSheet component |
| `openBottomSheet`  | `() => void`                         | Function to open the bottom sheet               |
| `closeBottomSheet` | `() => void`                         | Function to close the bottom sheet              |

## Related Components

- [Modal](../Modal/Modal.md) – Alternative modal component.
- [Dialog](../Dialog/Dialog.md) – Often used inside BottomSheet for content structure.
- [Accordion](../Accordion/Accordion.md) – Can be used inside a BottomSheet to organise collapsible content.

# Button

A Button triggers an action or confirms a choice when the user activates it.
- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=2151-9310)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-button--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Button/Button.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/Button/)*

<details open>
<summary>Code example</summary>

```tsx
import { Button } from '@yleisradio/yds-components-react';

<Button text="Primary" />
```
</details>

## Why to use

Buttons are used to execute actions in the interface: submitting a form, opening a modal, cancelling an operation, or performing add/remove actions. They stand out visually from surrounding content and guide the user’s attention to the most important actions.
The button text must clearly communicate what happens when it is pressed (for example, “Poista kaikki” or “Lähetä lomake”). It should typically start with a verb and use sentence case.

## When to use

Use a Button when the user needs to perform an explicit action. Buttons initiate tasks, submit information, confirm decisions, or open additional functionality. Use a Button whenever the user is expected to do something, not just navigate or view content.

> **Do**
> - Use a Button when an action changes data, advances a task, or opens an interaction.
> - Use the Primary button for the main action in a section or flow.
> - Use Secondary and Text buttons for supporting or lower-priority actions.
> - Use a Button instead of a link when something should happen on the same page.
> - Use icon-only buttons only when they fit the interaction pattern, the icon is widely recognized, or space is limited.

> **Don’t**
> - Don’t use a Button for simple navigation — use a [Link](../Link/Link.md) instead.
> - Don’t use a Button when the action is ambiguous or when a menu would better support the flow.
> - Don’t use multiple Primary buttons in the same section — it weakens the main action.
> - Don’t use disabled buttons to explain why something can’t be done — use helper or error text instead.
> - Don’t use very small button sizes as the default, especially on touch devices.

## Content Guidelines

Button labels must be short, clear, and action-oriented. They tell the user exactly what will happen when the button is pressed. Good labels increase confidence and reduce cognitive load.

- Start labels with a clear verb (e.g., Tallenna, Jatka, Muokkaa, Poista).
- Keep labels brief — ideally 1–2 words.
- Use consistent wording across the product (e.g., always use Peruuta for dismissing actions).
- Don’t use vague or generic labels like OK, Hyväksy, or Klikkaa tästä.
- Don’t use humor, jargon, or internal terminology unfamiliar to users.
- Don’t rely on icon-only labels without accessible text.

### Usage in UI patterns

#### Text labels

Use concise, action-oriented labels starting with a verb without unnecessary words or politeness (e.g., Tallenna, Jatka, Muokkaa, Poista).

**Do:** Good: Clear and concise.

**Don't:** Bad: Unnecessary politeness.

**Do:** Good: Clear and concise.

**Don't:** Bad: Unnecessary words.

#### Short labels

Keep labels brief — ideally 1–2 words. Avoid long phrases or sentences.

**Do:** Good: Short and to the point.

**Don't:** Bad: Too long and wordy.

#### Icons
Even with an icon, the label must clearly describe the action (e.g., “Poista tiedosto” with a trash can icon), not just an icon.

**Do:** Good: Text describes the action.

**Don't:** Bad: Icon alone is unclear.

#### Forms
The label should describe the result of submitting (e.g., “Lähetä lomake”, “Tallenna muutokset”), not the action “Lähetä”.

**Do:** Good: Describes the result of the action.

**Don't:** Bad: Vague about what happens.

>
#### Dialogs & confirmations
The primary button must clearly confirm the intended action (e.g., “Poista tiedosto”, “Hyväksy ehdot”), while secondary actions use neutral wording (e.g., “Peruuta”).

**Do:** Good: Clearly states the action.

**Don't:** Bad: Ambiguous confirmation.
#### Destructive actions
Make the consequence explicit to prevent mistakes (e.g., “Poista kaikki”, “Tyhjennä lista”). Avoid ambiguous verbs like “Poista” ilman kohdetta.

**Do:** Good: Specifies what will be deleted.

**Don't:** Bad: Unclear about the target.

#### Navigation
Labels should indicate where the user will go (e.g., “Jatka eteenpäin”, “Avaa asetukset”, “Näytä lisää”).

**Do:** Good: Indicates the destination.

**Don't:** Bad: Vague about where it leads.

## Anatomy

![Button anatomy](../../img/button-anatomy.svg)

1. **Container** – Clickable target
2. **Label** – Action text
3. **Icon Before (Optional)** – Visual cue preceding text
4. **Icon After (Optional)** – Supplementary indicator

## Key Button Props

Use these props to configure the Button component.

### text
Visible label text of the button. Explains the action performed when pressed.

| Type | Example | Description |
|------|---------|-------------|
| `string` | <Button text="Submit" /> | Text displayed inside the button that explains what happens when it is pressed. |

<details>
<summary>Code example</summary>

```tsx
<Button text="Submit" />
```
</details>

> **Warning**
> Avoid using `children` for text because it may lead to inconsistent styling with some other props.

### variant
Defines the visual and hierarchical level of the button.

| Value |  Example | Description |
|-------|----------|-------------|
| `primary` | <Button text="Save" /> | Default variant for the main action. |
| `secondary` | <Button variant="secondary" text="Cancel" /> | Secondary action. Always used with a primary button. |
| `text` | <Button variant="text" text="Details" /> | Low-emphasis text-style button. |

<details>
<summary>Code example</summary>

```tsx
<Button text="Save" />
<Button variant="secondary" text="Cancel" />
<Button variant="text" text="Details" />
```
</details>

### size
Adjusts dimensions and typography.

| Value | Example | Description |
|-------|---------|-------------|
| `xs` | <Button size="xs" text="Button" /> | Smallest accessible button. |
| `sm` | <Button size="sm" text="Button" /> | Compact button. |
| `md` | <Button size="md" text="Button" /> | Default size. |
| `lg` | <Button size="lg" text="Button" /> | Large button for key CTAs. |

<details>
<summary>Code example</summary>

```tsx
<Button size="xs" text="Button" />
<Button size="sm" text="Button" />
<Button size="md" text="Button" />
<Button size="lg" text="Button" />
```
</details>

### isDisabled
Non-interactive, dimmed styling.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Button text="Button" isDisabled />| Temporarily prevents user interaction. Sets `aria-disabled` on the button. |

<details>
<summary>Code example</summary>

```tsx
<Button isDisabled text="Submit" />
```
</details>

### fullWidth
Expands Button to fill parent width – especially useful in mobile views.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <div style={{ width: '300px' }}><Button text="Button" fullWidth /></div> | Makes the button stretch horizontally. |

<details>
<summary>Code example</summary>

```tsx
<div style={{ width: '300px' }}>
  <Button text="Button" fullWidth />
</div>
```
</details>

### iconBefore
Adds icon component before the text.

| Type | Example | Description |
|------|---------|-------------|
| `ReactNode` | <Button text="Play" iconBefore={<Play />} /> | Rendered before the label text. |

<details>
<summary>Code example</summary>

```tsx
import { Play, ArrowRight } from '@yleisradio/yds-icons-react';

<Button iconBefore={<Play />} text="Play" />
```
</details>

### iconAfter
Adds icon component after the text. Often used for dropdown indicators or directional arrows.

| Type | Example | Description |
|------|---------|-------------|
| `ReactNode` | <Button text="Next" iconAfter={<ArrowRight />} /> | Rendered after the label text. |

<details>
<summary>Code example</summary>

```tsx
import { ArrowRight } from '@yleisradio/yds-icons-react';

<Button text="Next" iconAfter={<ArrowRight />} />
```
</details>

### iconOnly

Renders a button with only an icon, requires `accessibleText` for accessibility.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Button iconBefore={<Play />} accessibleText="Play media" iconOnly /> | Icon-only button variant. |

<details>
<summary>Code example</summary>

```tsx
  <Button iconBefore={<Play />} accessibleText="Play media" iconOnly />
  ```
</details>

### accessibleText

Supplementary text for screen readers when using icon-only buttons.

| Type | Example | Description |
|------|---------|-------------|
| `string` | <Button text="Play" accessibleText="Play media" /> | Provides additional context for assistive technologies. Uses `aria-label`. |

<details>
<summary>Code example</summary>

```tsx
<Button text="Play" accessibleText="Play media" />
```
</details>

### removePadding

Removes default padding, use only when you fully control the inner layout.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Button text="Button" variant="text" removePadding /> | Works only with `variant="text"`. Eliminates default padding inside the button. |

<details>
<summary>Code example</summary>

```tsx
<Button text="Button" variant="text" removePadding />
```
</details>

### loading

Replaces text with a loading spinner and disables interaction.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Button text="Submit" loading /> | Indicates that an action is in progress. |

<details>
<summary>Code example</summary>

```tsx
<Button text="Submit" loading />
```
</details>

## Behavior

- Buttons provide clear visual feedback for interaction states (hover, focus, active, disabled, loading).
- Clicking or tapping a button triggers its action immediately.
- Loading state prevents repeated submissions or accidental double actions.
- Disabled buttons do not respond to interaction and appear inactive.
- Keep button sizes consistent within a group.
- Use full-width buttons on mobile to improve tap targets and clarity.
- Icon-only buttons and dropdown buttons must behave consistently with text buttons.
- Buttons that open menus or dialogs should visually indicate expanded and collapsed states.

## Accessibility

- Ensure icon-only buttons have an accessible name via `aria-label`.
- Disabled buttons should generally be focusable.
- Disable a button only when the action cannot yet be performed — and provide guidance nearby.
- Icon-only buttons must include accessible text via `accessibleText`.
- Fully keyboard-accessible and visible focus states.<br /> ([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard))

## Implementation examples

### Asynchronous actions

*[Live preview](https://design-system.yle.fi/docs/components/Button/)*

### Disabled until conditions are met

*[Live preview](https://design-system.yle.fi/docs/components/Button/)*

## API Reference

### Props

The Button component accepts all standard HTML `<button>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `'primary' \| 'secondary' \| 'text'` | No | `'primary'` | |
| `isDisabled` | `boolean` | No | `false` | |
| `iconBefore` | `React.ReactElement<SvgProps> \| null` | No | `undefined` | |
| `iconAfter` | `React.ReactElement<SvgProps> \| null` | No | `undefined` | |
| `iconOnly` | `boolean` | No | `false` | |
| `loading` | `boolean` | No | `false` | |
| `size` | `ButtonSize` | No | `'md'` | |
| `text` | `string` | No | — | |
| `accessibleText` | `string` | No | — | |
| `fullWidth` | `boolean` | No | `false` | |
| `removePadding` | `boolean` | No | `false` | |

### Type Definitions

```tsx
export type ButtonSize = 'xs' | 'sm' | 'md' | 'lg';

export interface ButtonDSProps {
  variant?: 'primary' | 'secondary' | 'text';
  isDisabled?: boolean;
  iconBefore?: React.ReactElement<SvgProps> | null;
  iconAfter?: React.ReactElement<SvgProps> | null;
  iconOnly?: boolean;
  loading?: boolean;
  size?: ButtonSize;
  text?: string;
  accessibleText?: string;
  fullWidth?: boolean;
  removePadding?: boolean;
}

export type ButtonProps<C extends React.ElementType> = PolymorphicComponentPropsWithRef<
  C,
  ButtonDSProps
>;
```

## Related Components

- [Link](../Link/Link.md) – Navigational transitions.
- [ButtonGroup](../ButtonGroup/ButtonGroup.md) – Group of buttons for related actions.
- [ActionMenu](../ActionMenu/ActionMenu.md) – Extends Button with a dropdown of related actions.
- [Badge](../Badge/Badge.md) – Often attached to a Button to show counts or status.
- [Spinner](../Spinner/Spinner.md) – Can be used inside a Button to indicate a loading state.

# ButtonGroup

A ButtonGroup is a selection component that groups multiple buttons into one structured unit so users can make single or multiple selections, apply filters, or toggle view states directly in the interface.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=6180-83)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-buttongroup--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/ButtonGroup/ButtonGroup.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/ButtonGroup/)*

<details open>
<summary>Code example</summary>

```tsx
import { ButtonGroup } from '@yleisradio/yds-components-react';

<ButtonGroup>
  <ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button>
  <ButtonGroup.Button id="btn-2">Option 2</ButtonGroup.Button>
  <ButtonGroup.Button id="btn-3">Option 3</ButtonGroup.Button>
</ButtonGroup>
```
</details>

## Why to use

ButtonGroup offers a compact, highly visible way to present related options side by side. It allows users to compare choices at a glance and make selections without opening menus or dialogs. ButtonGroup supports both single- and multi-select patterns and is well suited for filters, view modes, and inline state controls.

## When to use

Use a ButtonGroup when users need to select between a small set of options that should remain visible at all times.

### ButtonGroup supports multiple selection patterns

| Pattern                       | What it does                                                                                     | Typical use cases                                                      |
| ----------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| **Single Select**             | Allows one option at a time; selecting a new option deselects the previous one.                  | View or mode switching (e.g., tuntinäkymä / päivät / karttanäkymät).   |
| **Filterable (Multi-select)** | Allows zero or more options to be active simultaneously, often with visual selection indicators. | Content filtering by categories, tags, or features.                    |
| **Toggle actions**            | Toggles UI states on or off directly within the interface.                                       | Enabling or disabling settings or view options without opening a menu. |

> **Do**
> - Use ButtonGroup when options must be immediately visible and easily comparable.
> - Use it for switching modes, applying filters, or toggling view states.
> - Use single-select when options are mutually exclusive.
> - Use multi-select when multiple options can be active at the same time.

> **Don't**
> - Don’t use ButtonGroup for long or complex lists — use [Select](../Select/Select.md) or [DropdownMenuGroup](../DropdownMenuGroup/DropdownMenuGroup.md).
> - Don’t use it for page-level navigation — use [NavigationTabs](../NavigationTabs/NavigationTabs.md) instead.
> - Don’t use ButtonGroup for switching content within a section — use [SectionTabs](../SectionTabs/SectionTabs.md) instead.
> - Don’t mix unrelated actions and selection states in the same group.
> - Don’t use ButtonGroup when options don’t need to stay visible.

## Content Guidelines

ButtonGroup labels must be short, scannable, and comparable. Users should be able to understand the differences between options without extra explanation.

> **Do**
> - Use short, clear labels (e.g., “Kaikki”, “Uutiset”, “Suora”, “Klipit”).
> - Use nouns for selections and filters.
> - Use verbs only when a button triggers an immediate action.
> - Keep capitalization and terminology consistent within the group.
> - Keep groups small (ideally 2–6 options).

> **Don't**
> - Don’t use long sentences or explanatory text inside buttons.
> - Don’t change label wording between states without a clear reason.
> - Don’t use vague or context-free labels.
> - Don’t overload buttons with multiple icons or mixed meanings.

## Anatomy

![ButtonGroup anatomy](../../img/button-group-anatomy.svg)

1. **Group container** – Wraps the buttons and manages spacing, alignment, borders, and wrapping..
2. **Button** – Individual selectable option (extends Button component).
3. **Selection icon (optional)** – Used mainly in multi-select patterns (e.g., plus → checkmark).
4. **Label** – Text inside each button describing the option.

## Key ButtonGroup Props

Use these props to configure the ButtonGroup component.

### children

ButtonGroup.Button components to display.

| Type              | Example                                                                                                                                             | Description                   |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `React.ReactNode` | <ButtonGroup><ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button><ButtonGroup.Button id="btn-2">Option 2</ButtonGroup.Button></ButtonGroup> | ButtonGroup.Button components |

<details>
<summary>Code example</summary>

```tsx
  <ButtonGroup>
    <ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button>
    <ButtonGroup.Button id="btn-2">Option 2</ButtonGroup.Button>
  </ButtonGroup>
  ```
</details>

### multiple

Whether multiple buttons can be selected simultaneously.

| Type      | Example                                                                                                                                                      | Description               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
| `boolean` | <ButtonGroup multiple><ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button><ButtonGroup.Button id="btn-2">Option 2</ButtonGroup.Button></ButtonGroup> | Enables multi-select mode |

<details>
<summary>Code example</summary>

```tsx
  <ButtonGroup multiple>
    <ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button>
    <ButtonGroup.Button id="btn-2">Option 2</ButtonGroup.Button>
  </ButtonGroup>
  ```
</details>

### defaultValue

Initial selected value(s) for uncontrolled component.

| Type                 | Example                                                                                                                                                                  | Description               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
| `string \| string[]` | <ButtonGroup defaultValue="btn-1"><ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button><ButtonGroup.Button id="btn-2">Option 2</ButtonGroup.Button></ButtonGroup> | Initial selected value(s) |

<details>
<summary>Code example</summary>

```tsx
<ButtonGroup defaultValue="btn-1">
  <ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button>
  <ButtonGroup.Button id="btn-2">Option 2</ButtonGroup.Button>
</ButtonGroup>

<ButtonGroup multiple defaultValue={['btn-1', 'btn-2']}>
  <ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button>
  <ButtonGroup.Button id="btn-2">Option 2</ButtonGroup.Button>
</ButtonGroup>
```
</details>

### value

Current selected value(s) for controlled component.

| Type                 | Example                                                                                                                                                           | Description                  |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `string \| string[]` | <ButtonGroup value="btn-1"><ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button><ButtonGroup.Button id="btn-2">Option 2</ButtonGroup.Button></ButtonGroup> | Controlled selected value(s) |

<details>
<summary>Code example</summary>

```tsx
const [selected, setSelected] = useState('btn-1');

<ButtonGroup value={selected} onChange={setSelected}>
  <ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button>
  <ButtonGroup.Button id="btn-2">Option 2</ButtonGroup.Button>
</ButtonGroup>
```
</details>

### variant

Visual style variant of the buttons.

| Value       | Example                                                                                                                                                                 | Description            | Purpose                                                                                               |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------- |
| `primary`   | <ButtonGroup variant="primary"><ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button><ButtonGroup.Button id="btn-2">Option 2</ButtonGroup.Button></ButtonGroup>   | Primary button style   | Best for prominent selections that control the main view content; easier to scan at a glance.         |
| `secondary` | <ButtonGroup variant="secondary"><ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button><ButtonGroup.Button id="btn-2">Option 2</ButtonGroup.Button></ButtonGroup> | Secondary button style | Best for supportive controls (e.g., additional filters); use sparingly when the UI is already simple. |

<details>
<summary>Code example</summary>

```tsx
  <ButtonGroup variant="primary">
    <ButtonGroup.Button id="btn-1">Primary</ButtonGroup.Button>
  </ButtonGroup>
  <ButtonGroup variant="secondary">
    <ButtonGroup.Button id="btn-2">Secondary</ButtonGroup.Button>
  </ButtonGroup>
  ```
</details>

### size

Size of the buttons.

| Value | Example                                                                                           | Description           |
| ----- | ------------------------------------------------------------------------------------------------- | --------------------- |
| `xs`  | <ButtonGroup size="xs"><ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button></ButtonGroup> | Extra small size      |
| `sm`  | <ButtonGroup size="sm"><ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button></ButtonGroup> | Small size            |
| `md`  | <ButtonGroup size="md"><ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button></ButtonGroup> | Medium size (default) |
| `lg`  | <ButtonGroup size="lg"><ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button></ButtonGroup> | Large size            |

<details>
<summary>Code example</summary>

```tsx
  <ButtonGroup size="xs">
    <ButtonGroup.Button id="btn-1">XS</ButtonGroup.Button>
  </ButtonGroup>
  <ButtonGroup size="sm">
    <ButtonGroup.Button id="btn-2">SM</ButtonGroup.Button>
  </ButtonGroup>
  ```
</details>

### showIcon

Whether to show selection icons in multiple selection mode.

| Type      | Example                                                                                                                                                               | Description                                       |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `boolean` | <ButtonGroup multiple showIcon><ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button><ButtonGroup.Button id="btn-2">Option 2</ButtonGroup.Button></ButtonGroup> | Shows check/plus icons in multiple selection mode |

<details>
<summary>Code example</summary>

```tsx
  <ButtonGroup multiple showIcon>
    <ButtonGroup.Button id="btn-1">Option 1</ButtonGroup.Button>
    <ButtonGroup.Button id="btn-2">Option 2</ButtonGroup.Button>
  </ButtonGroup>
  ```
</details>

## Behavior

- ButtonGroup manages selection state internally or via controlled props.
- Single-select mode
  - Only one option can be selected at a time.
  - Selecting a new option deselects the previous one.
- Multi-select mode
  - Each button toggles independently.
  - Multiple options can be active simultaneously.
- When space is limited, the group may wrap into multiple rows.
- Keyboard interaction:
  - Arrow keys move focus within the group.
  - Space or Enter selects or toggles the focused option.

## Accessibility

- Provide a descriptive group label using `aria-label`, `aria-labelledby`, or visible text.
- Use `role="radiogroup"` for single-select patterns, or `role="group"` for multi-select/toggle patterns.
- In multi-select patterns, use aria-pressed on buttons to expose toggle state.
- Ensure full keyboard access (Tab, Arrow keys, Enter, Space).<br />
  (WCAG 2.1.1 — [Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html))

## Implementation Examples

### ButtonGroup with line breaks

*[Live preview](https://design-system.yle.fi/docs/components/ButtonGroup/)*

<details>
<summary>Code example</summary>

```tsx
  <div style={{ maxWidth: '400px' }}>
    <ButtonGroup>
      <ButtonGroup.Button id="mon">Maanantai</ButtonGroup.Button>
      <ButtonGroup.Button id="tue">Tiistai</ButtonGroup.Button>
      <ButtonGroup.Button id="wed">Keskiviikko</ButtonGroup.Button>
      <ButtonGroup.Button id="thu">Torstai</ButtonGroup.Button>
      <ButtonGroup.Button id="fri">Perjantai</ButtonGroup.Button>
      <ButtonGroup.Button id="sat">Lauantai</ButtonGroup.Button>
      <ButtonGroup.Button id="sun">Sunnuntai</ButtonGroup.Button>
    </ButtonGroup>
  </div>
  ```
</details>

### ButtonGroup with SwiperJS

Drag or swipe the container to see all the buttons

*[Live preview](https://design-system.yle.fi/docs/components/ButtonGroup/)*

### Disabled ButtonGroup with significant selected option

While it's possible to disable all buttons in the button group, sometimes it's important to keep a significant
selected option visible (for example in tab-like single select scenarios). In this case, you can use the
`aria-disabled` attribute to indicate that the selected option in the button group is disabled,
but still make the selected option visible to the user. Use isDisabled prop for the unselected buttons.

*[Live preview](https://design-system.yle.fi/docs/components/ButtonGroup/)*

<details>
<summary>Code example</summary>

```tsx
  <div style={{ maxWidth: '400px' }}>
    <ButtonGroup value="all">
      <ButtonGroup.Button id="all" aria-disabled="true">
        <span>Kaikki</span>
      </ButtonGroup.Button>
      <ButtonGroup.Button isDisabled id="own">
        <span>Omat</span>
      </ButtonGroup.Button>
      <ButtonGroup.Button isDisabled id="fav">
        <span>Suosikit</span>
      </ButtonGroup.Button>
    </ButtonGroup>
    <div style={{ marginTop: '8px' }}>
      <Link href="#">Kirjaudu sisään Yle Tunnuksella</Link> ja näe henkilökohtaiset suosituksesi.
    </div>
  </div>
  ```
</details>

## API Reference

### ButtonGroup Props

The ButtonGroup component accepts all standard HTML `<div>` attributes (except `onChange`) in addition to the following props:

| Prop           | Type                                  | Required | Default     | Description                                |
| -------------- | ------------------------------------- | -------- | ----------- | ------------------------------------------ |
| `children`     | `React.ReactNode`                     | Yes      | —           | ButtonGroup.Button components to display   |
| `multiple`     | `boolean`                             | No       | `false`     | Whether multiple buttons can be selected   |
| `defaultValue` | `string \| string[]`                  | No       | —           | Initial selected value(s) for uncontrolled |
| `value`        | `string \| string[]`                  | No       | —           | Current selected value(s) for controlled   |
| `onChange`     | `(value: string \| string[]) => void` | No       | —           | Callback fired when selection changes      |
| `variant`      | `'primary' \| 'secondary'`            | No       | `'primary'` | Visual style variant                       |
| `size`         | `'xs' \| 'sm' \| 'md' \| 'lg'`        | No       | —           | Size of the buttons                        |
| `showIcon`     | `boolean`                             | No       | —           | Shows selection icons in multiple mode     |

### ButtonGroup.Button Props

The ButtonGroup.Button component accepts all standard `Button` props (except `iconAfter`) in addition to the following props:

| Prop       | Type              | Required | Default | Description                              |
| ---------- | ----------------- | -------- | ------- | ---------------------------------------- |
| `id`       | `string`          | Yes      | —       | Unique identifier for tracking selection |
| `children` | `React.ReactNode` | Yes      | —       | Button content                           |

### Type Definitions

```tsx
export interface ButtonGroupDSProps {
  children: React.ReactNode;
  multiple?: boolean;
  defaultValue?: string | string[];
  value?: string | string[];
  onChange?: (value: string | string[]) => void;
  variant?: 'primary' | 'secondary';
  size?: 'xs' | 'sm' | 'md' | 'lg';
  showIcon?: boolean;
}

export type ButtonGroupProps = Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> &
  ButtonGroupDSProps;

export interface ButtonGroupButtonDSProps {
  id: string;
  children: React.ReactNode;
}

export type ButtonGroupButtonProps = Omit<ButtonProps<'button' | 'a'>, 'iconAfter'> &
  ButtonGroupButtonDSProps;
```

## Related Components

- [Button](../Button/Button.md) – ButtonGroup.Button extends Button functionality
- [RadioGroup](../Radio/Radio.md) – Alternative for single-selection groups with form semantics
- [CheckboxGroup](../Checkbox/Checkbox.md) – Alternative for multiple selection in forms
- [DropdownMenuGroup](../DropdownMenuGroup/DropdownMenuGroup.md) – Use when the option list is long or space is limited
- [NavigationTabs](../NavigationTabs/NavigationTabs.md) – Page-level navigation between major sections
- [SectionTabs](../SectionTabs/SectionTabs.md) – Switching content within a single page or section

# Checkbox

A Checkbox lets users select one or more options from a limited set, while a Checkbox Group combines related checkboxes under a shared label with optional helper text and validation.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=285-1933)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-checkbox--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Checkbox/Checkbox.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/Checkbox/)*

<details open>
<summary>Code example</summary>

```tsx
import { Checkbox, CheckboxGroup } from '@yleisradio/yds-components-react';

<CheckboxGroup
  id="colors"
  name="colors"
  label="Select colors"
  selectedValue={["red", "blue"]}
  onValueChange={() => {}}
>
  <Checkbox value="red" label="Red" name="colors" />
  <Checkbox value="green" label="Green" name="colors" />
  <Checkbox value="blue" label="Blue" name="colors" />
  <Checkbox value="yellow" label="Yellow" name="colors" />
</CheckboxGroup>
```
</details>

## Why to use

Checkboxes enable independent, multi-select decisions in forms and filters. A Checkbox Group clarifies context with a shared label, optional description, and unified validation, while each Checkbox represents a separate, non-exclusive choice.

## When to use

Use a Checkbox when users can select zero, one, or many independent options. Use a CheckboxGroup when related checkboxes should share a single label, description, or validation.

> **Do**
> - Use when multiple options can be selected at the same time (including none).
> - Use for filters, preferences, permissions, and multi-select form inputs.
> - Use a CheckboxGroup when options belong to the same question and should be validated together.

> **Don’t**
> - Don’t use for a single required choice — use [Radio](../Radio/Radio.md) instead.
> - Don’t use for an instant on/off UI state — use [Switch](../Switch/Switch.md) instead.
> - Don’t use when selecting one option should automatically deselect others — use [RadioGroup](../Radio/Radio.md).

## Content Guidelines
Checkbox labels should be short, scannable, and easy to compare. Use the group label to describe what the options have in common, and the group description for any necessary context.

> **Do**
> - Use a clear group label that describes the shared purpose of the options.
> - Keep option labels short and specific (e.g., “Evästeasetukset”).
> - Keep option wording parallel so choices are easy to compare.
> - Put instructions and clarifications in the group description, not inside each option label.

> **Don’t**
> - Don’t use long sentences as option labels — move detail into the description.
> - Don’t create overlapping or ambiguous options.
> - Don’t repeat the group label in each option.
> - Don’t mix unrelated options in the same CheckboxGroup.

## Anatomy

![Checkbox anatomy](../../img/checkbox-group-anatomy.svg)

1. **Group label** – Describes the set of related options.
2. **Description** – Optional helper text below the label.
3. **Checkbox control** – Square selector; multiple can be checked.
4. **Option label** – Text linked to each checkbox option.

## Key Checkbox Props

Use the following props to customize the Checkbox component to fit your needs.

### variant

| Value | Example | Description |
|-------|---------|-------------|
| `primary` | <Checkbox name="demoA" value="a" label="Primary" defaultChecked /> | Default style for most use cases. |
| `secondary` | <Checkbox variant="secondary" name="demoB" value="b" label="Secondary" defaultChecked /> | Uses highlight color for the control. |

<details>
<summary>Code example</summary>

```tsx
<Checkbox name="demo" value="primary" label="Primary" variant="primary" defaultChecked />
<Checkbox name="demo" value="secondary" label="Secondary" variant="secondary" defaultChecked />
```
</details>

### isDisabled
Non-interactive, dimmed styling.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Checkbox name="demo" value="x" label="Disabled" isDisabled /> | Temporarily prevents user interaction. |

<details>
<summary>Code example</summary>

```tsx
<Checkbox name="demo" value="x" label="Disabled" isDisabled />
```
</details>

### hideLabel

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Checkbox name="demo" value="hidden" label="Hidden label" hideLabel /> | Visually hides label but keeps it accessible. |

<details>
<summary>Code example</summary>

```tsx
<Checkbox name="demo" value="hidden" label="Hidden label" hideLabel />
```
</details>

### controlAlign

| Value | Example | Description |
|-------|---------|-------------|
| `start` | <Checkbox name="alignA" value="a" label="Start aligned" controlAlign="start" /> | Positions the control before the label text. |
| `end` | <Checkbox name="alignB" value="b" label="End aligned" controlAlign="end" /> | Positions the control after the label text. |

<details>
<summary>Code example</summary>

```tsx
<Checkbox name="align" value="start" label="Start aligned" controlAlign="start" />
<Checkbox name="align" value="end" label="End aligned" controlAlign="end" />
```
</details>

### error
Applies error styling to the individual checkbox.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Checkbox name="demo" value="err" label="Error" error /> | Marks checkbox with error styling. |

<details>
<summary>Code example</summary>

```tsx
<Checkbox name="demo" value="err" label="Error" error />
```
</details>

### checked / defaultChecked
Standard HTML checked control for controlled or uncontrolled usage.

| Prop | Example | Description |
|------|---------|-------------|
| `defaultChecked` | <Checkbox name="demo" value="one" label="Uncontrolled default" defaultChecked /> | Sets initial checked state. |
| `checked` | <Checkbox name="demo" value="two" label="Controlled" checked onChange={() => {}} /> | Controlled state—must provide onChange handler. |

<details>
<summary>Code example</summary>

```tsx
// Uncontrolled
<Checkbox name="demo" value="one" label="Uncontrolled default" defaultChecked />

// Controlled
const [isChecked, setChecked] = useState(true);
<Checkbox
  name="demo"
  value="two"
  label="Controlled"
  checked={isChecked}
  onChange={(e) => setChecked(e.currentTarget.checked)}
/>
```
</details>

## Key CheckboxGroup Props

Use the following props to customize the CheckboxGroup component to fit your needs.

### label

| Type | Example | Description |
|------|---------|-------------|
| `string` | <CheckboxGroup id="fruits" name="fruits" label="Fruits" selectedValue={[]} onValueChange={() => {}}><Checkbox value="apple" label="Apple" name="fruits" /><Checkbox value="pear" label="Pear" name="fruits" /></CheckboxGroup> | Text label describing the purpose of the group. |

<details>
<summary>Code example</summary>

```tsx
<CheckboxGroup id="fruits" name="fruits" label="Fruits" selectedValue={[]} onValueChange={() => {}}>
  <Checkbox value="apple" label="Apple" name="fruits" />
  <Checkbox value="pear" label="Pear" name="fruits" />
</CheckboxGroup>
```
</details>

### description
Helper guidance placed below group label.

| Type | Example | Description |
|------|---------|-------------|
| `string` | <CheckboxGroup id="fruits" name="fruits" label="Fruits" description="Select any that apply" selectedValue={[]} onValueChange={() => {}}><Checkbox value="apple" label="Apple" name="fruits" /><Checkbox value="pear" label="Pear" name="fruits" /></CheckboxGroup> | Provides additional context or instructions for the group. |

<details>
<summary>Code example</summary>

```tsx
<CheckboxGroup
  id="fruits"
  name="fruits"
  label="Fruits"
  description="Select any that apply"
  selectedValue={[]}
  onValueChange={() => {}}
>
  <Checkbox value="apple" label="Apple" name="fruits" />
  <Checkbox value="pear" label="Pear" name="fruits" />
</CheckboxGroup>
```
</details>

### selectedValue
Array of currently selected checkbox values (controlled state).

| Type | Example | Description |
|------|---------|-------------|
| `string[]` | <CheckboxGroup id="c" name="c" selectedValue={["green"]} onValueChange={() => {}}><Checkbox value="red" label="Red" name="colors2" /><Checkbox value="green" label="Green" name="colors2" /></CheckboxGroup> | Controlled selection values. |

<details>
<summary>Code example</summary>

```tsx
<CheckboxGroup
  id="colors2"
  name="colors2"
  label="Colours"
  selectedValue={['green']}
  onValueChange={(next) => {}}
>
  <Checkbox value="red" label="Red" name="colors2" />
  <Checkbox value="green" label="Green" name="colors2" />
  <Checkbox value="blue" label="Blue" name="colors2" />
</CheckboxGroup>
```
</details>

### errorMessage

| Type | Example | Description |
|------|---------|-------------|
| `string` | <CheckboxGroup id="fruits" name="fruits" label="Fruits" errorMessage="Select at least one" selectedValue={[]} onValueChange={() => {}}><Checkbox value="apple" label="Apple" name="fruits" /><Checkbox value="pear" label="Pear" name="fruits" /></CheckboxGroup> | Shows an error message and applies error styles to the group. |

<details>
<summary>Code example</summary>

```tsx
<CheckboxGroup
  id="fruits"
  name="fruits"
  label="Fruits"
  errorMessage="Select at least one"
  selectedValue={[]}
  onValueChange={() => {}}
>
  <Checkbox value="apple" label="Apple" name="fruits" />
  <Checkbox value="pear" label="Pear" name="fruits" />
</CheckboxGroup>
```
</details>

### labelOptions
Pass-through props to underlying `FormGroupLabel` (e.g., optionalLabel, isHidden).

| Type | Example | Description |
|------|---------|-------------|
| `FormGroupLabelProps` | <CheckboxGroup id="veg" name="veg" label="Vegetables" labelOptions={{ optionalLabel: '(Optional)' }} selectedValue={[]} onValueChange={() => {}}><Checkbox value="apple" label="Apple" name="fruits" /><Checkbox value="pear" label="Pear" name="fruits" /></CheckboxGroup> | Customizes group label display. |

<details>
<summary>Code example</summary>

```tsx
<CheckboxGroup
  id="fruits"
  name="fruits"
  label="Fruits"
  labelOptions={{ optionalLabel: '(Optional)' }}
  selectedValue={[]}
  onValueChange={() => {}}
>
  <Checkbox value="apple" label="Apple" name="fruits" />
  <Checkbox value="pear" label="Pear" name="fruits" />
</CheckboxGroup>
```
</details>

## Behavior

- Each checkbox is independent; multiple can be selected or none.
- Use a Checkbox Group to bind related options under one label/description and to show a single error message.
- Indeterminate visually represents a partial/unknown selection for parent items (not submitted as a value).
- Avoid immediate side effects on check/uncheck; apply changes on submit (use Switch for instant toggles).
- Disabled items remain visible but non-interactive.

## Accessibility

- Every Checkbox needs a visible label or accessible name.<br />([WCAG 3.3.2 — Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions))
- Group related checkboxes under a group label that describes the overall purpose.<br /> ([WCAG 1.3.1 — Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships))
- Keyboard: Tab/Shift+Tab move focus; Space toggles the focused checkbox.<br /> ([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard))
- Link helper or error text with aria-describedby; announce errors programmatically.<br /> ([WCAG 4.1.3 — Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages)).

## Implementation examples

### With description

*[Live preview](https://design-system.yle.fi/docs/components/Checkbox/)*

<details open>
<summary>Code example</summary>

```tsx
<CheckboxGroup
  id="learning"
  name="learning"
  label="Preferred learning methods"
  description="Select any methods that help you study effectively"
  selectedValue={["online", "group"]}
  onValueChange={() => {}}
>
  <Checkbox value="online" label="Online self-paced" name="learning" />
  <Checkbox value="classroom" label="Classroom" name="learning" />
  <Checkbox value="hybrid" label="Hybrid" name="learning" />
  <Checkbox value="group" label="Group discussions" name="learning" />
  <Checkbox value="independent" label="Independent study" name="learning" />
</CheckboxGroup>
```
</details>

### With error message

*[Live preview](https://design-system.yle.fi/docs/components/Checkbox/)*

<details open>
<summary>Code example</summary>

```tsx
<CheckboxGroup
  id="learning-error"
  name="learning-error"
  label="Preferred learning methods"
  description="Select any methods that help you study effectively"
  errorMessage="Please select at least one method"
  selectedValue={[]}
  onValueChange={() => {}}
>
  <Checkbox value="online" label="Online self-paced" name="learning-error" />
  <Checkbox value="classroom" label="Classroom" name="learning-error" />
  <Checkbox value="hybrid" label="Hybrid" name="learning-error" />
  <Checkbox value="group" label="Group discussions" name="learning-error" />
  <Checkbox value="independent" label="Independent study" name="learning-error" />
</CheckboxGroup>
```
</details>

### Indeterminate state
Indeterminate state indicates a partial selection (e.g., parent with some children selected). It does not submit a value—purely visual and must be set via ref.
Rarely used.

*[Live preview](https://design-system.yle.fi/docs/components/Checkbox/)*

## API Reference

### Props

#### Checkbox

The Checkbox component accepts all standard HTML `<input>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `isDisabled` | `boolean` | No | `false` | |
| `variant` | `'primary' \| 'secondary'` | No | `'primary'` | |
| `value` | `string` | No | — | |
| `name` | `string` | Yes | — | |
| `label` | `ReactNode` | Yes | — | |
| `error` | `boolean` | No | `false` | |
| `hideLabel` | `boolean` | No | `false` | |
| `useUnderlay` | `boolean` | No | `false` | |
| `controlAlign` | `InputControlAlign` | No | `'start'` | |

#### CheckboxGroup

The CheckboxGroup component accepts the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `id` | `string` | Yes | — | |
| `name` | `string` | Yes | — | |
| `selectedValue` | `string[]` | Yes | — | |
| `errorMessage` | `string` | No | — | |
| `label` | `string` | No | — | |
| `labelOptions` | `FormGroupLabelProps` | No | — | |
| `description` | `string` | No | — | |
| `children` | `ReactNode` | Yes | — | |
| `onValueChange` | `(value: string[]) => void` | Yes | — | |

### Type Definitions

#### Checkbox

```tsx
export type InputControlAlign = 'start' | 'end';

export interface CheckboxDSProps {
  isDisabled?: boolean;
  variant?: 'primary' | 'secondary';
  value?: string;
  name: string;
  label: ReactNode;
  error?: boolean;
  hideLabel?: boolean;
  useUnderlay?: boolean;
  controlAlign?: InputControlAlign;
}

export type CheckboxProps = InputHTMLAttributes<HTMLInputElement> & CheckboxDSProps;
```

#### CheckboxGroup

```tsx
export interface CheckboxGroupDSProps {
  id: string;
  name: string;
  selectedValue: string[];
  errorMessage?: string;
  label?: string;
  labelOptions?: FormGroupLabelProps;
  description?: string;
  children: ReactNode;
  onValueChange: (value: string[]) => void;
}

export type CheckboxGroupProps = CheckboxGroupDSProps;
```

## Related Components

- [Radio](../Radio/Radio.md) – For single mandatory choice.
- [Switch](../Switch/Switch.md) – For immediate on/off toggles.
- [TagFilter](../TagFilter/TagFilter.md) – For removable selection chips.
- [ButtonGroup](../ButtonGroup/ButtonGroup.md) – Alternative multi-selection pattern using buttons.

# ChoiceBox

ChoiceBox is a checkbox wrapped in a card-like container. It's used in question/answer scenarios where it's useful to show additional information for each option.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=3588-5824)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-choicebox--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/ChoiceBox/ChoiceBox.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/ChoiceBox/)*

<details open>
<summary>Code example</summary>

```tsx
import { ChoiceBox } from '@yleisradio/yds-components-react';

<ChoiceBox name="choice-1" label="Option 1" />
```
</details>

## Why to use

ChoiceBox gives you a consistent, accessible way to present multi-select options in a card layout. It extends [Checkbox](../Checkbox/Checkbox.md) with an optional icon, extra content below the label, and right/wrong answer indicator — so you can highlight options or show results without building custom layouts.

## When to use

Use ChoiceBox when options need a card-style container: each choice has an icon, a short description, or should stand out visually. Use plain Checkbox when options are simple labels in a list.

> **Do**
> - Use for question/answer patterns.

> **Don't**
> - Don't use as a regular form component. Use [Checkbox](../Checkbox/Checkbox.md) instead.

## Content guidelines

Keep labels short and parallel. Put longer explanations in the `content` prop or in a group description.

> **Do**
> - Use the optional icon and status to tell the user if the answer is correct or incorrect.
> - Use `content` for brief supporting text, not for the main choice label.

> **Don't**
> - Don't use long sentences as the main label — move detail into `content` or description.

## Key ChoiceBox Props

Use these props to configure the ChoiceBox component.

### label

Label text or content for the checkbox.

| Type              | Example                                        | Description                    |
| ----------------- | ---------------------------------------------- | ------------------------------ |
| `React.ReactNode` | <ChoiceBox name="option-1" label="Option 1" /> | Label content for the checkbox |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceBox name="option-1" label="Option 1" />
  <ChoiceBox name="option-2" label={<strong>Bold Option</strong>} />
  ```
</details>

### status

Visual status indicator for the choice box.

| Value     | Example                                                       | Description            |
| --------- | ------------------------------------------------------------- | ---------------------- |
| `success` | <ChoiceBox name="option-1" label="Option" status="success" /> | Success status styling |
| `error`   | <ChoiceBox name="option-1" label="Option" status="error" />   | Error status styling   |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceBox name="option-1" label="Option" status="success" />
  <ChoiceBox name="option-2" label="Option" status="error" />
  ```
</details>

### controlAlign

Alignment of the checkbox control relative to the content.

| Value   | Example                                                           | Description                 |
| ------- | ----------------------------------------------------------------- | --------------------------- |
| `start` | <ChoiceBox name="option-1" label="Option" controlAlign="start" /> | Aligns control to the start |
| `end`   | <ChoiceBox name="option-1" label="Option" controlAlign="end" />   | Aligns control to the end   |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceBox name="option-1" label="Option" controlAlign="start" />
  <ChoiceBox name="option-2" label="Option" controlAlign="end" />
  ```
</details>

### containerSize

Size of the choice container.

| Value | Example                                                         | Description                     |
| ----- | --------------------------------------------------------------- | ------------------------------- |
| `sm`  | <ChoiceBox name="option-1" label="Option" containerSize="sm" /> | Small container size            |
| `md`  | <ChoiceBox name="option-1" label="Option" containerSize="md" /> | Medium container size (default) |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceBox name="option-1" label="Option" containerSize="sm" />
  <ChoiceBox name="option-2" label="Option" containerSize="md" />
  ```
</details>

### icon

Optional icon to display in the choice container.

| Type              | Example                                                       | Description                                                                                        |
| ----------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `React.ReactNode` | <ChoiceBox name="option-1" label="Option" icon={<Check />} /> | Icon element to display. Use with `status` to tell the user if the answer is correct or incorrect. |

<details>
<summary>Code example</summary>

```tsx
import { Check } from '@yleisradio/yds-icons-react';

<ChoiceBox name="option-1" label="Option" icon={<Check />} />
```
</details>

### content

Additional content to display below the checkbox and icon.

> **Warning**
> The content area has no built-in padding. Handle spacing and layout yourself when showing extra content such as text. This keeps images flush with the edges when they are used as content.

| Type              | Example                                                                                                      | Description                          |
| ----------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| `React.ReactNode` | <ChoiceBox name="option-1" label="Option" content={<p style={{ margin: 16 }}>Some additional content</p>} /> | Additional content below the control |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceBox
    name="option-1"
    label="Option"
    content={<p style={{ margin: 16 }}>Some additional content</p>}
  />
  ```
</details>

### isDisabled

Whether the checkbox is disabled.

| Type      | Example                                                 | Description           |
| --------- | ------------------------------------------------------- | --------------------- |
| `boolean` | <ChoiceBox name="option-1" label="Option" isDisabled /> | Disables the checkbox |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceBox name="option-1" label="Option" isDisabled />
  ```
</details>

### variant

Visual style variant of the checkbox.

| Value       | Example                                                                  | Description               |
| ----------- | ------------------------------------------------------------------------ | ------------------------- |
| `primary`   | <ChoiceBox name="option-1" label="Option" variant="primary" checked />   | Primary variant (default) |
| `secondary` | <ChoiceBox name="option-2" label="Option" variant="secondary" checked /> | Secondary variant         |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceBox name="option-1" label="Option" variant="primary" />
  <ChoiceBox name="option-2" label="Option" variant="secondary" />
  ```
</details>

### useUnderlay

Whether to show an underlay effect.

| Type      | Example                                                  | Description           |
| --------- | -------------------------------------------------------- | --------------------- |
| `boolean` | <ChoiceBox name="option-1" label="Option" useUnderlay /> | Shows underlay effect |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceBox name="option-1" label="Option" useUnderlay />
  ```
</details>

### background

Background style variant of the choice container.

| Type      | Example                                                           | Description        |
| --------- | ----------------------------------------------------------------- | ------------------ |
| `default` | <ChoiceBox name="option-1" label="Option" background="default" /> | Default background |
| `variant` | <ChoiceBox name="option-2" label="Option" background="variant" /> | Variant background |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceBox name="option-1" label="Option" background="default" />
  <ChoiceBox name="option-2" label="Option" background="variant" />
  ```
</details>

## Behavior

- Each ChoiceBox is independent; multiple can be selected or none. Use the same `name` for options that belong to the same question.
- Checked state is controlled via `checked` / `defaultChecked`; use `onChange` for controlled usage.
- The container has an underlay by default (`useUnderlay={true}`).
- `status="success"` or `status="error"` applies visual feedback.
- Disabled options are non-interactive but remain visible.

## Accessibility

- Every ChoiceBox must have a visible or programmatically associated label (use `label` with meaningful accessible name).<br />([WCAG 3.3.2 — Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions))
- Group related options under a shared question or fieldset so the relationship is clear.<br />([WCAG 1.3.1 — Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships))
- Keyboard: Tab/Shift+Tab move focus; Space toggles the focused checkbox.<br />([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard))

## API Reference

### Props

The ChoiceBox component accepts all standard HTML `<input>` attributes (except `size`) in addition to the following props:

| Prop            | Type                       | Required | Default     | Description                         |
| --------------- | -------------------------- | -------- | ----------- | ----------------------------------- |
| `name`          | `string`                   | Yes      | —           | Name attribute for form submission  |
| `label`         | `React.ReactNode`          | Yes      | —           | Label content for the checkbox      |
| `status`        | `'success' \| 'error'`     | No       | —           | Visual status indicator             |
| `controlAlign`  | `'start' \| 'end'`         | No       | —           | Alignment of checkbox control       |
| `containerSize` | `'sm' \| 'md'`             | No       | —           | Size of the choice container        |
| `icon`          | `React.ReactNode`          | No       | —           | Optional icon to display            |
| `content`       | `React.ReactNode`          | No       | —           | Additional content below control    |
| `isDisabled`    | `boolean`                  | No       | `false`     | Whether the checkbox is disabled    |
| `variant`       | `'primary' \| 'secondary'` | No       | `'primary'` | Visual style variant                |
| `value`         | `string`                   | No       | —           | Value attribute for form submission |
| `hideLabel`     | `boolean`                  | No       | `false`     | Visually hides the label            |
| `useUnderlay`   | `boolean`                  | No       | `true`      | Shows underlay effect               |
| `background`    | `'default' \| 'variant'`   | No       | `'default'` | Background style variant            |

### Type Definitions

```tsx
export type ChoiceContainerStatus = 'success' | 'error';
export type ChoiceContainerBackground = 'default' | 'variant';
export type InputControlAlign = 'start' | 'end';
export type ChoiceContainerSize = 'sm' | 'md';
export type ChoiceHTMLInputAttributes = Omit<InputHTMLAttributes<HTMLInputElement>, 'size'>;

export interface ChoiceBoxDSProps {
  status?: ChoiceContainerStatus;
  controlAlign?: InputControlAlign;
  containerSize?: ChoiceContainerSize;
  icon?: React.ReactNode;
  content?: React.ReactNode;
  background?: ChoiceContainerBackground;
}

export type CheckboxPropsNoError = Omit<CheckboxProps, 'error'>;

export type ChoiceBoxProps = ChoiceHTMLInputAttributes & ChoiceBoxDSProps & CheckboxPropsNoError;
```

## Related Components

- [Checkbox](../Checkbox/Checkbox.md) – Base checkbox component for grouping multiple selections with a shared label and validation.
- [ChoiceButton](../ChoiceButton/ChoiceButton.md) – Card-style single-select option (radio).

# ChoiceButton

ChoiceButton is a radio button wrapped in a card-like container. It's used in question/answer scenarios where it's useful to show additional information for each option.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=3696-719)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-choicebutton--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/ChoiceButton/ChoiceButton.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/ChoiceButton/)*

<details open>
<summary>Code example</summary>

```tsx
import { ChoiceButton } from '@yleisradio/yds-components-react';

<ChoiceButton name="choice-1" label="Option 1" />
```
</details>

## Why to use

ChoiceButton gives you a consistent, accessible way to present single-select options in a card layout. It extends [Radio](../Radio/Radio.md) with an optional icon, extra content below the label, and right/wrong answer indicator — so you can highlight options or show results without building custom layouts.

## When to use

Use ChoiceButton when options need a card-style container: each choice has an icon, a short description, or should stand out visually. Use plain Radio (and RadioGroup) when options are simple labels in a list.

> **Do**
> - Use for question/answer patterns.

> **Don't**
> - Don't use as a regular form component. Use [Radio](../Radio/Radio.md) instead.

## Content guidelines

Keep labels short and parallel. Put longer explanations in the `content` prop or in a group description.

> **Do**
> - Use the optional icon and status to tell the user if the answer is correct or incorrect.
> - Use `content` for brief supporting text, not for the main choice label.

> **Don't**
> - Don't use long sentences as the main label — move detail into `content` or description.

## Key ChoiceButton Props

Use these props to configure the ChoiceButton component.

### label

Label text or content for the radio button.

| Type              | Example                                               | Description                        |
| ----------------- | ----------------------------------------------------- | ---------------------------------- |
| `React.ReactNode` | <ChoiceButton name="option-group" label="Option 1" /> | Label content for the radio button |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceButton name="option-group" label="Option 1" />
  <ChoiceButton name="option-group" label={<strong>Bold Option</strong>} />
  ```
</details>

### status

Visual status indicator for the choice button.

| Value     | Example                                                              | Description            |
| --------- | -------------------------------------------------------------------- | ---------------------- |
| `success` | <ChoiceButton name="option-group" label="Option" status="success" /> | Success status styling |
| `error`   | <ChoiceButton name="option-group" label="Option" status="error" />   | Error status styling   |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceButton name="option-group" label="Option" status="success" />
  <ChoiceButton name="option-group" label="Option" status="error" />
  ```
</details>

### controlAlign

Alignment of the radio control relative to the content.

| Value   | Example                                                                  | Description                 |
| ------- | ------------------------------------------------------------------------ | --------------------------- |
| `start` | <ChoiceButton name="option-group" label="Option" controlAlign="start" /> | Aligns control to the start |
| `end`   | <ChoiceButton name="option-group" label="Option" controlAlign="end" />   | Aligns control to the end   |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceButton name="option-group" label="Option" controlAlign="start" />
  <ChoiceButton name="option-group" label="Option" controlAlign="end" />
  ```
</details>

### containerSize

Size of the choice container.

| Value | Example                                                                | Description                     |
| ----- | ---------------------------------------------------------------------- | ------------------------------- |
| `sm`  | <ChoiceButton name="option-group" label="Option" containerSize="sm" /> | Small container size            |
| `md`  | <ChoiceButton name="option-group" label="Option" containerSize="md" /> | Medium container size (default) |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceButton name="option-group" label="Option" containerSize="sm" />
  <ChoiceButton name="option-group" label="Option" containerSize="md" />
  ```
</details>

### icon

Optional icon to display in the choice container.

| Type              | Example                                                              | Description             |
| ----------------- | -------------------------------------------------------------------- | ----------------------- |
| `React.ReactNode` | <ChoiceButton name="option-group" label="Option" icon={<Check />} /> | Icon element to display |

<details>
<summary>Code example</summary>

```tsx
import { Check } from '@yleisradio/yds-icons-react';

<ChoiceButton name="option-group" label="Option" icon={<Check />} />
```
</details>

### content

Additional content to display below the radio button and icon.

> **Warning**
> The content area has no built-in padding. Handle spacing and layout yourself when showing extra content such as text. This keeps images flush with the edges when they are used as content.

| Type              | Example                                                                                                             | Description                          |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `React.ReactNode` | <ChoiceButton name="option-group" label="Option" content={<p style={{ margin: 16 }}>Some additional content</p>} /> | Additional content below the control |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceButton
    name="option-group"
    label="Option"
    content={<p style={{ margin: 16 }}>Some additional content</p>}
  />
  ```
</details>

### isDisabled

Whether the radio button is disabled.

| Type      | Example                                                        | Description               |
| --------- | -------------------------------------------------------------- | ------------------------- |
| `boolean` | <ChoiceButton name="option-group" label="Option" isDisabled /> | Disables the radio button |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceButton name="option-group" label="Option" isDisabled />
  ```
</details>

### variant

Visual style variant of the radio button.

| Value       | Example                                                                           | Description               |
| ----------- | --------------------------------------------------------------------------------- | ------------------------- |
| `primary`   | <ChoiceButton name="option-group-1" label="Option" variant="primary" checked />   | Primary variant (default) |
| `secondary` | <ChoiceButton name="option-group-2" label="Option" variant="secondary" checked /> | Secondary variant         |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceButton name="option-group" label="Option" variant="primary" />
  <ChoiceButton name="option-group" label="Option" variant="secondary" />
  ```
</details>

### useUnderlay

Whether to show an underlay effect.

| Type      | Example                                                         | Description           |
| --------- | --------------------------------------------------------------- | --------------------- |
| `boolean` | <ChoiceButton name="option-group" label="Option" useUnderlay /> | Shows underlay effect |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceButton name="option-group" label="Option" useUnderlay />
  ```
</details>

### background

Background style variant of the choice container.

| Type      | Example                                                                  | Description        |
| --------- | ------------------------------------------------------------------------ | ------------------ |
| `default` | <ChoiceButton name="option-group" label="Option" background="default" /> | Default background |
| `variant` | <ChoiceButton name="option-group" label="Option" background="variant" /> | Variant background |

<details>
<summary>Code example</summary>

```tsx
  <ChoiceButton name="option-group" label="Option" background="default" />
  <ChoiceButton name="option-group" label="Option" background="variant" />
  ```
</details>

## Behavior

- All ChoiceButtons in a group share the same `name`; only one can be selected at a time.
- Selection is controlled via `checked` / `defaultChecked` and `onChange`, or via a parent like RadioGroup.
- The container has an underlay by default (`useUnderlay={true}`).
- `status="success"` or `status="error"` applies visual feedback.
- Disabled options are non-interactive but remain visible.

## Accessibility

- Every ChoiceButton must have a visible or programmatically associated label (use `label` or `hideLabel` with meaningful accessible name).<br />([WCAG 3.3.2 — Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions))
- Group related options under a shared name and, when possible, a fieldset or group label so the relationship is clear.<br />([WCAG 1.3.1 — Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships))
- Keyboard: Tab/Shift+Tab move focus between options; Arrow keys move between radio buttons in the same group; Space selects the focused option.<br />([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard))

## Implementation examples

### Abitreenit example

*[Live preview](https://design-system.yle.fi/docs/components/ChoiceButton/)*

## API Reference

### Props

The ChoiceButton component accepts all standard HTML `<input>` attributes (except `size`) in addition to the following props:

| Prop            | Type                       | Required | Default     | Description                               |
| --------------- | -------------------------- | -------- | ----------- | ----------------------------------------- |
| `name`          | `string`                   | Yes      | —           | Name attribute for grouping radio buttons |
| `label`         | `React.ReactNode`          | Yes      | —           | Label content for the radio button        |
| `status`        | `'success' \| 'error'`     | No       | —           | Visual status indicator                   |
| `controlAlign`  | `'start' \| 'end'`         | No       | —           | Alignment of radio control                |
| `containerSize` | `'sm' \| 'md'`             | No       | —           | Size of the choice container              |
| `icon`          | `React.ReactNode`          | No       | —           | Optional icon to display                  |
| `content`       | `React.ReactNode`          | No       | —           | Additional content below control          |
| `isDisabled`    | `boolean`                  | No       | `false`     | Whether the radio button is disabled      |
| `variant`       | `'primary' \| 'secondary'` | No       | `'primary'` | Visual style variant                      |
| `value`         | `string`                   | No       | —           | Value attribute for form submission       |
| `hideLabel`     | `boolean`                  | No       | `false`     | Visually hides the label                  |
| `useUnderlay`   | `boolean`                  | No       | `true`      | Shows underlay effect                     |
| `background`    | `'default' \| 'variant'`   | No       | —           | Background style variant                  |

### Type Definitions

```tsx
export type ChoiceContainerStatus = 'success' | 'error';
export type ChoiceContainerBackground = 'default' | 'variant';
export type InputControlAlign = 'start' | 'end';
export type ChoiceContainerSize = 'sm' | 'md';
export type ChoiceHTMLInputAttributes = Omit<InputHTMLAttributes<HTMLInputElement>, 'size'>;

export interface ChoiceButtonDSProps {
  status?: ChoiceContainerStatus;
  controlAlign?: InputControlAlign;
  containerSize?: ChoiceContainerSize;
  icon?: React.ReactNode;
  content?: React.ReactNode;
  background?: ChoiceContainerBackground;
}

export type RadioPropsNoError = Omit<RadioProps, 'error'>;

export type ChoiceButtonProps = ChoiceHTMLInputAttributes & ChoiceButtonDSProps & RadioPropsNoError;
```

## Related Components

- [Radio](../Radio/Radio.md) – Base radio component and RadioGroup that ChoiceButton extends
- [ChoiceBox](../ChoiceBox/ChoiceBox.md) – Card-style multi-select option (checkbox)
- [Checkbox](../Checkbox/Checkbox.md) – For multiple independent selections with CheckboxGroup

import {
  ComboboxTableExamples,
  ComboboxCustomItem,
} from 'yds-documentation/src/components/Examples/ComboboxTableExamples';

# ComboboxSingleSelect

A ComboboxSingleSelect is a combination of a text input and a list of options. It allows users to select a value from a predefined list or filter the list by typing.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=285-1943)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-comboboxsingleselect--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/ComboboxSingleSelect/ComboboxSingleSelect.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/ComboboxSingleSelect/)*
<details open>
<summary>Code example</summary>

```tsx
  import { ComboboxSingleSelect } from '@yleisradio/yds-components-react';

  <ComboboxSingleSelect
    label="Label"
    id="basic-usage"
    placeholder="Select an option"
    items={[
      { value: 'News' },
      { value: 'Sports' },
      { value: 'Culture', isDisabled: true }
    ]}
  />
  ```
</details>

## When to use

> **Do**
> - You have a list of options that users need to search and select from
> - The list is too long for a simple dropdown (typically 10+ items)
> - Users need to type to filter options quickly
> - You want to provide autocomplete functionality

> **Don't**
> - You have fewer than 10 options (use [Select](../Select/Select.md) instead)
> - Users need to select multiple items (use a multi-select pattern or [Checkbox group](../Checkbox/Checkbox.md))
> - The input should accept free-form text without selection (use [TextInput](../TextInput/TextInput.md))
> - You need a searchable list without single-value selection

## Content Guidelines

Combobox labels should be clear and descriptive. The placeholder should guide the user on what to type or select.

> **Do**
> - Use short, descriptive labels (e.g., "Country", "Language").
> - Use placeholder text to indicate that typing is allowed (e.g., "Type to search...").
> - Ensure item labels are consistent and easy to read.

## Anatomy

<div style={{ display: 'flex', justifyContent: 'center' }}>
  {/* Placeholder for anatomy image if available */}
  {/* ![Combobox anatomy](../../img/combobox-anatomy.svg) */}
</div>

1. **Label** – Describes the purpose of the field.
2. **Input field** – Area where users type to filter or view the selected value.
3. **Dropdown icon** – Indicates that there are options to choose from.
4. **Menu** – The list of filtered options.
5. **Clear button** (optional) – Allows clearing the selection.

## Key Props

Use the following props to customize the ComboboxSingleSelect component to fit your needs.

### items

The source of truth for the list of options. Each item must have a `value` property.

| Type             | Example                   | Description                |
| ---------------- | ------------------------- | -------------------------- |
| `ComboboxItem[]` | <ComboboxTableExamples /> | Array of items to display. |

<details>
<summary>Code example</summary>

```tsx
  <ComboboxSingleSelect label="Category" items={[{ value: 'News' }, { value: 'Sports' }]} />
  ```
</details>

### menuItemComponent

Allows customizing the rendering of menu items.

| Type                                        | Example                                                          | Description                         |
| ------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------- |
| `(props: ComboboxItemProps) => JSX.Element` | <ComboboxTableExamples menuItemComponent={ComboboxCustomItem} /> | Render function for each menu item. |

<details>
<summary>Code example</summary>

```tsx
  const CustomItem = ({
    item,
    index,
    highlightedIndex,
    selectedItem,
    itemProps,
  }: ComboboxItemProps) => {
    const isHighlighted = highlightedIndex === index;
    const isSelected = item.value === selectedItem?.value;

    return (
      <li
        {...itemProps}
        style={{
          padding: '8px 16px',
          cursor: 'pointer',
          backgroundColor: isHighlighted ? '#e0f2fe' : 'transparent',
          fontWeight: isSelected ? 'bold' : 'normal',
        }}
      >
        {item.value} {isSelected && '✓'}
      </li>
    );

};

  <ComboboxSingleSelect
    label="Maakunta"
    items={maakunnat}
    menuItemComponent={CustomItem}
  />
  ```
</details>

To keep the default look for some rows, import `DefaultComboboxMenuItem` and return it from the custom component:

```tsx
import {
  ComboboxSingleSelect,
  DefaultComboboxMenuItem,
  type ComboboxItemProps,
} from '@yleisradio/yds-components-react';

const MixedItem = (props: ComboboxItemProps) => {
  if (props.item.isHeading) {
    return <li>{props.item.value}</li>;
  }
  return <DefaultComboboxMenuItem {...props} />;
};

<ComboboxSingleSelect label="Maakunta" items={maakunnat} menuItemComponent={MixedItem} />;
```

### isDisabled

Non-interactive, dimmed styling.

| Type      | Example                              | Description                            |
| --------- | ------------------------------------ | -------------------------------------- |
| `boolean` | <ComboboxTableExamples isDisabled /> | Temporarily prevents user interaction. |

<details>
<summary>Code example</summary>

```tsx
  <ComboboxSingleSelect label="Disabled" isDisabled items={[{ value: 'News' }]} />
  ```
</details>

### errorMessage

| Type     | Example                                                        | Description                                                       |
| -------- | -------------------------------------------------------------- | ----------------------------------------------------------------- |
| `string` | <ComboboxTableExamples errorMessage="Please select a value" /> | Displays a validation error below the field. Sets `aria-invalid`. |

<details>
<summary>Code example</summary>

```tsx
  <ComboboxSingleSelect
    label="Category"
    errorMessage="Please select a value"
    items={[{ value: 'News' }]}
  />
  ```
</details>

### description

Helper guidance placed below the field.

| Type     | Example                                               | Description                                   |
| -------- | ----------------------------------------------------- | --------------------------------------------- |
| `string` | <ComboboxTableExamples description="Select one..." /> | Provides additional guidance below the field. |

<details>
<summary>Code example</summary>

```tsx
  <ComboboxSingleSelect label="Category" description="Select one..." items={[{ value: 'News' }]} />
  ```
</details>

## Behavior

- **Filtering**: By default, the component filters items based on a case-insensitive substring match.
- **Selection**: Clicking an item selects it and closes the menu. Pressing Enter on a highlighted item also selects it.
- **Blur**: Blurring the input without selecting an item may clear the input or keep the text depending on configuration.
- **Keyboard Navigation**: Users can navigate the menu using Arrow Up/Down keys and select with Enter.

## Accessibility

- The component uses `aria-expanded`, `aria-haspopup`, and `aria-activedescendant` to communicate state to screen readers.
- Keyboard navigation is fully supported.
- Ensure labels are associated with the input.

## Implementation examples

### Basic Usage (Uncontrolled)

The simplest way to use the combobox is with the `items` prop. The component handles filtering automatically. This can be useful
when the combobox is part of a form.

*[Live preview](https://design-system.yle.fi/docs/components/ComboboxSingleSelect/)*

### Controlled Mode (Custom Filtering)

When you provide `controlledItems`, `setControlledItems`, and `handleInputValueChange`, you manage the filtering logic yourself. This is useful for custom filtering (e.g., "starts with") or async loading.
Use this method if the combobox is tied to application state or needs to be controlled from outside the component.

*[Live preview](https://design-system.yle.fi/docs/components/ComboboxSingleSelect/)*

### Multi-select Pattern

You can build a multi-select experience on top of the single-select combobox by managing selected values externally and using `TagFilter` components.

_This is an experimental pattern and should be replaced with a proper multi-select Combobox component in the future._

*[Live preview](https://design-system.yle.fi/docs/components/ComboboxSingleSelect/)*

## API Reference

### Props

The ComboboxSingleSelect is based on the [TextInput](../TextInput/TextInput.md) component and [Downshift.js](https://www.downshift-js.com/use-combobox). It accepts standard HTML input attributes and the following props:

#### Basic

| Prop          | Type             | Required | Default | Description                                                                                                             |
| ------------- | ---------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `label`       | `string`         | Yes      | —       | Label text displayed above the input.                                                                                   |
| `items`       | `ComboboxItem[]` | Yes      | —       | Array of items to display in the dropdown. Each item must have a `value` property and can optionally have `isDisabled`. |
| `id`          | `string`         | No       | —       | HTML id for the input element.                                                                                          |
| `placeholder` | `string`         | No       | —       | Placeholder text shown when input is empty.                                                                             |
| `value`       | `string`         | No       | —       | Initial value for uncontrolled usage.                                                                                   |

#### Appearance

| Prop            | Type           | Required | Default   | Description                                      |
| --------------- | -------------- | -------- | --------- | ------------------------------------------------ |
| `type`          | `string`       | No       | `'text'`  | HTML input type.                                 |
| `menuSize`      | `'sm' \| 'md'` | No       | `'md'`    | Size of the menu items.                          |
| `menuMaxHeight` | `string`       | No       | `'300px'` | Maximum height of the dropdown menu (CSS value). |
| `success`       | `boolean`      | No       | `false`   | Shows success state styling.                     |
| `isDisabled`    | `boolean`      | No       | `false`   | Disables the entire combobox.                    |
| `isRequired`    | `boolean`      | No       | `false`   | Marks the field as required.                     |

#### Content

| Prop               | Type     | Required | Default               | Description                                                 |
| ------------------ | -------- | -------- | --------------------- | ----------------------------------------------------------- |
| `description`      | `string` | No       | —                     | Helper text displayed below the input.                      |
| `errorMessage`     | `string` | No       | —                     | Error message displayed below input (triggers error state). |
| `noResultsText`    | `string` | No       | `'Ei tuloksia'`       | Text shown when no items match the filter.                  |
| `loadingText`      | `string` | No       | `'Ladataan...'`       | Text shown during loading state.                            |
| `toggleButtonText` | `string` | No       | `'Näytä vaihtoehdot'` | Aria label for the toggle button (chevron icon).            |
| `clearText`        | `string` | No       | `'Tyhjennä'`          | Aria label for the clear button.                            |
| `searchIconLabel`  | `string` | No       | `'Haku'`              | Aria label for the search icon.                             |

#### Loading

| Prop                   | Type      | Required | Default | Description                                          |
| ---------------------- | --------- | -------- | ------- | ---------------------------------------------------- |
| `loading`              | `boolean` | No       | `false` | Shows loading spinner and loading text in menu.      |
| `showLoadingIndicator` | `boolean` | No       | `false` | Shows loading indicator (spinner) next to the input. |

#### Behavior

| Prop                         | Type      | Required | Default | Description                                                           |
| ---------------------------- | --------- | -------- | ------- | --------------------------------------------------------------------- |
| `showAllValuesOnOpen`        | `boolean` | No       | `false` | When true, shows all items when menu opens (even if input has value). |
| `clearSelectionOnEmptyInput` | `boolean` | No       | `true`  | When true, clears selection when input is emptied.                    |
| `initialIsOpen`              | `boolean` | No       | `false` | Whether menu should be open on mount.                                 |
| `autocomplete`               | `string`  | No       | —       | HTML autocomplete attribute.                                          |
| `hideClearButton`            | `boolean` | No       | `false` | Hides the clear button and prevents clearing the input.               |

#### Controlled Mode

| Prop                 | Type                              | Required | Description                                                                                              |
| -------------------- | --------------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `controlledValue`    | `string`                          | No       | Externally controlled input value. Use with `handleControlledValueChange` or `handleSelectedItemChange`. |
| `controlledItems`    | `ComboboxItem[]`                  | No       | Externally controlled items array. Use with `setControlledItems` for custom filtering logic.             |
| `setControlledItems` | `(items: ComboboxItem[]) => void` | No       | Setter for controlled items array. Required when using `controlledItems`.                                |

#### Icons

| Prop             | Type             | Required | Default | Description                                                                          |
| ---------------- | ---------------- | -------- | ------- | ------------------------------------------------------------------------------------ |
| `showSearchIcon` | `boolean`        | No       | `false` | Shows a search icon before the input.                                                |
| `icon`           | `InputIconProps` | No       | —       | Custom icon to replace the default toggle button (ChevronDown).                      |
| `iconBefore`     | `InputIconProps` | No       | —       | Icon displayed before input (overridden by search icon if `showSearchIcon` is true). |
| `iconClear`      | `InputIconProps` | No       | —       | Overrides default `createClearIcon` clear button (hidden while input is empty).      |

#### Customization

| Prop                | Type                                        | Required | Description                                                                                                                                 |
| ------------------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `menuItemComponent` | `(props: ComboboxItemProps) => JSX.Element` | No       | Custom component to render each menu item. Receives `ComboboxItemProps` including `item`, `index`, `highlightedIndex`, `selectedItem`, etc. Fall back to `DefaultComboboxMenuItem` for rows that should keep the default look. |

#### Callbacks

| Prop                          | Type                                         | Description                                                                                                                  |
| ----------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `handleControlledValueChange` | `(value: string) => void`                    | Callback when selected item changes. Receives the item's `value` string. Use for simple controlled mode.                     |
| `handleSelectedItemChange`    | `(item?: ComboboxItem \| null) => void`      | Callback when selection changes. Receives the full `ComboboxItem` object or null.                                            |
| `handleInputValueChange`      | `(value: string) => void`                    | Callback on every input change. When provided, **disables built-in filtering** - you must manually update `controlledItems`. |
| `handleItemToString`          | `(item?: ComboboxItem) => string`            | Custom function to convert a `ComboboxItem` to string for display in the input.                                              |
| `onChange`                    | `(e: ChangeEvent<HTMLInputElement>) => void` | Standard input onChange handler.                                                                                             |

#### Advanced

| Prop             | Type                        | Description                                                                                                                                                                                                                                     |
| ---------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `labelOptions`   | `FormElementLabelProps`     | Additional props for the label element. Note: downshift's `getLabelProps()` is merged into this.                                                                                                                                                |
| `environment`    | `Environment`               | Custom environment for downshift (useful for iframes/shadow DOM).                                                                                                                                                                               |
| `downshiftProps` | `Partial<UseComboboxProps>` | Passthrough object of Downshift's [`useCombobox`](https://www.downshift-js.com/use-combobox) hook advanced [configuration props](https://github.com/downshift-js/downshift/blob/master/src/hooks/useCombobox/README.md) for advanced use cases. |

### Type Definitions

```tsx
// TextInput props (base for ComboboxSingleSelect)
type TextInputDSProps = {
  label: string;
  labelOptions?: FormElementLabelProps;
  id?: string;
  value?: string;
  onChange?: React.ChangeEventHandler<HTMLInputElement>;
  placeholder?: string;
  description?: string;
  errorMessage?: string;
  autocomplete?: string;
  type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'search';
  success?: boolean;
  isRequired?: boolean;
  isDisabled?: boolean;
  children?: ReactNode;
  icon?: InputIconProps;
  submitButton?: ReactNode;
  iconBefore?: InputIconProps;
  iconClear?: InputIconProps;
  showLoadingIndicator?: boolean;
};

// ComboboxSingleSelect specific props
type ComboboxSingleSelectDSProps = TextInputDSProps & {
  items: ComboboxItem[];
  menuSize?: 'sm' | 'md';
  menuMaxHeight?: string;
  menuItemComponent?: (props: ComboboxItemProps) => JSX.Element;
  noResultsText?: string;
  toggleButtonText?: string;
  clearText?: string;
  hideClearButton?: boolean;
  showSearchIcon?: boolean;
  searchIconLabel?: string;
  loading?: boolean;
  loadingText?: string;
  controlledValue?: string;
  handleControlledValueChange?: (value: string) => void;
  handleInputValueChange?: (value: string) => void;
  handleItemToString?: (item?: ComboboxItem) => string;
  handleSelectedItemChange?: (item?: ComboboxItem | null) => void;
  controlledItems?: ComboboxItem[];
  setControlledItems?: (items: ComboboxItem[]) => void;
  showAllValuesOnOpen?: boolean;
  clearSelectionOnEmptyInput?: boolean;
  initialIsOpen?: boolean;
  environment?: Environment;
  downshiftProps?: Partial<UseComboboxProps>;
};

// Full props type
type ComboboxSingleSelectProps = InputHTMLAttributes<HTMLInputElement> &
  ComboboxSingleSelectDSProps;

// Items in `items` array must conform to this structure
type ComboboxItem = {
  value: string;
  isDisabled?: boolean;
  [key: string]: string | number | boolean | undefined;
};

// Custom menu item component receives these props
type ComboboxItemProps = HTMLAttributes<HTMLLIElement> & {
  item: ComboboxItem;
  index: number;
  highlightedIndex?: number;
  selectedItem: ComboboxItem | null;
  itemProps: HTMLAttributes<HTMLLIElement>;
  menuSize: 'sm' | 'md';
  children: ReactNode;
};

// Custom icon configurations
type InputIconProps = {
  componentFn: React.ComponentType;
  ariaLabel?: string;
  onClick?: () => void;
  props?: Record<string, unknown>;
};
```

## Related Components

- [Select](../Select/Select.md): A form element for simpler dropdowns with fewer options.
- [DropdownMenu](../DropdownMenu/DropdownMenu.md): A dropdown menu for interactive selections.
- [TextInput](../TextInput/TextInput.md): For free-form text input.
- [TagFilter](../TagFilter/TagFilter.md): For displaying selected items in a multi-select pattern.

# Dialog

Dialog is a content structure component that provides a consistent layout for a title, body content, and actions, and it is designed to be used inside Modal or BottomSheet components; it does not provide overlay, backdrop, or focus management on its own.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=9105-1860)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-dialog--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Dialog/Dialog.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/Dialog/)*

<details open>
<summary>Code example</summary>

```tsx
import { Dialog, Button } from '@yleisradio/yds-components-react';

<Dialog
  title="Dialog Title"
  actions={
    <>
      <Button text="Cancel" variant="text" />
      <Button text="Confirm" />
    </>
  }
>
  Dialog content goes here
</Dialog>
```
</details>

## Why to use

Use Dialog to ensure consistent spacing, typography, scrolling behavior, and action placement across all dialog-based interfaces in YDS. Dialog standardizes dialog layout, handles internal scrolling and separators, aligns actions consistently across devices, and improves accessibility when used inside Modal or BottomSheet.

> **Important**
> Dialog is a building block component designed to work inside Modal or BottomSheet. It provides the content structure (title, body, actions) but does not provide modal behavior, backdrop, or focus management. Use Modal or BottomSheet for the actual dialog overlay functionality.
## When to use

Use Dialog when you need a structured dialog layout that consists of a clear title, body content, and optional actions.

> **Do**
> - Use Dialog inside [Modal](../Modal/Modal.md) or [BottomSheet](../BottomSheet/BottomSheet.md) for all dialog interfaces.
> - Use it for confirmations, forms, settings, and focused tasks.
> - Use when content needs a clear hierarchy and actions footer.

> **Don't**
> - Don’t use Dialog as a standalone modal overlay.
> - Don’t use it for generic layout or page content.
> - Don’t omit the title — it is required for accessibility.

## Content Guidelines

Use these guidelines when placing content inside a Dialog. They are based on the Modal content guidelines.

> **Do**
> - Write a clear, descriptive title that explains the task.
> - Keep body content concise and task-focused.
> - Match the primary action label to the dialog intent
> - Action buttons should have clear, descriptive labels that indicate their purpose.

> **Don't**
> - Don’t overload the dialog with secondary content.
> - Don’t include multi-step flows inside a dialog.
> - Don’t use vague action labels like “OK”.

## Key Dialog Props

Use these props to configure the Dialog component.

### title
Dialog title text.

| Type | Example | Description |
|------|---------|-------------|
| `string` | <Dialog title="Confirm Action" actions={<><Button variant="text" text="Cancel" /><Button text="Confirm" /></>} style={{ minWidth: 320, maxWidth: 560 }}>Content</Dialog> | Title text for the dialog |

<details>
<summary>Code example</summary>

```tsx
<Dialog
  title="Confirm Action"
  actions={
    <>
      <Button variant="text" text="Cancel" />
      <Button text="Confirm" />
    </>
  }
>
  Are you sure you want to proceed?
</Dialog>
```
</details>

### titleAs
HTML tag name to render for the title.

| Type | Example | Description |
|------|---------|-------------|
| `string` | <Dialog titleAs="h2" title="Dialog Title" actions={<><Button variant="text" text="Cancel" /><Button text="Confirm" /></>} style={{ minWidth: 320, maxWidth: 560 }}>Content</Dialog> | HTML element for title (e.g., 'h2') |

<details>
<summary>Code example</summary>

```tsx
<Dialog
  titleAs="h2"
  title="Dialog Title"
  actions={
    <>
      <Button variant="text" text="Cancel" />
      <Button text="Confirm" />
    </>
  }
>
  Content
</Dialog>
```
</details>

### illustrativeIcon
Optional illustrative icon displayed above the title.

| Type | Example | Description |
|------|---------|-------------|
| `React.ReactElement<SvgProps> \| null` | <Dialog illustrativeIcon={<IllustrativeCelebrate />} title="Title" actions={<><Button variant="text" text="Cancel" /><Button text="Confirm" /></>} style={{ minWidth: 320, maxWidth: 560 }}>Content</Dialog> | Illustrative icon element to display |

<details>
<summary>Code example</summary>

```tsx
import { IllustrativeCelebrate } from '@yleisradio/yds-icons-react';

<Dialog
  illustrativeIcon={<IllustrativeCelebrate />}
  title="Dialog Title"
  actions={
    <>
      <Button variant="text" text="Cancel" />
      <Button text="Confirm" />
    </>
  }
>
  Content
</Dialog>
```
</details>

### size
Size variant of the dialog.

| Value | Example | Description |
|-------|---------|-------------|
| `sm` | <Dialog size="sm" title="Title" style={{ minWidth: 320, maxWidth: 560 }} actions={<Button text="Action" />}>Content</Dialog> | Small dialog size |
| `md` | <Dialog size="md" title="Title" style={{ minWidth: 320, maxWidth: 560 }} actions={<Button text="Action" />}>Content</Dialog> | Medium dialog size (default) |

<details>
<summary>Code example</summary>

```tsx
<Dialog size="sm" title="Small Dialog" actions={<Button text="Action" />}>
  Content
</Dialog>
<Dialog size="md" title="Medium Dialog" actions={<Button text="Action" />}>
  Content
</Dialog>
```
</details>

### actions
Action buttons or elements displayed in the footer.

| Type | Example | Description |
|------|---------|-------------|
| `React.ReactNode` | <Dialog title="Title" actions={<Button>OK</Button>}>Content</Dialog> | Footer action elements |

<details>
<summary>Code example</summary>

```tsx
<Dialog
  title="Confirm"
  actions={
    <>
      <Button variant="text">Cancel</Button>
      <Button>Confirm</Button>
    </>
  }
>
  <p>Are you sure?</p>
</Dialog>
```
</details>

## Behavior

- Dialog provides layout only — no open/close logic.
- Body content scrolls independently when height exceeds limits.
- Scroll separators appear automatically when content overflows.
- Actions remain visually separated from content.
- Action buttons in the `actions` prop are automatically sized to match the dialog's `size` prop
- Illustrative icons are positioned above the title and affect spacing accordingly
- The component is purely presentational — it does not handle opening, closing, or modal behavior (that's handled by Modal or BottomSheet)

## Accessibility

- Title is rendered as a heading (default `h2`, configurable via `titleAs` prop) for proper document structure<br />([WCAG 1.3.1 — Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships))
- Structure supports screen reader announcement when used in Modal/BottomSheet.
- Illustrative icons are decorative and don't require alt text (they're visual enhancements)

## API Reference

### Props

The Dialog component accepts all standard HTML `<div>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `title` | `string` | Yes | — | Dialog title text |
| `titleAs` | `string` | No | `'h2'` | HTML tag name to render for title |
| `illustrativeIcon` | `React.ReactElement<SvgProps> \| null` | No | — | Optional icon displayed above title |
| `size` | `'sm' \| 'md'` | No | `'md'` | Size variant of the dialog |
| `children` | `React.ReactNode` | No | — | Content displayed in dialog body |
| `actions` | `React.ReactNode` | No | — | Action buttons displayed in footer |

### Type Definitions

```tsx
import { type SvgProps } from '@yleisradio/yds-icons-react';

export interface DialogDSProps {
  title: string;
  titleAs?: string;
  illustrativeIcon?: React.ReactElement<SvgProps> | null;
  size?: 'sm' | 'md';
  children?: React.ReactNode;
  actions?: React.ReactNode;
}

export type DialogProps = HTMLAttributes<HTMLDivElement> & DialogDSProps;
```

## Related Components

- [Modal](../Modal/Modal.md) – **Primary container for Dialog** — use Modal to wrap Dialog for desktop/tablet dialog interfaces.
- [BottomSheet](../BottomSheet/BottomSheet.md) – **Primary container for Dialog** — use BottomSheet to wrap Dialog for mobile dialog interfaces.
- [Button](../Button/Button.md) – Commonly used in dialog `actions` prop for footer buttons.
- [Accordion](../Accordion/Accordion.md) – Can be used inside a Dialog to organise collapsible content.

# DropdownMenu

DropdownMenu is a button-based control that lets users select a value from a list of options and applies the change immediately. It is used for lightweight state changes such as language selection or sorting.
- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=8809-10633)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-dropdownmenu--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/DropdownMenu/DropdownMenu.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/DropdownMenu/)*

<details open>
<summary>Code example</summary>

```tsx
import { DropdownMenu } from '@yleisradio/yds-components-react';

const [value, setValue] = useState<string>();

<DropdownMenu
  placeholder="Select option"
  value={value}
  onChange={setValue}
  options={[
    { text: 'Option 1', value: 'opt1' },
    { text: 'Option 2', value: 'opt2' },
    { type: 'separator' },
    { text: 'Option 3', value: 'opt3' },
  ]}
  id="dropdown-1"
  menuId="menu-1"
  value={value}
  onChange={setValue}
/>
```
</details>

## Why to use

DropdownMenu provides a compact and accessible way to change the UI state by selecting one option from a predefined list. It enables users to make immediate choices without additional confirmation, while keeping the interface clean and uncluttered. By building on the Menu component, DropdownMenu ensures consistent positioning, keyboard interaction, and visual behavior across products.

It is especially suitable for cases where options are few, clearly comparable, and the selection directly affects what the user sees or how the interface behaves.

## When to use

Use DropdownMenu when users need to select a single value that changes the UI state immediately, such as language, sorting order, or filtering mode.

> **Do**
> - Use when the selection updates the interface immediately without requiring a separate save action.
> - Use when options are easily comparable at a glance.
> - Use for lightweight UI state changes such as language, sorting, or view mode.

> **Don't**
> - Don’t use when users need to select multiple values – use multi-select patterns instead.
> - Don’t use when options should remain visible and directly comparable – use [ButtonGroup](../ButtonGroup/ButtonGroup.md) instead.
> - Don’t use for triggering actions that do not change component state – use [ActionMenu](../ActionMenu/ActionMenu.md) instead.

## Content Guidelines

DropdownMenu labels and options should support quick scanning and easy comparison.

> **Do**
> - Keep option labels short and parallel in structure.
> - Use nouns or adjectives for option labels (e.g. “Suomi”, “English”, “Uusin”).
> - Ensure options are easily comparable at a glance.
> - Prefer fewer than eight options to maintain clarity.

> **Don't**
> - Don’t use long or descriptive sentences as options.
> - Don’t use abbreviations like “FI”, “EN” for language choices.
> - Don’t mix different grammatical styles in the same list.
> - Don’t include options that are not logically comparable.

## Anatomy

![DropdownMenu anatomy](../../img/dropdown-anatomy.svg)

1. **DropdownMenu button** – The trigger button that opens the dropdown menu.
2. **Label / selected value** – Text inside the button showing the placeholder or the currently selected value.
3. **Chevron icon** – Indicates that the button opens a dropdown menu.
4. **Menu surface** – The floating container holding the selectable options.
5. **MenuItem (option)** – A single selectable option inside the menu.
6. **Selected state** – Visual indicator showing the currently selected option.
7. **MenuSeparator (optional)** – Groups related actions.

## Key DropdownMenu Props

Use these props to configure the DropdownMenu component.

### placeholder
Placeholder text displayed when no option is selected.

| Type | Example | Description |
|------|---------|-------------|
| `string` | <DropdownMenuExample placeholder="Select a value" id="menu-1" menuId="menu-1" options={[{ text: 'Option 1', value: 'opt1' }]}/> | Placeholder text |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenu
  placeholder="Select an option"
  options={options}
  value={value}
  onChange={onChange}
  id="menu-1"
  menuId="menu-1"
/>
```
</details>

### options
Array of menu options and separators.

| Type | Example | Description |
|------|---------|-------------|
| `(DropdownMenuOption<T> \| DropdownMenuSeparator)[]` | <DropdownMenuExample options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }, { type: 'separator' }, { text: 'Option 3', value: 'opt3' }]} placeholder="Select a value" id="menu-1" menuId="menu-1" /> | Array of options and separators |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenu
  options={[
    { text: 'Option 1', value: 'opt1' },
    { text: 'Option 2', value: 'opt2' },
    { type: 'separator' },
    { text: 'Option 3', value: 'opt3' },
  ]}
  value={value}
  onChange={onChange}
  placeholder="Select"
  id="menu-1"
  menuId="menu-1"
/>
```
</details>

### dropdown
Whether to show a dropdown chevron icon.

| Value | Example | Description |
|------|---------|-------------|
| `true` | <DropdownMenuExample dropdown={true} placeholder="Select a value" id="menu-1" menuId="menu-1" options={[{ text: 'Option 1', value: 'opt1' }]} /> | Shows chevron icon |
| `false` | <DropdownMenuExample dropdown={false} placeholder="Select a value" id="menu-1" menuId="menu-1" options={[{ text: 'Option 1', value: 'opt1' }]} /> | Hides chevron icon |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenu
  dropdown={true}
  id="menu-1"
  menuId="menu-1"
  options={options}
  value={value}
  onChange={onChange}
  placeholder="Select"
/>
```
</details>

### openMenuOnClick
Whether clicking the button opens the menu.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <DropdownMenuExample openMenuOnClick={false} placeholder="Select a value" id="menu-1" menuId="menu-1" options={[{ text: 'Option 1', value: 'opt1' }]} /> | Controls if click opens menu |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenu
  openMenuOnClick={true}
  id="menu-1"
  menuId="menu-1"
  options={options}
  value={value}
  onChange={onChange}
  placeholder="Select"
/>
```
</details>

### menuSize
Size of the menu items.

| Value | Example | Description |
|-------|---------|-------------|
| `sm` | <DropdownMenuExample menuSize="sm" placeholder="Select a value" id="menu-1" menuId="menu-1" options={[{ text: 'Option 1', value: 'opt1' }]} /> | Small menu items |
| `md` | <DropdownMenuExample menuSize="md" placeholder="Select a value" id="menu-1" menuId="menu-1" options={[{ text: 'Option 1', value: 'opt1' }]} /> | Medium menu items (default) |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenu
  menuSize="sm"
  id="menu-1"
  menuId="menu-1"
  options={options}
  value={value}
  onChange={onChange}
  placeholder="Select"
/>
```
</details>

### alignMenu
Horizontal alignment of the menu relative to the button.

| Value | Example | Description |
|-------|---------|-------------|
| `left` | <DropdownMenuExample alignMenu="left" placeholder="Select a value" id="menu-1" menuId="menu-1" options={[{ text: 'Option 1', value: 'opt1' }]} /> | Aligns menu to the left |
| `right` | <DropdownMenuExample alignMenu="right" placeholder="Select a value" id="menu-1" menuId="menu-1" options={[{ text: 'Option 1', value: 'opt1' }]} /> | Aligns menu to the right (default) |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenu
  alignMenu="left"
  id="menu-1"
  menuId="menu-1"
  options={options}
  value={value}
  onChange={onChange}
  placeholder="Select"
/>
```
</details>

### position

Preferred direction in which the menu opens relative to the trigger button. The menu automatically adjusts if it would be clipped by the viewport.

| Value    | Example | Description |
|----------|---------|-------------|
| `bottom` | <DropdownMenuExample position="bottom" placeholder="Select a value" id="menu-1" menuId="menu-1" options={[{ text: 'Option 1', value: 'opt1' }]} /> | Opens below the button (default) |
| `top`    | <DropdownMenuExample position="top" placeholder="Select a value" id="menu-1" menuId="menu-1" options={[{ text: 'Option 1', value: 'opt1' }]} /> | Opens above the button |
| `left`   | <DropdownMenuExample position="left" placeholder="Select a value" id="menu-1" menuId="menu-1" options={[{ text: 'Option 1', value: 'opt1' }]} /> | Opens to the left of the button |
| `right`  | <DropdownMenuExample position="right" placeholder="Select a value" id="menu-1" menuId="menu-1" options={[{ text: 'Option 1', value: 'opt1' }]} /> | Opens to the right of the button |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenu
  position="top"
  placeholder="Select"
  options={options}
  value={value}
  onChange={onChange}
  id="menu-1"
  menuId="menu-1"
/>
<DropdownMenu
  position="right"
  placeholder="Select"
  options={options}
  value={value}
  onChange={onChange}
  id="menu-2"
  menuId="menu-2"
/>
<DropdownMenu
  position="left"
  placeholder="Select"
  options={options}
  value={value}
  onChange={onChange}
  id="menu-3"
  menuId="menu-3"
/>
```
</details>

## Behavior

- Selecting an option updates the component state immediately.
- The selected value is reflected in the trigger button label.
- The menu opens from the trigger and closes after selection, outside click, or cancellation.
- The `position` prop controls the preferred direction in which the menu opens: `'bottom'` (default), `'top'`, `'left'`, or `'right'`. The menu automatically adjusts if it would be clipped by the viewport.
- Keyboard interaction:
  - Arrow keys navigate between options.
  - Enter selects an option.
  - Escape closes the menu.

## Accessibility

- Ensure full keyboard support for all interactions (Tab, Arrow keys, Enter, Space).<br />
  (WCAG 2.1.1 — [Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html))
- Interactive elements have visible focus indicators.<br />
  ([WCAG 2.4.7 — Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html))
- Options are easily comparable and perceivable at a glance.
- The selected option is communicated both visually and programmatically.
- Screen readers announce the current value and the open/closed state of the menu.

## Implementation Examples

### Language Selector

*[Live preview](https://design-system.yle.fi/docs/components/DropdownMenu/)*

<details>
<summary>Code example</summary>

```tsx
  import { DropdownMenu } from '@yleisradio/yds-components-react';

  const [value, setValue] = useState<string>();

  <DropdownMenu
    placeholder="Select Language"
    options={[
      { text: 'Suomi', value: 'fi' },
      { text: 'Svenska', value: 'sv' },
      { text: 'English', value: 'en' },
    ]}
    id="languare-selector"
    menuId="language-menu"
    value={value}
    onChange={setValue}
  />
  ```
</details>

## API Reference

### Props

The DropdownMenu component accepts all standard ActionMenu props (except `children` and `text`) in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `placeholder` | `string` | Yes | — | Placeholder text when no option selected |
| `value` | `T \| undefined` | Yes | — | Currently selected value |
| `onChange` | `(value: T) => void` | Yes | — | Callback fired when selection changes |
| `options` | `(DropdownMenuOption<T> \| DropdownMenuSeparator)[]` | Yes | — | Array of menu options and separators |
| `id` | `string` | Yes | — | Unique identifier for the button |
| `menuId` | `string` | Yes | — | Unique identifier for the menu |

### Type Definitions

```tsx
export interface DropdownMenuOption<T> {
  text: string;
  value: T;
  type?: 'item';
}

export interface DropdownMenuSeparator {
  type: 'separator';
}

export type DropdownMenuDSProps<T> = Omit<ActionMenuDSProps, 'children' | 'text'> & {
  placeholder: string;
  value: T | undefined;
  onChange: (value: T) => void;
  options: (DropdownMenuOption<T> | DropdownMenuSeparator)[];
};

export type DropdownMenuProps<T> = DropdownMenuDSProps<T> &
  Omit<ActionMenuProps, 'children' | 'onClick' | 'onChange' | 'text'>;
```

## Related Components

- [Menu](../Menu/Menu.md) - Base component for all menu components
- [ActionMenu](../ActionMenu/ActionMenu.md) – Base component that DropdownMenu extends
- [DropdownMenuGroup](../DropdownMenuGroup/DropdownMenuGroup.md) – Component for grouping multiple DropdownMenus
- [Select](../Select/Select.md) – Alternative component for form selects
- [ButtonGroup](../ButtonGroup/ButtonGroup.md) – Alternative component for button-based menus

# DropdownMenuGroup

DropdownMenuGroup groups multiple dropdown menus into a single, cohesive control area, allowing users to make one or more selections in a compact way without overloading the interface.
- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=6298-3045)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-dropdownmenugroup--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/DropdownMenuGroup/DropdownMenuGroup.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/DropdownMenuGroup/)*

<details open>
<summary>Code example</summary>

```tsx
import { DropdownMenuGroup } from '@yleisradio/yds-components-react';

<DropdownMenuGroup>
  <DropdownMenuGroup.DropdownMenu
    id="menu-1"
    options={[
      { text: 'Option 1', value: 'opt1' },
      { text: 'Option 2', value: 'opt2' },
    ]}
    value={selectedValue}
    onChange={(value) => setSelectedValue(value)}
  />
  <DropdownMenuGroup.DropdownMenuMultiSelect
    id="menu-2"
    options={[
      { text: 'Option A', value: 'optA' },
      { text: 'Option B', value: 'optB' },
    ]}
    value={selectedValues}
    onChange={(values) => setSelectedValues(values)}
  />
</DropdownMenuGroup>
```
</details>

## Why to use

DropdownMenuGroup brings related selections together into a clear and consistent whole. It reduces visual clutter compared to always-visible button groups while still supporting both single- and multi-select patterns with unified behavior, alignment, and visual styling across the product.

## When to use

Use DropdownMenuGroup when users need to make one or more related selections but the options don’t need to be visible all the time.

| Pattern | What it does | Typical use cases |
|-------|---------|---------|
| **Single Select** | Allows selecting one option from a dropdown menu. | Selecting a single election-related view or setting, such as election type or region. |
| **Multi Select** | Allows selecting zero or more options from a dropdown menu. | Filtering content by election-related criteria, such as parties, candidate types, or themes. |

> **Do**
> - Use when option lists are long, labels are wide, or the UI would become cluttered if everything was always visible.
> - Use it for supportive settings and filters (not the primary state of the view).
> - Use single-select dropdowns for one choice and multi-select dropdowns for filters.
> - Use multiple menus together when selections belong to the same task (e.g., “Category” + “Sort” + “Time range”).

> **Don't**
> - Don’t hide primary view state changes inside menus — use [ButtonGroup](../ButtonGroup/ButtonGroup.md) or tabs instead.
> - Don’t use DropdownMenuGroup for page-level navigation — use [NavigationTabs](../NavigationTabs/NavigationTabs.md) instead.
> - Don’t use it for switching content within a section — use [SectionTabs](../SectionTabs/SectionTabs.md) instead.
> - Don’t combine unrelated selections within the same group.
> - Don’t use menus when options should remain visible and directly comparable — use [ButtonGroup](../ButtonGroup/ButtonGroup.md) instead.

## Content Guidelines

Menu labels and options must be short, scannable, and comparable. Users should understand what each menu controls and what each option changes without extra explanation.

> **Do**
> - Use clear menu labels that describe the selection category (e.g., “Alue”, “Aikaväli”, “Järjestys”).
> - Keep option labels short and parallel (e.g., “Uusin”, “Suosituin”, “A–Ö”).
> - Use nouns for filters and categories; use verbs only when an item triggers an immediate action.
> - Use separators to group options when the list includes multiple logical sections.
> - Keep terminology and capitalization consistent within the same menu and across menus in the group

> **Don't**
> - Don’t use long sentences or instructions as menu options.
> - Don’t use vague labels like “Oletus” or “Valitse” without context.
> - Don’t mix verbs and nouns in the same option list without a clear reason.
> - Don’t rely on placeholder text alone to explain scope or rules — use surrounding UI text or helper text.
> - Don’t create deep or overly complex menu structures — split into multiple menus or rethink the model.

## Anatomy

![DropdownMenuGroup anatomy](../../img/dropdown-menu-group-anatomy.svg)

1. **Group Container** – Wraps multiple menus into a single unit and manages spacing, alignment, and wrapping.
2. **Menu Button** – The control users interact with to open and close a menu.
3. **Menu (Panel & Items)** – The dropdown (list, radio or checkbox) surface containing selectable options, optional separators, and selection styles.
4. **Label** – Text inside each menu button describing the menu.
5. **Selection Indicator** – Visual indication of selection

## Key DropdownMenuGroup Props

Use these props to configure the DropdownMenuGroup component.

### children
DropdownMenu components to display in the group.

| Type | Example | Description |
|------|---------|-------------|
| `React.ReactNode` | <DropdownMenuGroup><DropdownMenuGroup.DropdownMenu options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} value={undefined} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenu><DropdownMenuGroup.DropdownMenu options={[{ text: 'Option A', value: 'optA' }, { text: 'Option B', value: 'optB' }]} value={undefined} onChange={() => {}}><span>Menu 2</span></DropdownMenuGroup.DropdownMenu></DropdownMenuGroup> | DropdownMenu sub-components |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenuGroup>
  <DropdownMenuGroup.DropdownMenu id="menu-1" options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} value={undefined} onChange={() => {}}>Menu 1</DropdownMenuGroup.DropdownMenu>
  <DropdownMenuGroup.DropdownMenu id="menu-2" options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} value={undefined} onChange={() => {}}>Menu 2</DropdownMenuGroup.DropdownMenu>
</DropdownMenuGroup>
```
</details>

### variant
Visual style variant of the buttons.

| Value | Example | Description |
|-------|---------|-------------|
| `primary` | <DropdownMenuGroup variant="primary"><DropdownMenuGroup.DropdownMenu options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} value={undefined} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenu></DropdownMenuGroup> | Primary button style (default) |
| `text` | <DropdownMenuGroup variant="text"><DropdownMenuGroup.DropdownMenu options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} value={undefined} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenu></DropdownMenuGroup> | Low-emphasis text style for lighter controls |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenuGroup variant="primary">
  <DropdownMenuGroup.DropdownMenu id="menu-1" options={[]} value={undefined} onChange={() => {}}>Menu 1</DropdownMenuGroup.DropdownMenu>
</DropdownMenuGroup>
```
</details>

### size
Size of the buttons.

| Value | Example | Description |
|-------|---------|-------------|
| `xs` | <DropdownMenuGroup size="xs"><DropdownMenuGroup.DropdownMenu options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} value={undefined} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenu></DropdownMenuGroup> | Extra small size |
| `sm` | <DropdownMenuGroup size="sm"><DropdownMenuGroup.DropdownMenu options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} value={undefined} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenu></DropdownMenuGroup> | Small size |
| `md` | <DropdownMenuGroup size="md"><DropdownMenuGroup.DropdownMenu options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} value={undefined} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenu></DropdownMenuGroup> | Medium size (default) |
| `lg` | <DropdownMenuGroup size="lg"><DropdownMenuGroup.DropdownMenu options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} value={undefined} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenu></DropdownMenuGroup> | Large size |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenuGroup size="sm">
  <DropdownMenuGroup.DropdownMenu id="menu-1" options={[]} value={undefined} onChange={() => {}}>Menu 1</DropdownMenuGroup.DropdownMenu>
</DropdownMenuGroup>
```
</details>

### menuSize
Size of the menu items.

| Value | Example | Description |
|-------|---------|-------------|
| `sm` | <DropdownMenuGroup menuSize="sm"><DropdownMenuGroup.DropdownMenu options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} value={undefined} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenu></DropdownMenuGroup> | Small menu items |
| `md` | <DropdownMenuGroup menuSize="md"><DropdownMenuGroup.DropdownMenu options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} value={undefined} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenu></DropdownMenuGroup> | Medium menu items (default) |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenuGroup menuSize="sm">
  <DropdownMenuGroup.DropdownMenu id="menu-1" options={[]} value={undefined} onChange={() => {}}>Menu 1</DropdownMenuGroup.DropdownMenu>
</DropdownMenuGroup>
```
</details>

## Key DropdownMenuGroup.DropdownMenu Props

Use these props to configure the single-select dropdown menu.

### options
Array of menu options and separators.

| Type | Example | Description |
|------|---------|-------------|
| `(DropdownMenuOption<T> \| DropdownMenuSeparator)[]` | <DropdownMenuGroup.DropdownMenu options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }, { type: 'separator' }, { text: 'Option 3', value: 'opt3' }]} value={undefined} onChange={() => {}} id="menu-1"><span>Menu 1</span></DropdownMenuGroup.DropdownMenu> | Array of options and separators |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenuGroup.DropdownMenu
  id="menu-1"
  options={[
    { text: 'Option 1', value: 'opt1' },
    { text: 'Option 2', value: 'opt2' },
    { type: 'separator' },
    { text: 'Option 3', value: 'opt3' },
  ]}
  value={value}
  onChange={onChange}
>
  Menu 1
</DropdownMenuGroup.DropdownMenu>
```
</details>

### value
Currently selected value (single value).

| Type | Example | Description |
|------|---------|-------------|
| `T \| undefined` | <DropdownMenuGroup.DropdownMenu value="opt1" options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} onChange={() => {}} id="menu-1" ><span>Menu 1</span></DropdownMenuGroup.DropdownMenu> | Selected option value |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenuGroup.DropdownMenu
  id="menu-1"
  value="opt1"
  options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]}
  onChange={onChange}
>
  Menu 1
</DropdownMenuGroup.DropdownMenu>
```
</details>

### defaultValue
Initial selected value for uncontrolled component.

| Type | Example | Description |
|------|---------|-------------|
| `T \| undefined` | <DropdownMenuGroup.DropdownMenu defaultValue="opt1" options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} onChange={() => {}} id="menu-1"><span>Menu 1</span></DropdownMenuGroup.DropdownMenu> | Initial selected value |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenuGroup.DropdownMenu
  id="menu-1"
  defaultValue="opt1"
  options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]}
  onChange={onChange}
>
  Menu 1
</DropdownMenuGroup.DropdownMenu>
```
</details>

### menuItemVariant
Visual variant of menu items.

| Value | Example | Description |
|-------|---------|-------------|
| `default` | <DropdownMenuGroup.DropdownMenu menuItemVariant="default" id="menu-1" options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} value={undefined} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenu> | Default menu item style |
| `radio` | <DropdownMenuGroup.DropdownMenu menuItemVariant="radio" id="menu-1" options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} value={undefined} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenu> | Radio button style menu items |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenuGroup.DropdownMenu
  id="menu-1"
  menuItemVariant="radio"
  options={options}
  value={value}
  onChange={onChange}
>
  Menu 1
</DropdownMenuGroup.DropdownMenu>
```
</details>

### alignMenu
Horizontal alignment of the menu relative to the button.

| Value | Example | Description |
|-------|---------|-------------|
| `left` | <DropdownMenuGroup.DropdownMenu alignMenu="left" id="menu-1" options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenu> | Aligns menu to the left |
| `right` | <DropdownMenuGroup.DropdownMenu alignMenu="right" id="menu-1" options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenu> | Aligns menu to the right (default) |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenuGroup.DropdownMenu
  id="menu-1"
  alignMenu="left"
  options={[options]}
  value={value}
  onChange={onChange}
>
  Menu 1
</DropdownMenuGroup.DropdownMenu>
```
</details>

## Key DropdownMenuGroup.DropdownMenuMultiSelect Props

Use these props to configure the multi-select dropdown menu.

### options
Array of menu options and separators.

| Type | Example | Description |
|------|---------|-------------|
| `(DropdownMenuOption<T> \| DropdownMenuSeparator)[]` | <DropdownMenuGroup.DropdownMenuMultiSelect options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }, { type: 'separator' }, { text: 'Option 3', value: 'opt3' }]} onChange={() => {}} id="menu-1"><span>Menu 1</span></DropdownMenuGroup.DropdownMenuMultiSelect> | Array of options and separators |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenuGroup.DropdownMenuMultiSelect
  id="menu-1"
  options={[
    { text: 'Option 1', value: 'opt1' },
    { text: 'Option 2', value: 'opt2' },
    { type: 'separator' },
    { text: 'Option 3', value: 'opt3' },
  ]}
  value={values}
  onChange={onChange}
>
  Menu 1
</DropdownMenuGroup.DropdownMenuMultiSelect>
```
</details>

### value
Currently selected values (array).

| Type | Example | Description |
|------|---------|-------------|
| `T[] \| undefined` | <DropdownMenuGroup.DropdownMenuMultiSelect value={['opt1', 'opt2']} options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }, { type: 'separator' }, { text: 'Option 3', value: 'opt3' }]} onChange={() => {}} id="menu-1"><span>Menu 1</span></DropdownMenuGroup.DropdownMenuMultiSelect> | Selected option values |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenuGroup.DropdownMenuMultiSelect
  id="menu-1"
  value={['opt1', 'opt2']}
  options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }, { type: 'separator' }, { text: 'Option 3', value: 'opt3' }]}
  onChange={onChange}
>
  Menu 1
</DropdownMenuGroup.DropdownMenuMultiSelect>
```
</details>

### defaultValue
Initial selected values for uncontrolled component.

| Type | Example | Description |
|------|---------|-------------|
| `T[] \| undefined` | <DropdownMenuGroup.DropdownMenuMultiSelect defaultValue={['opt1']} options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} onChange={() => {}} id="menu-1"><span>Menu 1</span></DropdownMenuGroup.DropdownMenuMultiSelect> | Initial selected values |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenuGroup.DropdownMenuMultiSelect
  id="menu-1"
  defaultValue={['opt1', 'opt2']}
  options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]}
  onChange={onChange}
>
  Menu 1
</DropdownMenuGroup.DropdownMenuMultiSelect>
```
</details>

### menuItemVariant
Visual variant of menu items.

| Value | Example | Description |
|-------|---------|-------------|
| `default` | <DropdownMenuGroup.DropdownMenuMultiSelect menuItemVariant="default" id="menu-1" options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenuMultiSelect> | Default menu item style |
| `checkbox` | <DropdownMenuGroup.DropdownMenuMultiSelect menuItemVariant="checkbox" id="menu-1" options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenuMultiSelect> | Checkbox style menu items |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenuGroup.DropdownMenuMultiSelect
  id="menu-1"
  menuItemVariant="checkbox"
  options={options}
  value={values}
  onChange={onChange}
>
  Menu 1
</DropdownMenuGroup.DropdownMenuMultiSelect>
```
</details>

### alignMenu
Horizontal alignment of the menu relative to the button.

| Value | Example | Description |
|-------|---------|-------------|
| `left` | <DropdownMenuGroup.DropdownMenuMultiSelect alignMenu="left" id="menu-1" options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenuMultiSelect> | Aligns menu to the left |
| `right` | <DropdownMenuGroup.DropdownMenuMultiSelect alignMenu="right" id="menu-1" options={[{ text: 'Option 1', value: 'opt1' }, { text: 'Option 2', value: 'opt2' }]} onChange={() => {}}><span>Menu 1</span></DropdownMenuGroup.DropdownMenuMultiSelect> | Aligns menu to the right (default) |

<details>
<summary>Code example</summary>

```tsx
<DropdownMenuGroup.DropdownMenuMultiSelect
  id="menu-1"
  alignMenu="left"
  options={options}
  value={values}
  onChange={onChange}
>
  Menu 1
</DropdownMenuGroup.DropdownMenuMultiSelect>
```
</details>

## Behavior
- Menus open from their button and close on selection, outside click, or cancellation.
- Single-select updates one value; multi-select toggles options independently.
- Menus in the same group align visually and can wrap onto multiple rows when space is limited.
- Use alignMenu near edges to prevent the panel from being clipped.
- onOpen / onClose can be used for analytics and focus management.
- openMenuOnClick defines whether the menu opens on click (default: true).

## Accessibility
- Ensure full keyboard support (Tab, Arrow keys, Enter, Space).<br />
  (WCAG 2.1.1 — [Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html))
- Provide clear context for each menu through visible text or an accessible programmatic name.<br />
  (WCAG 4.1.2 — [Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html))
- Keep selection state perceivable (radio/checkbox variants help communicate single vs multi selection).<br />
  (WCAG 1.3.1 — [Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html))

## Implementation Examples

### Search filters with single select menus

<ComponentPreview style={{ display: 'flex', gap: '16px', flexDirection: 'column', marginBottom: '16px' }}>
  <SearchInput
    id="search-basic"
    label="Hae"
    placeholder="Hae"
    name="q"
    submitButton={<SearchSubmitButton aria-label="Hae" />}
    iconClear={createClearIcon({ ariaLabel: 'Tyhjennä haku' })}
  />
  <DropdownMenuGroup>
    <DropdownMenuGroup.DropdownMenu
      id="menu-1"
      options={[
        { text: 'Uutiset', value: 'uutiset' },
        { text: 'Urheilu', value: 'urheilu' },
        { text: 'Oppiminen', value: 'oppiminen' },
        { text: 'Elävä arkisto', value: 'elava-arkisto' },
        { text: 'YleX ', value: 'ylex' },
      ]}
      value={undefined}
      onChange={(value) => {}}
    >
      <span>Valitse palvelu</span>
    </DropdownMenuGroup.DropdownMenu>
    <DropdownMenuGroup.DropdownMenu
      id="menu-2"
      options={[
        { text: 'Tänään', value: 'tanaan' },
        { text: 'Viikon sisällä', value: 'viikon-sisalla' },
        { text: 'Kuukauden sisällä', value: 'kuukauden-sisalla' },
      ]}
      value={undefined}
      onChange={(value) => {}}
    >
      <span>Valitse aikaväli</span>
    </DropdownMenuGroup.DropdownMenu>
    <DropdownMenuGroup.DropdownMenu
      id="menu-3"
      options={[
        { text: 'Suomi', value: 'suomi' },
        { text: 'Svenska', value: 'svenska' },
        { text: 'English', value: 'english' },
      ]}
      value={undefined}
      onChange={(value) => {}}
    >
      <span>Valitse kieli</span>
    </DropdownMenuGroup.DropdownMenu>
  </DropdownMenuGroup>
</ComponentPreview>

<details>
<summary>Code example</summary>

```tsx
  <div style={{ display: 'flex', gap: '8px', flexDirection: 'column' }}>
    <SearchInput
      id="search-basic"
      label="Hae"
      placeholder="Hae"
      name="q"
      submitButton={<SearchSubmitButton aria-label="Hae" />}
      iconClear={createClearIcon({ ariaLabel: 'Tyhjennä haku' })}
    />
    <DropdownMenuGroup size="sm">
      <DropdownMenuGroup.DropdownMenu
        id="menu-1"
        options={[
          { text: 'Uutiset', value: 'uutiset' },
          { text: 'Urheilu', value: 'urheilu' },
          { text: 'Oppiminen', value: 'oppiminen' },
          { text: 'Elävä arkisto', value: 'elava-arkisto' },
          { text: 'YleX ', value: 'ylex' },
        ]}
        value={undefined}
        onChange={(value) => {}}
      >
        <span>Valitse palvelu</span>
      </DropdownMenuGroup.DropdownMenu>
      <DropdownMenuGroup.DropdownMenu
        id="menu-2"
        options={[
          { text: 'Tänään', value: 'tanaan' },
          { text: 'Viikon sisällä', value: 'viikon-sisalla' },
          { text: 'Kuukauden sisällä', value: 'kuukauden-sisalla' },
        ]}
        value={undefined}
        onChange={(value) => {}}
      >
        <span>Valitse aikaväli</span>
      </DropdownMenuGroup.DropdownMenu>
      <DropdownMenuGroup.DropdownMenu
        id="menu-3"
        options={[
          { text: 'Suomi', value: 'suomi' },
          { text: 'Svenska', value: 'svenska' },
          { text: 'English', value: 'english' },
        ]}
        value={undefined}
        onChange={(value) => {}}
      >
        <span>Valitse kieli</span>
      </DropdownMenuGroup.DropdownMenu>
    </DropdownMenuGroup>
  </div>
  ```
</details>

### Vaalikone filters with multi-select menus

*[Live preview](https://design-system.yle.fi/docs/components/DropdownMenuGroup/)*

## API Reference

### DropdownMenuGroup Props

The DropdownMenuGroup component accepts all standard HTML `<div>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | Yes | — | DropdownMenu sub-components |
| `variant` | `'primary' \| 'text'` | No | `'primary'` | Visual style variant |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | No | `'md'` | Size of the buttons |
| `menuSize` | `'sm' \| 'md'` | No | `'md'` | Size of menu items |

### DropdownMenuGroup.DropdownMenu Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `id` | `string` | Yes | — | Unique identifier for the button |
| `options` | `(DropdownMenuOption<T> \| DropdownMenuSeparator)[]` | Yes | — | Array of menu options |
| `value` | `T \| undefined` | No | — | Selected value (controlled) |
| `defaultValue` | `T \| undefined` | No | — | Initial selected value (uncontrolled) |
| `onChange` | `(value: T, id: string) => void` | No | — | Callback when selection changes |
| `menuItemVariant` | `'default' \| 'radio'` | No | `'default'` | Visual variant of menu items |
| `alignMenu` | `'left' \| 'right'` | No | `'right'` | Horizontal alignment of menu |
| `onOpen` | `() => void` | No | — | Callback when menu opens |
| `onClose` | `() => void` | No | — | Callback when menu closes |
| `openMenuOnClick` | `boolean` | No | `true` | Whether clicking opens menu |

### DropdownMenuGroup.DropdownMenuMultiSelect Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `id` | `string` | Yes | — | Unique identifier for the button |
| `options` | `(DropdownMenuOption<T> \| DropdownMenuSeparator)[]` | Yes | — | Array of menu options |
| `value` | `T[] \| undefined` | No | — | Selected values (controlled) |
| `defaultValue` | `T[] \| undefined` | No | — | Initial selected values (uncontrolled) |
| `onChange` | `(value: T[], id: string) => void` | No | — | Callback when selection changes |
| `menuItemVariant` | `'default' \| 'checkbox'` | No | `'default'` | Visual variant of menu items |
| `alignMenu` | `'left' \| 'right'` | No | `'right'` | Horizontal alignment of menu |
| `onOpen` | `() => void` | No | — | Callback when menu opens |
| `onClose` | `() => void` | No | — | Callback when menu closes |
| `openMenuOnClick` | `boolean` | No | `true` | Whether clicking opens menu |

### Type Definitions

```tsx
export interface DropdownMenuGroupDSProps {
  children: React.ReactNode;
  variant?: 'primary' | 'text';
  size?: 'xs' | 'sm' | 'md' | 'lg';
  menuSize?: 'sm' | 'md';
}

export type DropdownMenuGroupProps = Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> &
  DropdownMenuGroupDSProps;

export type DropdownMenuGroupDropdownMenuSingleSelectProps<T> = {
  id: string;
  options?: (DropdownMenuOption<T> | DropdownMenuSeparator)[];
  value?: T;
  defaultValue?: T;
  onChange?: (value: T, id: string) => void;
  menuItemVariant?: 'default' | 'radio';
  alignMenu?: 'left' | 'right';
  onOpen?: () => void;
  onClose?: () => void;
  openMenuOnClick?: boolean;
};

export type DropdownMenuGroupDropdownMenuMultiSelectProps<T> = {
  id: string;
  options?: (DropdownMenuOption<T> | DropdownMenuSeparator)[];
  value?: T[];
  defaultValue?: T[];
  onChange?: (value: T[], id: string) => void;
  menuItemVariant?: 'default' | 'checkbox';
  alignMenu?: 'left' | 'right';
  onOpen?: () => void;
  onClose?: () => void;
  openMenuOnClick?: boolean;
};
```

## Related Components

- [DropdownMenu](../DropdownMenu/DropdownMenu.md) – Standalone dropdown menu component
- [ActionMenu](../ActionMenu/ActionMenu.md) – Base component used internally
- [MenuItem](../Menu/Menu.md) – Used internally for menu items
- [ButtonGroup](../ButtonGroup/ButtonGroup.md) – Alternative for single-selection groups with form semantics
- [CheckboxGroup](../Checkbox/Checkbox.md) – Alternative for multiple selection in forms
- [NavigationTabs](../NavigationTabs/NavigationTabs.md) – Page-level navigation between major sections
- [SectionTabs](../SectionTabs/SectionTabs.md) – Switching content within a single page or section

# FormElementDescription

A FormElementDescription is a text component used to provide additional help text, guidance, or clarifications below form labels and inputs. It helps users understand what information is expected or required for a specific field, improving form usability and reducing errors.

<Resources
  storybookUrl="https://ds-storybook.test.yle.fi/?path=/docs/components-FormElementDescription--docs"
  githubUrl="https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/FormElementDescription/FormElementDescription.mdx"
/>

*[Live preview](https://design-system.yle.fi/docs/components/FormElementDescription/)*

<details open>
<summary>Code example</summary>

```tsx
import { FormElementDescription } from '@yleisradio/yds-components-react';

<FormElementDescription text="This field accepts email addresses in the format: name@example.com" />
```
</details>

## Why to use

FormElementDescription enhances form clarity and user guidance. Using this component provides:

- **User guidance**: Provides contextual help and clarification about what input is expected
- **Error prevention**: Clear instructions reduce user mistakes and form abandonment
- **Accessibility**: Works with form labels and inputs to create a complete accessible form experience

## When to use

Use the **FormElementDescription** component only when you're building a custom form (e.g. native inputs with [FormElementLabel](../FormElementLabel/FormElementLabel.md)) and need help text below a field. For YDS form components (TextInput, Select, TextArea, etc.), use their `label` and `description` props instead of this component.

> **Do**
> - Format requirements (e.g. date, phone) or input constraints (length, characters)
> - A short example of valid input or optional-field hint

> **Don't**
> - Don't use with YDS form components — use the form component's `label` and `description` props instead
> - Don't use as the field label — use [FormElementLabel](../FormElementLabel/FormElementLabel.md) or the form component's `label` prop
> - Don't use for validation errors — use the form element's error state or error prop
> - Don't put critical or required info only in the description — keep it in the label or visible UI

## Writing Guidelines

> **Do**
> - Write in a conversational, helpful tone
> - Use concrete examples when describing formats or requirements
> - Keep descriptions short and concise

> **Don't**
> - Don't use overly technical language or jargon
> - Don't write in all caps or use excessive punctuation
> - Don't make descriptions longer than one or two sentences
> - Don't use descriptions to explain why a field is required (use the isRequired prop on FormElementLabel instead)

## Key FormElementDescription Props

Use these props to configure the FormElementDescription component.

### text

The descriptive text content displayed below the form input. This provides helpful guidance or clarification.

| Type     | Example                                              | Description                            |
| -------- | ---------------------------------------------------- | -------------------------------------- |
| `string` | <FormElementDescription text="Format: DD.MM.YYYY" /> | Help text displayed in the description |

<details>
<summary>Code example</summary>

```tsx
  <FormElementDescription text="Format: DD.MM.YYYY" />
  <FormElementDescription text="Must be at least 8 characters long" />
  <FormElementDescription text="Example: john.doe@example.com" />
  ```
</details>

## Behavior

- The description text is displayed as a paragraph element below the form input
- The component is always visible (no hidden states)
- Text styling is consistent across all form descriptions for visual hierarchy
- The description is associated with its form control through proximity and context

## Accessibility

- The description should be associated with its form input using the `id` attribute and `aria-describedby`
- Help text is available to screen reader users and provides important context
- The component uses semantic HTML (`<p>` element) for proper document structure

## API Reference

### Props

The FormElementDescription component accepts all standard HTML `<p>` attributes in addition to the following props:

| Prop   | Type     | Required | Default | Description                          |
| ------ | -------- | -------- | ------- | ------------------------------------ |
| `text` | `string` | No       | `''`    | The descriptive help text to display |

### Type Definitions

```tsx
export interface FormElementDescriptionProps
  extends React.LabelHTMLAttributes<HTMLParagraphElement> {
  text?: string;
}
```

## Related Components

- [FormElementLabel](../FormElementLabel/FormElementLabel.md) – Labels for form inputs
- [FormGroupLabel](../FormGroupLabel/FormGroupLabel.md) – Labels for groups of related form elements

# FormElementLabel

A FormElementLabel is a text component used to label form elements like inputs, textareas, and select fields. It provides accessible labeling and visual hierarchy for form fields, ensuring clear associations between labels and their corresponding form controls.

<Resources
  storybookUrl="https://ds-storybook.test.yle.fi/?path=/docs/components-FormElementLabel--docs"
  githubUrl="https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/FormElementLabel/FormElementLabel.mdx"
/>

*[Live preview](https://design-system.yle.fi/docs/components/FormElementLabel/)*

<details open>
<summary>Code example</summary>

```tsx
import { FormElementLabel } from '@yleisradio/yds-components-react';

<FormElementLabel label="Email address" isRequired />
```
</details>

## Why to use

FormElementLabel ensures proper semantic HTML and accessibility standards for form labels. Using this component provides:

- **Accessibility**: Properly associates labels with form inputs through the `for` attribute, improving usability for screen reader users
- **Consistency**: Provides a unified styling and behavior across all form labels in Yle applications
- **Flexibility**: Supports visual indicators for required fields, optional fields, disabled states, and visually-hidden labels for specific use cases
- **Built-in spacing**: Manages margin and spacing automatically, reducing the need for custom CSS

## When to use

Use FormElementLabel when you need a visible, accessible label for a single form control.

> **Do**
> - Custom form elements that need to align with YDS form components

> **Don't**
> - Don't use for content that isn't `label` element — for headings that group multiple fields (eg. Radios and Checkboxes), use [FormGroupLabel](../FormGroupLabel/FormGroupLabel.md) instead
> - Don't use FormElementLabel for YDS form components – use the form component's `label` and `labelOptions` props instead

## Writing Guidelines

> **Do**
> - Write labels in active voice and from the user's perspective (e.g., "Your email address" instead of "Email address to be entered")
> - Use simple, familiar words that users understand without needing to look up definitions
> - Keep labels concise but descriptive enough to be useful
> - Use sentence case for consistency (capitalize the first word only)
> - Include units of measurement in labels when relevant (e.g., "Weight (kg)")
> - Be specific about what information is expected (e.g., "Phone number (with country code)")

> **Don't**
> - Don't use all caps or excessive punctuation in labels
> - Don't repeat words from the placeholder text in your label
> - Don't use abbreviations unless they're universally understood
> - Don't make labels overly long - break into multiple labels if needed
> - Don't use ambiguous or vague wording like "Enter information" or "Add details"

## Key FormElementLabel Props

Use these props to configure the FormElementLabel component.

### label

The main text content displayed for the label. This is the primary text that describes the associated form element.

| Type     | Example                                | Description                 |
| -------- | -------------------------------------- | --------------------------- |
| `string` | <FormElementLabel label="Full name" /> | Text displayed in the label |

<details>
<summary>Code example</summary>

```tsx
  <FormElementLabel label="Full name" />
  <FormElementLabel label="Email address" />
  ```
</details>

### isRequired

Indicates whether the associated form field is required. When true, the label is typically styled to show it's mandatory.

| Type      | Example                                       | Description                 |
| --------- | --------------------------------------------- | --------------------------- |
| `boolean` | <FormElementLabel label="Email" isRequired /> | Marks the field as required |

<details>
<summary>Code example</summary>

```tsx
  <FormElementLabel label="Email" isRequired />
  <FormElementLabel label="Optional note" isRequired={false} />
  ```
</details>

### optionalLabel

Additional text displayed alongside the main label to indicate optional fields. Only shows when `isRequired` is false.

| Type     | Example                                                       | Description                    |
| -------- | ------------------------------------------------------------- | ------------------------------ |
| `string` | <FormElementLabel label="Phone" optionalLabel="(optional)" /> | Text indicating optional field |

<details>
<summary>Code example</summary>

```tsx
  <FormElementLabel label="Phone" optionalLabel="(optional)" />
  <FormElementLabel label="Website" optionalLabel="(not required)" />
  ```
</details>

### isDisabled

Disables the label visually, typically used when the associated form field is disabled.

| Type      | Example                                                | Description                      |
| --------- | ------------------------------------------------------ | -------------------------------- |
| `boolean` | <FormElementLabel label="Disabled field" isDisabled /> | Displays label in disabled state |

<details>
<summary>Code example</summary>

```tsx
  <FormElementLabel label="Archived field" isDisabled />
  <FormElementLabel label="Active field" isDisabled={false} />
  ```
</details>

### isHidden

Hides the label visually while keeping it accessible to screen readers (using the `visually-hidden` class).

| Type      | Example                                      | Description                     |
| --------- | -------------------------------------------- | ------------------------------- |
| `boolean` | <FormElementLabel label="Search" isHidden /> | Hides label from visual display |

<details>
<summary>Code example</summary>

```tsx
  <FormElementLabel label="Search query" isHidden />
  <FormElementLabel label="Username" isHidden={false} />
  ```
</details>

### hasMarginBottom

Controls whether the label includes bottom margin spacing. Enabled by default to provide spacing from the associated form element.

| Type      | Example                                           | Description                     |
| --------- | ------------------------------------------------- | ------------------------------- |
| `boolean` | <FormElementLabel label="Name" hasMarginBottom /> | Adds bottom margin to the label |

<details>
<summary>Code example</summary>

```tsx
  <FormElementLabel label="Name" hasMarginBottom={true} />
  <FormElementLabel label="Name" hasMarginBottom={false} />
  ```
</details>

## Behavior

- The label is always associated with the input and appears above or beside it.
- The label text displays with standard styling by default.
- When `isRequired` is false, `optionalLabel` is displayed alongside the main label.
- When `optionalLabel` is provided, it displays alongside the main label for optional fields (when `isRequired` is false).
- Disabled labels appear with reduced styling when the associated input is disabled.
- Visually-hidden labels remain accessible to screen readers while not displaying on the page.
- Bottom margin is applied by default to create spacing from the associated input.
- The label can be associated with form controls using the `htmlFor` attribute or by wrapping the control.

## Accessibility

- The label uses semantic `<label>` HTML elements to properly associate with form inputs.
- Labels must always be present or programmatically associated with form controls.
- Screen readers announce labels clearly, providing context for form navigation.<br /> ([WCAG 3.3.2 — Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions))
- Optional fields are described appropriately to users.
- Visually-hidden labels maintain full accessibility for screen reader users.

## API Reference

### Props

The FormElementLabel component accepts all standard HTML `<label>` attributes in addition to the following props:

| Prop              | Type      | Required | Default | Description                                                                         |
| ----------------- | --------- | -------- | ------- | ----------------------------------------------------------------------------------- |
| `label`           | `string`  | No       | `''`    | The main text content displayed for the label                                       |
| `optionalLabel`   | `string`  | No       | —       | Additional text to indicate optional fields (only shows when `isRequired` is false) |
| `isRequired`      | `boolean` | No       | `false` | Indicates whether the associated form field is required                             |
| `isDisabled`      | `boolean` | No       | `false` | Disables the label visually when the form field is disabled                         |
| `isHidden`        | `boolean` | No       | `false` | Hides the label visually while keeping it accessible to screen readers              |
| `hasMarginBottom` | `boolean` | No       | `true`  | Controls whether the label includes bottom margin spacing                           |

### Type Definitions

```tsx
export interface FormElementLabelDSProps {
  label?: string;
  optionalLabel?: string;
  isRequired?: boolean;
  isDisabled?: boolean;
  isHidden?: boolean;
  hasMarginBottom?: boolean;
}

export type FormElementLabelProps = React.LabelHTMLAttributes<HTMLLabelElement> &
  FormElementLabelDSProps;
```

## Related Components

- [FormElementDescription](../FormElementDescription/FormElementDescription.md) – Provides additional help text or description below form labels
- [FormGroupLabel](../FormGroupLabel/FormGroupLabel.md) – Labels groups of related form elements or field sets

# FormGroupLabel

A FormGroupLabel is a semantic label component used to label groups of related form elements, such as radio buttons, checkboxes, or other fieldsets. It serves as the legend for grouped form controls, providing clear context and improving accessibility and user understanding.

<Resources
  storybookUrl="https://ds-storybook.test.yle.fi/?path=/docs/components-FormGroupLabel--docs"
  githubUrl="https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/FormGroupLabel/FormGroupLabel.mdx"
/>

*[Live preview](https://design-system.yle.fi/docs/components/FormGroupLabel/)*

<details open>
<summary>Code example</summary>

```tsx
import { FormGroupLabel } from '@yleisradio/yds-components-react';

<FormGroupLabel label="Contact preference" isRequired />
```
</details>

## Why to use

FormGroupLabel ensures proper semantic HTML and accessibility for grouped form elements. Using this component provides:

- **Accessibility**: Uses the semantic `<legend>` element to properly associate labels with grouped form controls
- **Semantic HTML**: Follows HTML standards for fieldset legends, improving document structure
- **Screen reader support**: Screen readers announce the legend to users, providing context for form groups
- **Consistency**: Ensures visual and behavioral consistency across all grouped form labels in Yle applications
- **Flexibility**: Supports required and optional indicators, hidden labels, and additional content

## When to use

Use FormElementLabel when you need a visible, accessible label for a single form control.

> **Do**
> - Custom grouped form elements that need to align with YDS form components

> **Don't**
> - Don't use for content that is a `label` element — for headings that are assigned to single fields (eg. Text inputs and Selects), use [FormElementLabel](../FormElementLabel/FormElementLabel.md) instead
> - Don't use FormGroupLabel for YDS form components – use the form component's `label` and `labelOptions` props instead

## Writing Guidelines

> **Do**
> - Write group labels from the user's perspective (e.g., "How would you like to be contacted?" instead of "Contact method selection")
> - Use simple, clear language that describes the choice or grouping
> - Keep labels concise but descriptive enough to be useful
> - Use sentence case for consistency
> - Be specific about what you're asking (e.g., "Which subscription level interests you?")

> **Don't**
> - Don't use all caps or excessive punctuation
> - Don't make labels overly long - consider breaking into multiple groups if needed
> - Don't use ambiguous wording like "Choose options" without clarifying context
> - Don't use technical jargon that users won't understand

## Key FormGroupLabel Props

Use these props to configure the FormGroupLabel component.

### label

The main text content displayed for the group label. This describes the purpose of the grouped form elements.

| Type     | Example                                       | Description                       |
| -------- | --------------------------------------------- | --------------------------------- |
| `string` | <FormGroupLabel label="Contact preference" /> | Text displayed in the group label |

<details>
<summary>Code example</summary>

```tsx
  <FormGroupLabel label="Contact preference" />
  <FormGroupLabel label="Billing frequency" />
  ```
</details>

### isRequired

Indicates whether the grouped form controls require a selection. When true, the label is typically styled to show it's mandatory.

| Type      | Example                                                  | Description                 |
| --------- | -------------------------------------------------------- | --------------------------- |
| `boolean` | <FormGroupLabel label="Contact preference" isRequired /> | Marks the group as required |

<details>
<summary>Code example</summary>

```tsx
  <FormGroupLabel label="Contact preference" isRequired />
  <FormGroupLabel label="Additional options" isRequired={false} />
  ```
</details>

### optionalLabel

Additional text displayed alongside the main label to indicate optional groups. Only shows when `isRequired` is false.

| Type     | Example                                                           | Description                    |
| -------- | ----------------------------------------------------------------- | ------------------------------ |
| `string` | <FormGroupLabel label="Preferences" optionalLabel="(optional)" /> | Text indicating optional group |

<details>
<summary>Code example</summary>

```tsx
  <FormGroupLabel label="Additional preferences" optionalLabel="(optional)" />
  <FormGroupLabel label="Extra options" optionalLabel="(not required)" />
  ```
</details>

### isHidden

Hides the label visually while keeping it accessible to screen readers (using the `visually-hidden` class).

| Type      | Example                                      | Description                     |
| --------- | -------------------------------------------- | ------------------------------- |
| `boolean` | <FormGroupLabel label="Category" isHidden /> | Hides label from visual display |

<details>
<summary>Code example</summary>

```tsx
  <FormGroupLabel label="Select category" isHidden />
  <FormGroupLabel label="Choose option" isHidden={false} />
  ```
</details>

## Behavior

- The label is rendered as a `<legend>` element within a `<fieldset>` for semantic HTML
- The legend is associated with all grouped form controls within the fieldset
- Visual styling indicates required/optional status through indicators

## Accessibility

- Screen readers announce the legend before reading individual form controls in the group
- Screen readers announce the legend to provide context for the grouped controls

## API Reference

### Props

The FormGroupLabel component accepts all standard HTML `<legend>` attributes in addition to the following props:

| Prop            | Type      | Required | Default | Description                                                                         |
| --------------- | --------- | -------- | ------- | ----------------------------------------------------------------------------------- |
| `label`         | `string`  | No       | `''`    | The main text content displayed for the group label                                 |
| `optionalLabel` | `string`  | No       | —       | Additional text to indicate optional groups (only shows when `isRequired` is false) |
| `isRequired`    | `boolean` | No       | `false` | Indicates whether the grouped form controls require a selection                     |
| `isHidden`      | `boolean` | No       | `false` | Hides the label visually while keeping it accessible to screen readers              |

### Type Definitions

```tsx
export interface FormGroupLabelDSProps {
  label?: string;
  optionalLabel?: string;
  isRequired?: boolean;
  isHidden?: boolean;
}

export type FormGroupLabelProps = React.HTMLAttributes<HTMLLegendElement> & FormGroupLabelDSProps;
```

## Related Components

- [FormElementLabel](../FormElementLabel/FormElementLabel.md) – Labels for individual form inputs
- [FormElementDescription](../FormElementDescription/FormElementDescription.md) – Help text for form fields

```

```

# Link

A styled anchor element that provides consistent link styling and optionally displays an external link icon next to the link text.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=252-180)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-link--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Link/Link.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/Link/)*

<details open>
<summary>Code example</summary>

```tsx
import { Link } from '@yleisradio/yds-components-react';

<Link href="#">Link text</Link>
```
</details>

## Why to Use

Link ensures consistent anchor styling across Yle services without repeating style definitions. The built-in external link icon provides a standard visual affordance when linking to outside destinations, removing the need to implement it per-service.

## When to Use

Use Link for navigational anchor elements that take users to a new location within the same app or to an external URL.

> **Do**
> - Use for inline text links within body copy or lists.
> - Use for navigation links in headers, footers, and menus.
> - Use `isExternal` when the link navigates to a URL outside the current application.

> **Don't**
> - Don't use Link to trigger actions — use [Button](../Button/Button.md) instead.
> - Don't use Link for category or keyword labels — use [TagLink](../TagLink/TagLink.md) instead.

## Writing Guidelines

Link text must clearly describe the destination so users can predict where the link leads without reading surrounding content.

> **Do**
> - Use descriptive text that makes sense out of context (e.g. "Read the accessibility report").
> - Keep link text concise, ideally 2–5 words.

> **Don't**
> - Don't use generic text like "click here", "read more", or "link".
> - Don't repeat the full URL as link text for external links.

## Key Link Props

Use these props to configure the Link component.

### isExternal

When `true`, renders an `ExternalLink` icon alongside the link text to signal that the destination is outside the current application. Defaults to `false`.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Link href="#" isExternal>Yle.fi</Link> | Displays an external link icon next to the text. |

<details>
<summary>Code example</summary>

```tsx
<Link href="https://yle.fi" isExternal>Yle.fi</Link>
```
</details>

### externalLinkIconPosition

Controls whether the external link icon appears before or after the link text. Only relevant when `isExternal` is `true`. Defaults to `'after'`.

| Value | Example | Description |
|-------|---------|-------------|
| `'after'` | <Link href="#" isExternal externalLinkIconPosition="after">Yle.fi</Link> | Icon placed after the text. |
| `'before'` | <Link href="#" isExternal externalLinkIconPosition="before">Yle.fi</Link> | Icon placed before the text. |

<details>
<summary>Code example</summary>

```tsx
<Link href="https://yle.fi" isExternal externalLinkIconPosition="after">Yle.fi</Link>
<Link href="https://yle.fi" isExternal externalLinkIconPosition="before">Yle.fi</Link>
```
</details>

## Behavior

- Renders a standard HTML `<a>` element; all native anchor attributes (`href`, `target`, `rel`, etc.) are forwarded.
- When `isExternal` is `true` and `externalLinkIconPosition` is `'after'` (default), the icon is rendered after the children.
- When `isExternal` is `true` and `externalLinkIconPosition` is `'before'`, the icon is rendered before the children.
- The external link icon is decorative and wrapped in a non-interactive span.

## Accessibility

- Link text must be descriptive enough to convey the destination without relying on surrounding context.<br />([WCAG 2.4.6 — Headings and Labels](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels))
- When linking to an external site, consider adding `rel="noopener noreferrer"` and informing users via link text or a visually hidden label that the link opens externally.<br />([WCAG 2.4.4 — Link Purpose](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context))
- The `ExternalLink` icon is decorative; ensure the link text alone communicates the destination.

## API Reference

### Props

The Link component accepts all standard HTML `<a>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `isExternal` | `boolean` | No | `false` | Displays an external link icon next to the text. |
| `externalLinkIconPosition` | `'after' \| 'before'` | No | `'after'` | Position of the external link icon relative to the text. |
| `children` | `React.ReactNode` | No | — | Content of the link. |

### Type Definitions

```tsx
export interface LinkDSProps {
  isExternal?: boolean;
  externalLinkIconPosition?: 'after' | 'before';
  children?: React.ReactNode;
}

export type LinkProps = LinkDSProps & AnchorHTMLAttributes<HTMLAnchorElement>;
```

## Related Components

- [TagLink](../TagLink/TagLink.md) – An interactive keyword link for navigational context on articles or content items.
- [Button](../Button/Button.md) – For triggering actions rather than navigation.

# LiveSearchInput

LiveSearchInput is a search field that updates results in real-time as the user types. It is ideal for searching large content sets where users are likely to know what they are looking for.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=3777-1839&p=f&t=U4uSG0M5o85iz0VX-0)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-livesearchinput--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/LiveSearchInput/LiveSearchInput.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

export const LiveSearchExample = () => {
  const [value, setValue] = useState('');
  return (
    *[Live preview](https://design-system.yle.fi/docs/components/LiveSearchInput/)*
  );
};

<LiveSearchExample />

<details open>
<summary>Code example</summary>

```tsx
import { LiveSearchInput } from '@yleisradio/yds-components-react';

const [value, setValue] = useState('');

<LiveSearchInput
  label="Live Search"
  placeholder="Search articles"
  description="Live Search Input description"
  value={value}
  onChange={(e) => setValue(e.target.value)}
/>;
```
</details>

## Why to use

LiveSearchInput improves the search experience by providing instant feedback as users type, allowing them to refine queries without submitting.

It enables faster interaction, reduces cognitive load through recognition over recall, and guides users with real-time results and suggestions. This makes it especially effective for large datasets, aligns with familiar search patterns, supports filtering, and helps avoid empty or unsuccessful searches.

## When to use

Use LiveSearchInput when users need to search a content set by typing keywords and seeing results update in real-time.

> **Do**
> - Use LiveSearchInput for services with large content sets where users may not find content by browsing.
> - Use it for global search (e.g., header search) or scoped search within a page or section.
> - Use it when users are likely to know what they want to search for (keywords, titles, names).
> - Use it when fast, real-time feedback improves efficiency and reduces unnecessary clicks.
> - Use it with lists and tables to quickly filter and find rows within large datasets.

> **Don't**
> - Don't use LiveSearchInput for choosing from predefined options — use [Select](../Select/Select.md) or [ComboboxSingleSelect](../ComboboxSingleSelect/ComboboxSingleSelect.md).
> - Don't place LiveSearchInput where search is not relevant or expected.
> - Don't use it for small content sets where users can find content by browsing.
> - Don't use it when users are unlikely to know what to search for — prefer browsing or navigation instead.

## Content Guidelines

LiveSearchInput text should help users understand what they can search and how. Keep labels and placeholders short, familiar, and specific to the search scope.

> **Do**
> - Use a clear label that describes the search scope (e.g., "Hae", "Hae artikkeleita", "Hae ohjelmia").
> - Use placeholder text as an example (e.g., "Kirjoita hakusana", "Hae artikkeleita").
> - If the scope is not obvious, add helper text nearby (e.g., "Hakee vain ohjelmista").

> **Don't**
> - Don't rely on placeholder text alone to explain purpose.
> - Don't duplicate the label in the placeholder.
> - Don't use long instructional placeholders or rules — put constraints in helper text instead.
> - Don't use jargon or unclear labels that don't indicate what is being searched.

## Anatomy

![LiveSearchInput anatomy](../../img/live-search-input-anatomy.svg)

1. **Icon** – Optional search icon.
2. **Search text (placeholder** – Example text inside the field.
3. **Search field (input)** – Area where the user types the query.
4. **Clear button** – Appears automatically when text is present; clears the field.

## Key Props

Use the following props to customize the LiveSearchInput component to fit your needs.

LiveSearchInput extends TextInput, so it also supports all [TextInput props](../TextInput/TextInput.md#key-props), except for `icon` and `submitButton`.

### label

The visible label for the input field. Unlike SearchInput, the label is **visible by default**.

| Type     | Required | Description                        |
| -------- | -------- | ---------------------------------- |
| `string` | Yes      | Text displayed as the input label. |

### labelOptions

Customize label behavior, such as hiding it visually while keeping it accessible for screen readers.

| Type                    | Default               | Description                             |
| ----------------------- | --------------------- | --------------------------------------- |
| `FormElementLabelProps` | `{ isHidden: false }` | Options for label display and behavior. |

<details>
<summary>Code example</summary>

```tsx
  <LiveSearchInput
    label="Search"
    labelOptions={{ isHidden: true }}
    placeholder="Search articles"
    value={query}
    onChange={(e) => setQuery(e.target.value)}
  />
  ```
</details>

### description

Helper text displayed below the input field, providing additional context to the user.

| Type     | Default | Description                             |
| -------- | ------- | --------------------------------------- |
| `string` | —       | Descriptive text shown below the input. |

### errorMessage

Displays a validation error message below the input and applies error styling to the field.

| Type     | Default | Description                                   |
| -------- | ------- | --------------------------------------------- |
| `string` | —       | Error message shown below the input when set. |

### isDisabled

Disables the input, preventing user interaction while keeping the field visible.

| Type      | Default | Description                                         |
| --------- | ------- | --------------------------------------------------- |
| `boolean` | `false` | Disables the input and sets `aria-disabled="true"`. |

### isRequired

Marks the input field as required.

| Type      | Default | Description                         |
| --------- | ------- | ----------------------------------- |
| `boolean` | `false` | Sets the input as a required field. |

### showLoadingIndicator

Shows a loading spinner inside the input field, typically used while fetching search results.

| Type      | Default | Description                                          |
| --------- | ------- | ---------------------------------------------------- |
| `boolean` | `false` | Displays a loading indicator inside the input field. |

<details>
<summary>Code example</summary>

```tsx
  <LiveSearchInput
    label="Search"
    placeholder="Search articles"
    value={query}
    onChange={(e) => setQuery(e.target.value)}
    showLoadingIndicator
  />
  ```
</details>

### iconBefore

Overrides the default search (magnifying glass) icon displayed before the input. Defaults to `{ componentFn: Search, ariaLabel: 'Hae' }`.

| Type             | Default                                     | Description                           |
| ---------------- | ------------------------------------------- | ------------------------------------- |
| `InputIconProps` | `{ componentFn: Search, ariaLabel: 'Hae' }` | Icon rendered before the input field. |

### iconClear

Overrides the default clear button built with [`createClearIcon`](../TextInput/TextInput.md#createclearicon). Hidden while `value` is an empty string.

| Type             | Default                                              | Description                                    |
| ---------------- | ---------------------------------------------------- | ---------------------------------------------- |
| `InputIconProps` | `createClearIcon({ ariaLabel: 'Tyhjennä', value })` | Clear button; hidden when `value` is empty. |

### hideIcon

Hides the default search icon (magnifying glass) before the input field.

| Type      | Default | Description                               |
| --------- | ------- | ----------------------------------------- |
| `boolean` | `false` | If true, the search icon is not rendered. |

### iconBeforeAriaLabel

Custom aria-label for the search icon. Defaults to "Hae".

| Type     | Default | Description                     |
| -------- | ------- | ------------------------------- |
| `string` | "Hae"   | Aria-label for the search icon. |

### iconClearAriaLabel

Custom aria-label for the clear button. Defaults to "Tyhjennä".

| Type     | Default    | Description                     |
| -------- | ---------- | ------------------------------- |
| `string` | "Tyhjennä" | Aria-label for the clear button |

## Behavior

- Results update in real-time as the user types — there is no explicit submit action.
- A clear button appears automatically when the field has text and clears the value when activated.
- The component can show a loading indicator (via `showLoadingIndicator`) while fetching results.
- The parent component is responsible for debouncing search requests if needed. This is especially important for asynchronous search requests or with large datasets.
- Disabled state prevents interaction but keeps the field visible.
- All interactive elements (input, clear) must be keyboard operable.
- Results should provide immediate, meaningful feedback (e.g., matches, no results, loading state).
- Updates should feel responsive but not overwhelming — avoid overly rapid changes that can confuse users.

## Accessibility

- Always provide a label — it may be hidden visually, but it must remain accessible. This ensures users of assistive technologies know what the field is for. <br />([WCAG 3.3.2 — Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions)).
- The clear button has a built-in accessible label ("Tyhjennä"). <br />([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard)).
- Keyboard support: Tab/Shift+Tab moves focus between the input and clear button.
- The magnifying glass icon is a widely recognized symbol and doesn't need to include the word "search" visually. However, it must have an accessible label for screen readers. <br /> ([WCAG 3.3.2 — Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions)).
- Use screen-reader compatible feedback such as loading/disabled states, result counts, and empty states to guide users.

## Implementation examples

### Basic usage

export const BasicExample = () => {
  const [value, setValue] = useState('');
  return (
    *[Live preview](https://design-system.yle.fi/docs/components/LiveSearchInput/)*
  );
};

<BasicExample />

<details open>
<summary>Code example</summary>

```tsx
  const [value, setValue] = useState('');

  <LiveSearchInput
    label="Search"
    placeholder="Search articles"
    value={value}
    onChange={(e) => setValue(e.target.value)}
  />;
  ```
</details>

### Icon hidden

export const IconHiddenExample = () => {
  const [value, setValue] = useState('');
  return (
    *[Live preview](https://design-system.yle.fi/docs/components/LiveSearchInput/)*
  );
};

<IconHiddenExample />

<details open>
<summary>Code example</summary>

```tsx
  const [value, setValue] = useState('');

  <LiveSearchInput
    label="Search"
    placeholder="Search articles"
    value={value}
    onChange={(e) => setValue(e.target.value)}
    hideIcon
  />;
  ```
</details>

### Search with results

> **Note**
> There's currently no built-in component for displaying search results. You can use [Menu](../Menu/Menu.md) or custom list / table component to display the results – this example uses a simple unordered list for demonstration purposes.

export const SearchWithResultsExample = () => {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);
  const [isLoading, setIsLoading] = useState(false);
  const articles = [
    'Uutiset tänään: sää lämpenee viikonloppuna',
    'Kulttuuri: uusi näyttely avautuu Kiasmassa',
    'Urheilu: Suomi voitti jääkiekko-ottelun',
    'Tiede: uusi tutkimus ilmastonmuutoksesta',
    'Musiikki: kesän festivaalit julkistivat ohjelmansa',
    'Politiikka: hallitus esitteli uuden lakiehdotuksen',
  ];
  useEffect(() => {
    if (!query) {
      setResults([]);
      setIsLoading(false);
      return;
    }
    setIsLoading(true);
    const timer = setTimeout(() => {
      setResults(articles.filter((a) => a.toLowerCase().includes(query.toLowerCase())));
      setIsLoading(false);
    }, 800);
    return () => clearTimeout(timer);
  }, [query]);
  return (
    *[Live preview](https://design-system.yle.fi/docs/components/LiveSearchInput/)*
  );
};

<SearchWithResultsExample />

<details open>
<summary>Code example</summary>

```tsx
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);
  const [isLoading, setIsLoading] = useState(false);
  const items = ['Item one', 'Item two', 'Item three'];

useEffect(() => {
if (!query) {
setResults([]);
setIsLoading(false);
return;
}
setIsLoading(true);
const timer = setTimeout(() => {
setResults(items.filter((item) => item.toLowerCase().includes(query.toLowerCase())));
setIsLoading(false);
}, 800);
return () => clearTimeout(timer);
}, [query]);

  <LiveSearchInput
    label="Search"
    placeholder="Search items"
    value={query}
    onChange={(e) => setQuery(e.target.value)}
    showLoadingIndicator={isLoading}
  />
  {query && !isLoading && (
    <ul>
      {results.length > 0
        ? results.map((r) => <li key={r}>{r}</li>)
        : <li>No results found.</li>}
    </ul>
  )}
  ```
</details>

### With loading indicator

*[Live preview](https://design-system.yle.fi/docs/components/LiveSearchInput/)*
<details open>
<summary>Code example</summary>

```tsx
  <LiveSearchInput
    label="Search"
    placeholder="Search articles"
    value={query}
    onChange={(e) => setQuery(e.target.value)}
    showLoadingIndicator={isLoading}
  />
  ```
</details>

### With error message

*[Live preview](https://design-system.yle.fi/docs/components/LiveSearchInput/)*
<details open>
<summary>Code example</summary>

```tsx
  <LiveSearchInput
    label="Search"
    placeholder="Search articles"
    value={query}
    onChange={(e) => setQuery(e.target.value)}
    errorMessage={error}
  />
  ```
</details>

### Disabled

*[Live preview](https://design-system.yle.fi/docs/components/LiveSearchInput/)*
<details open>
<summary>Code example</summary>

```tsx
  <LiveSearchInput label="Search" placeholder="Search disabled" isDisabled />
  ```
</details>

## API Reference

### Props

#### LiveSearchInput

The LiveSearchInput component accepts all standard HTML `<input>` attributes in addition to the following props. LiveSearchInput extends TextInput, so it supports all TextInput props except `icon` and `submitButton`:

| Prop                   | Type                    | Required | Default                                              | Description                                     |
| ---------------------- | ----------------------- | -------- | ---------------------------------------------------- | ----------------------------------------------- |
| `label`                | `string`                | Yes      | —                                                    | Text displayed as the input label.              |
| `labelOptions`         | `FormElementLabelProps` | No       | `{ isHidden: false }`                                | Options for label display and behavior.         |
| `description`          | `string`                | No       | —                                                    | Helper text displayed below the input.          |
| `errorMessage`         | `string`                | No       | —                                                    | Error message shown below the input.            |
| `isDisabled`           | `boolean`               | No       | `false`                                              | Disables the input and sets `aria-disabled`.    |
| `isRequired`           | `boolean`               | No       | `false`                                              | Marks the input as required.                    |
| `showLoadingIndicator` | `boolean`               | No       | `false`                                              | Shows a loading spinner inside the input field. |
| `iconBefore`           | `InputIconProps`        | No       | `{ componentFn: Search, ariaLabel: 'Hae' }`          | Icon rendered before the input field.           |
| `iconClear`            | `InputIconProps`        | No       | `createClearIcon({ ariaLabel, value })`               | Clear button; hidden when `value` is empty.     |
| `hideIcon`             | `boolean`               | No       | `false`                                              | If true, the search icon is not rendered.       |
| `iconBeforeAriaLabel`  | `string`                | Yes      | "Hae"                                                | Aria-label for the search icon.                 |
| `iconClearAriaLabel`   | `string`                | Yes      | "Tyhjennä"                                           | Aria-label for the clear button.                |

### Type Definitions

#### LiveSearchInput

```tsx
export type LiveSearchInputDSProps = Omit<TextInputDSProps, 'icon' | 'submitButton'> & {
  hideIcon?: boolean;
  iconBeforeAriaLabel: string;
  iconClearAriaLabel: string;
};
```

## Related Components

- [SearchInput](../SearchInput/SearchInput.md): For submit-based search with an explicit search button.
- [TextInput](../TextInput/TextInput.md): For single-line text input.

# Menu

Menu is a low-level component that renders a positioned dropdown menu list with keyboard navigation, focus management, and automatic positioning. It provides the foundation for menu-based interactions in YDS.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=8762-5312)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-menulist--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Menu/Menu.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/Menu/)*

## Why to use

Menu provides a shared, internal foundation for all dropdown-style components in the design system. It centralizes complex logic for menu components in a consistent way.

By building ActionMenu, DropdownMenu, and other menu-based components on top of Menu, the design system ensures predictable behavior, accessibility, and visual consistency across products without duplicating low-level logic.

## When to use

Menu provides the underlying functionality for dropdown menus in YDS. Rely on Menu directly when you build menu-based patterns inside YDS or use higher-level components like ActionMenu or DropdownMenu that are built on top of Menu and provide specific interaction patterns.

> **Do**
> - Use Menu as the foundation for building custom menu-based components or patterns with YDS.

> **Don't**
> - Don't hide primary calls to action inside menus. Use menus for grouping secondary or contextual actions.
> - Don't use Menu for navigation. Use [ButtonGroup](../ButtonGroup/ButtonGroup.md) or [NavigationTabs](../NavigationTabs/NavigationTabs.md) instead.
> - Don't use multiple menu variants in the same space (e.g. mixing radio and checkbox menus) - use [DropdownMenuGroup](../DropdownMenuGroup/DropdownMenuGroup.md) instead.

### Menu is used internally by

| Component                       | Purpose                                                        | When to use                                                                               |
| ------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **ActionMenu**                  | Displays a list of actions without persistent selection.       | When the user needs to trigger one of several related actions (e.g. edit, delete, share). |
| **DropdownMenu**                | Displays selectable options with single or multiple selection. | When the user needs to choose values from a list (e.g. filters, sorting).                 |
| **DropdownMenuGroup**           | Groups multiple dropdown menus into a unified control area.    | When several related selections belong to the same task or context.                       |
| **Other menu-based components** | Reuse Menu for consistent dropdown behavior.                   | When building new YDS components that require menu-like interactions.                     |

## Content guidelines

> **Do**
> - Keep labels short, scannable, and consistent in structure.
> - Use verbs for actions (e.g. “Muokkaa”, “Jaa”, “Poista”) and nouns/adjectives for options (e.g. “Uusin”, “Suomi”).
> - Use MenuSeparator to group related items when the list has clear sections..

> **Don't**
> - Don’t use long sentences, instructions, or mixed grammar styles in the same menu.
> - Don’t use vague labels like “OK”, “Kyllä”, or “Valitse” without context.
> - Don’t create deep or nested menu structures — split into multiple menus or rethink the model.

## Anatomy

![Menu anatomy](../../img/menu-anatomy.svg)

1. **Menu (surface)** – The floating container rendered by the `Menu` component, positioned relative to the trigger (`rootElement`).
2. **MenuItem** – An individual interactive row inside the menu, representing an action or selectable option.
3. **MenuItem label** – The primary text content of a `MenuItem`, describing the action or option.
4. **MenuItem icon (optional)** – An optional leading icon inside a `MenuItem`, used to support recognition or categorization.
5. **Selected state** – Visual indication applied to a `MenuItem` when it represents the current value in selection-based menus.
6. **MenuSeparator (optional)** – A visual divider rendered with `MenuSeparator` to group related menu items.

NOTE! Selection groups (e.g. radio or checkbox) can be rendered inside the menu to support single-select or multi-select patterns in structured menus.

## Key MenuItem props

Use the following props to configure the MenuItem component.

### icon

Optional icon element displayed before the menu item label.

| Type                   | Example                                     | Description                                |
| ---------------------- | ------------------------------------------- | ------------------------------------------ |
| `ReactElement \| null` | <MenuItem icon={<Share />}>Share</MenuItem> | Icon component to display before the label |

<details>
<summary>Code example</summary>

```tsx
import { MenuItem } from '@yleisradio/yds-components-react';
import { Share } from '@yleisradio/yds-icons-react';

<MenuItem icon={<Share />}>Share</MenuItem>
```
</details>

### iconHighlight

Whether to highlight the icon area when the item is selected. Used to create space for a checkmark icon when `isSelected` is true.

| Type      | Example                                              | Description                             |
| --------- | ---------------------------------------------------- | --------------------------------------- |
| `boolean` | <MenuItem iconHighlight isSelected>Option</MenuItem> | Highlights icon area for selected state |

<details>
<summary>Code example</summary>

```tsx
  <MenuItem iconHighlight isSelected>
    Selected option
  </MenuItem>
  ```
</details>

### isDisabled

Whether the menu item is disabled and non-interactive.

| Type      | Example                                         | Description            |
| --------- | ----------------------------------------------- | ---------------------- |
| `boolean` | <MenuItem isDisabled>Disabled option</MenuItem> | Disables the menu item |

<details>
<summary>Code example</summary>

```tsx
  <MenuItem isDisabled>Disabled option</MenuItem>
  ```
</details>

### isSelected

Whether the menu item is in a selected state. Used for selection-based menus (e.g., DropdownMenu).

| Type      | Example                                  | Description              |
| --------- | ---------------------------------------- | ------------------------ |
| `boolean` | <MenuItem isSelected>Selected</MenuItem> | Indicates selected state |

<details>
<summary>Code example</summary>

```tsx
  <MenuItem isSelected>Selected option</MenuItem>
  ```
</details>

### itemVariant

Visual variant of the menu item. Determines how the item is rendered.

| Value      | Example                                                       | Description                             |
| ---------- | ------------------------------------------------------------- | --------------------------------------- |
| `default`  | <MenuItem itemVariant="default">Option</MenuItem>             | Default variant with icon and label     |
| `radio`    | <MenuItem itemVariant="radio" isSelected>Option</MenuItem>    | Radio button style for single selection |
| `checkbox` | <MenuItem itemVariant="checkbox" isSelected>Option</MenuItem> | Checkbox style for multiple selection   |

<details>
<summary>Code example</summary>

```tsx
  <MenuItem itemVariant="default" icon={<Share />}>
    Default item
  </MenuItem>
  <MenuItem itemVariant="radio" isSelected>
    Radio item
  </MenuItem>
  <MenuItem itemVariant="checkbox" isSelected>
    Checkbox item
  </MenuItem>
  ```
</details>

### children

The label text or content displayed in the menu item.

| Type              | Example                              | Description                         |
| ----------------- | ------------------------------------ | ----------------------------------- |
| `React.ReactNode` | <MenuItem>Menu item label</MenuItem> | Content to display in the menu item |

<details>
<summary>Code example</summary>

```tsx
  <MenuItem onSelect={() => {}}>Simple text label</MenuItem>
  <MenuItem onSelect={() => {}}>
    <span>Custom content</span>
  </MenuItem>
  ```
</details>

## Behavior

- Menu is rendered and positioned relative to its rootElement (typically a trigger button).
- The `position` prop controls the preferred direction in which the menu opens: `'bottom'` (default), `'top'`, `'left'`, or `'right'`.
- The `align` prop controls horizontal alignment of the menu relative to the trigger (`'left'` or `'right'`).
- The menu automatically adjusts its position to avoid being clipped by the viewport.
- Keyboard interaction:
  - Arrow keys move focus between menu items.
  - Enter or Space activates the focused item.
  - Escape closes the menu via the close callback.
  - Tabbing away closes the menu via navigateAway.
- Focus management:
  When autofocus is enabled, focus moves to the first menu item on open.
  When the menu closes, focus should return to the trigger (handled by the parent component).
- The menu is only visible when a valid rootElement is provided.

## Accessibility

Menu itself is a structural component. Accessibility is ensured through the patterns that use it (such as ActionMenu and DropdownMenu), but Menu enables those patterns by supporting correct focus and keyboard behavior.

- All interactions are fully keyboard accessible.<br />
  ([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html))
- Interactive items show a clear visual focus indicator.<br />
  ([WCAG 2.4.7 — Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html))
- Focus is managed predictably when the menu opens and closes.
- Parent components are responsible for applying correct ARIA roles and relationships (e.g. menu/menuitem, listbox/option, radiogroup/radio).
- Menu supports use inside complex contexts such as modals without allowing focus to escape unintentionally.

## Implementation Examples

### Custom Menu with checkboxes

Menu supporting multiple selection with checkboxes.

*[Live preview](https://design-system.yle.fi/docs/components/Menu/)*

### Custom Menu with radio buttons

Menu supporting single selection with radio buttons.

*[Live preview](https://design-system.yle.fi/docs/components/Menu/)*

## API Reference

### Props

The Menu component accepts the following props:

| Prop           | Type                           | Required | Default   | Description                          |
| -------------- | ------------------------------ | -------- | --------- | ------------------------------------ |
| `id`           | `string`                       | Yes      | —         | Unique identifier for the menu       |
| `rootElement`  | `HTMLElement \| null`          | Yes      | —         | Element to position menu relative to |
| `autofocus`    | `boolean`                      | Yes      | —         | Whether to focus first item on open  |
| `close`        | `() => void`                   | Yes      | —         | Callback to close the menu           |
| `buttonRef`    | `RefObject<HTMLButtonElement>` | Yes      | —         | Reference to trigger button          |
| `navigateAway` | `() => void`                   | Yes      | —         | Callback when navigating away        |
| `align`        | `'left' \| 'right'`            | No       | `'right'` | Horizontal alignment of menu         |
| `position`     | `'top' \| 'right' \| 'bottom' \| 'left'` | No | `'bottom'` | Preferred direction the menu opens   |
| `children`     | `React.ReactNode`              | Yes      | —         | Menu items to display                |

### Type Definitions

```tsx
export interface MenuProps {
  id: string;
  rootElement: HTMLElement | null;
  autofocus: boolean;
  close: () => void;
  buttonRef: RefObject<HTMLButtonElement>;
  navigateAway: () => void;
  align?: 'left' | 'right';
  children: ReactNode;
}

export const Menu = forwardRef<HTMLUListElement, MenuProps>;
```

### MenuContext

The Menu component uses MenuContext to access menu configuration:

```tsx
export interface MenuInterface {
  closeMenu?: () => void;
  menuSize: MenuSize;
}

export const MenuContext = createContext<MenuInterface>({ menuSize: 'md' });
```

Menu items can access the context to:

- Get the current menu size (`md` or `sm`)
- Access the `closeMenu` function if needed

## MenuItem API Reference

### Props

The MenuItem component accepts all standard HTML `<li>` attributes in addition to the following props:

| Prop               | Type                                 | Required | Default      | Description                                  |
| ------------------ | ------------------------------------ | -------- | ------------ | -------------------------------------------- |
| `icon`             | `ReactElement \| null`               | No       | `undefined`  | Icon element to display before the label     |
| `iconHighlight`    | `boolean`                            | No       | `false`      | Whether to highlight icon area when selected |
| `isDisabled`       | `boolean`                            | No       | `false`      | Whether the menu item is disabled            |
| `isSelected`       | `boolean`                            | No       | `false`      | Whether the menu item is selected            |
| `itemVariant`      | `'default' \| 'radio' \| 'checkbox'` | No       | `'default'`  | Visual variant of the menu item              |
| `onSelect`         | `() => void`                         | No       | —            | Callback fired when item is selected         |
| `closeMenuOnClick` | `boolean`                            | No       | `true`       | Whether to close menu when item is selected  |
| `role`             | `string`                             | No       | `'menuitem'` | ARIA role for the menu item                  |
| `children`         | `React.ReactNode`                    | Yes      | —            | Label text or content to display             |

### Type Definitions

```tsx
export interface MenuItemDSProps {
  icon?: ReactElement | null;
  iconHighlight?: boolean;
  isDisabled?: boolean;
  isSelected?: boolean;
  closeMenuOnClick?: boolean;
  onSelect?: () => void;
  role?: string;
  children: ReactNode;
  itemVariant?: 'default' | 'radio' | 'checkbox';
}

export type MenuItemProps = MenuItemDSProps & HTMLAttributes<HTMLLIElement>;
```

## MenuSeparator

MenuSeparator is a simple component used to visually separate menu items:

```tsx
export const MenuSeparator = (): JSX.Element;
```

<details>
<summary>Code example</summary>

```tsx
import { MenuItem, MenuSeparator } from '@yleisradio/yds-components-react';

<MenuItem onSelect={() => {}}>Option 1</MenuItem>
<MenuItem onSelect={() => {}}>Option 2</MenuItem>
<MenuSeparator />
<MenuItem onSelect={() => {}}>Option 3</MenuItem>
```
</details>

## Related Components

- [ActionMenu](../ActionMenu/ActionMenu.md) – Uses Menu internally for action-based menus
- [DropdownMenu](../DropdownMenu/DropdownMenu.md) – Uses Menu internally for selection-based menus
- [DropdownMenuGroup](../DropdownMenuGroup/DropdownMenuGroup.md) – Uses Menu internally for grouping multiple dropdown menus into a unified control area.
- [ComboboxSingleSelect](../ComboboxSingleSelect/ComboboxSingleSelect.md) uses Menu internally for the dropdown menu.

# Modal

Modal displays content in a centered overlay that blocks interaction with the underlying interface until the user completes or dismisses the task. Modal is responsible for overlay, focus management, keyboard handling, and scroll behavior, and it typically contains a Dialog component for structured content.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=9105-1860)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-modal--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Modal/Modal.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/Modal/)*

<details open>
<summary>Code example</summary>

```tsx
import { Modal, useModal, Dialog, Button, Dialog } from '@yleisradio/yds-components-react';

const { modalRef, openModal, closeModal } = useModal();

<>
  <Button onClick={openModal}>Open Modal</Button>
  <Modal modalRef={modalRef}>
    <Dialog
      title="Modal Title"
      actions={
        <>
          <Button variant="text" text="Cancel" onClick={closeModal} />
          <Button text="OK" onClick={closeModal} />
        </>
      }
    >
      <p>Modal content goes here</p>
    </Dialog>
  </Modal>
</>
```
</details>

## Why to use

Use Modal when you need to interrupt the user’s current flow to request a decision, confirmation, or focused input. Modal ensures consistent overlay behavior, focus trapping, keyboard interaction, and accessibility across all dialog-based interfaces in YDS. It standardizes how blocking dialogs behave and prevents common accessibility and usability issues related to custom modal implementations.

## When to use

Use Modal when the user must complete or explicitly dismiss a task before continuing.

> **Do**
> - Use Modal for confirmations, critical information, and forms that require focused attention.
> - Use Modal together with [Dialog](../Dialog/Dialog.md) to structure content consistently.
> - Use Modal for desktop and tablet experiences.

> **Don't**
> - Don’t use Modal for non-critical or purely informational content.
> - Don’t use Modal for mobile-first interactions — use [BottomSheet](../BottomSheet/BottomSheet.md) instead.
> - Don’t stack or nest modals.

## Content Guidelines

Use these guidelines when placing content inside a Modal. They apply especially when Modal contains a Dialog.

> **Do**
> - Ensure the modal has a clear title describing the task.
> - Keep content concise and focused on a single goal.
> - Use clear primary and secondary actions.

> **Don't**
> - Don’t overload the modal with long or multi-step flows.
> - Don’t include unnecessary secondary content.
> - Don’t use vague action labels like “OK” or “Kyllä”.

## Anatomy

![Modal anatomy](../../img/modal-anatomy.svg)

A modal dialog is composed of two distinct parts: the **Modal** and the **Dialog**. Together they form a complete, accessible modal dialog pattern where responsibilities are clearly separated between container behavior and content structure.

### Modal

1. **Close button** – Optional control used to dismiss the modal.
2. **Modal container** – The surface that holds the dialog content and visually separates it from the backdrop while managing focus and interaction.

### Dialog

3. **Dialog title** – Required heading that communicates the purpose of the modal.
4. **Content area** – The main content section for text, forms, or other components. Supports internal scrolling when content overflows.
5. **Actions area** – Optional footer containing one or more action buttons, typically a primary and a secondary action.

## Key Modal Props

Use these props to configure the Modal component.

### modalRef
Ref handle for controlling the modal (open/close). Use with `useModal` hook.

| Type | Example | Description |
|------|---------|-------------|
| `React.RefObject<ModalHandle>` | <ModalExample /> | Ref handle for programmatic control |

<details>
<summary>Code example</summary>

```tsx
const { modalRef, openModal, closeModal } = useModal();

<Modal modalRef={modalRef}>
  <div>Content here</div>
  <Button onClick={closeModal}>Close</Button>
</Modal>
```
</details>

### scrollBehavior
Scroll behavior for the modal content.

| Value | Example | Description |
|-------|---------|-------------|
| `content` | <ModalExample scrollBehavior="content"><div style={{ padding: '2rem 1.5rem 1.5rem', lineHeight: '2' }}>What is Lorem Ipsum? Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum. Why do we use it? It is a long established fact that a reader will be distracted by the readable content of a page when looking at its layout. The point of using Lorem Ipsum is that it has a more-or-less normal distribution of letters, as opposed to using 'Content here, content here', making it look like readable English. Many desktop publishing packages and web page editors now use Lorem Ipsum as their default model text, and a search for 'lorem ipsum' will uncover many web sites still in their infancy. Various versions have evolved over the years, sometimes by accident, sometimes on purpose (injected humour and the like). Where does it come from? Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words, consectetur, from a Lorem Ipsum passage, and going through the cites of the word in classical literature, discovered the undoubtable source. Lorem Ipsum comes from sections 1.10.32 and 1.10.33 of "de Finibus Bonorum et Malorum" (The Extremes of Good and Evil) by Cicero, written in 45 BC. This book is a treatise on the theory of ethics, very popular during the Renaissance. The first line of Lorem Ipsum, "Lorem ipsum dolor sit amet..", comes from a line in section 1.10.32. The standard chunk of Lorem Ipsum used since the 1500s is reproduced below for those interested. Sections 1.10.32 and 1.10.33 from "de Finibus Bonorum et Malorum" by Cicero are also reproduced in their exact original form, accompanied by English versions from the 1914 translation by H. Rackham. Where can I get some? There are many variations of passages of Lorem Ipsum available, but the majority have suffered alteration in some form, by injected humour, or randomised words which don't look even slightly believable. If you are going to use a passage of Lorem Ipsum, you need to be sure there isn't anything embarrassing hidden in the middle of text. All the Lorem Ipsum generators on the Internet tend to repeat predefined chunks as necessary, making this the first true generator on the Internet. It uses a dictionary of over 200 Latin words, combined with a handful of model sentence structures, to generate Lorem Ipsum which looks reasonable. The generated Lorem Ipsum is therefore always free from repetition, injected humour, or non-characteristic words etc.</div></ModalExample> | Restricts scrolling to modal content (default) |
| `body` | <ModalExample scrollBehavior="body"><div style={{ padding: '2rem 1.5rem 1.5rem', lineHeight: '2' }}>What is Lorem Ipsum? Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum. Why do we use it? It is a long established fact that a reader will be distracted by the readable content of a page when looking at its layout. The point of using Lorem Ipsum is that it has a more-or-less normal distribution of letters, as opposed to using 'Content here, content here', making it look like readable English. Many desktop publishing packages and web page editors now use Lorem Ipsum as their default model text, and a search for 'lorem ipsum' will uncover many web sites still in their infancy. Various versions have evolved over the years, sometimes by accident, sometimes on purpose (injected humour and the like). Where does it come from? Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words, consectetur, from a Lorem Ipsum passage, and going through the cites of the word in classical literature, discovered the undoubtable source. Lorem Ipsum comes from sections 1.10.32 and 1.10.33 of "de Finibus Bonorum et Malorum" (The Extremes of Good and Evil) by Cicero, written in 45 BC. This book is a treatise on the theory of ethics, very popular during the Renaissance. The first line of Lorem Ipsum, "Lorem ipsum dolor sit amet..", comes from a line in section 1.10.32. The standard chunk of Lorem Ipsum used since the 1500s is reproduced below for those interested. Sections 1.10.32 and 1.10.33 from "de Finibus Bonorum et Malorum" by Cicero are also reproduced in their exact original form, accompanied by English versions from the 1914 translation by H. Rackham. Where can I get some? There are many variations of passages of Lorem Ipsum available, but the majority have suffered alteration in some form, by injected humour, or randomised words which don't look even slightly believable. If you are going to use a passage of Lorem Ipsum, you need to be sure there isn't anything embarrassing hidden in the middle of text. All the Lorem Ipsum generators on the Internet tend to repeat predefined chunks as necessary, making this the first true generator on the Internet. It uses a dictionary of over 200 Latin words, combined with a handful of model sentence structures, to generate Lorem Ipsum which looks reasonable. The generated Lorem Ipsum is therefore always free from repetition, injected humour, or non-characteristic words etc.</div></ModalExample> | Allows entire page to scroll |

<details>
<summary>Code example</summary>

```tsx
const { modalRef, openModal, closeModal } = useModal();
<Modal scrollBehavior="content" modalRef={modalRef}>
  <div>Content here</div>
  <Button onClick={closeModal}>Close</Button>
</Modal>
<Modal scrollBehavior="body" modalRef={modalRef}>
  <div>Content here</div>
  <Button onClick={closeModal}>Close</Button>
</Modal>
```
</details>

## Behavior

- Modal opens when openModal() is called or when the ref’s open() method is invoked.
- Modal closes when closeModal() is called, the close button is clicked, or the Escape key is pressed.
- While open, Modal blocks interaction with background content and traps focus within the modal.
- Body scroll is disabled by default (scrollBehavior="content") to prevent background scrolling, and the page scroll position is preserved when the modal opens.
- Clicking the backdrop does not close the modal by default (native `<dialog>` behavior).
- The onClose callback fires when the modal’s close event is triggered.

## Accessibility

- Uses native `<dialog>` semantics<br />([WCAG 4.1.2 — Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value))
- Supports keyboard interaction and Escape key closing<br />([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard))
- Traps focus within the modal while open

### Focus and naming on open

When the modal opens, Modal manages initial focus and the accessible name automatically:

- **Initial focus** is placed on the native `<dialog>` element. The next Tab press moves to the close button, then to the dialog content and actions. This keeps a predictable tab order without skipping the close control.
- **Accessible name** is wired from the dialog title when you use [Dialog](../Dialog/Dialog.md) inside Modal. Dialog exposes its title with a stable `id` and `data-yds-dialog-title`; Modal sets `aria-labelledby` on the `<dialog>` so screen readers announce the title on open.
- **Custom content** (without Dialog): give the visible heading an `id` and `data-yds-dialog-title` so Modal can link it the same way.

**Overrides** (standard `<dialog>` attributes on Modal):

- `aria-label` — use when there is no visible title
- `aria-labelledby` — use when you provide your own title element id

**Focus a specific field on open:** add `data-autofocus` or native `autofocus` to an element inside the modal (for example a text input). That target takes priority over the default dialog focus.

```tsx
import { useId } from 'react';
import { Modal, Dialog, useModal, TextInput } from '@yleisradio/yds-components-react';

// Default: use Dialog — no extra accessibility props required
const { modalRef, openModal } = useModal();
<Modal modalRef={modalRef}>
  <Dialog title="Confirm action">...</Dialog>
</Modal>

// Custom content: mark the heading for auto-naming
const titleId = useId();
<Modal modalRef={modalRef}>
  <h2 id={titleId} data-yds-dialog-title>Custom title</h2>
  ...
</Modal>

// Focus a field instead of the dialog on open
<Modal modalRef={modalRef}>
  <Dialog title="Enter your name">
    <TextInput label="Name" data-autofocus />
  </Dialog>
</Modal>
```

## Implementation Examples

### Email verification Modal with Dialog

*[Live preview](https://design-system.yle.fi/docs/components/Modal/)*

### Nickname Modal with custom content

*[Live preview](https://design-system.yle.fi/docs/components/Modal/)*

## API Reference

### Props

The Modal component accepts all standard HTML `<dialog>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `modalRef` | `React.RefObject<ModalHandle>` | No | — | Ref handle for controlling the modal |
| `onClose` | `() => void` | No | — | Callback fired when modal closes |
| `scrollBehavior` | `'content' \| 'body'` | No | `'content'` | Scroll behavior for modal content |
| `closeOnOutsideClick` | `boolean` | No | `true` | Whether clicking outside the modal content should close the modal |
| `hideCloseButton` | `boolean` | No | `false` | Whether to hide the close button in the modal |
| `closeButtonLabel` | `string` | No | `'Sulje modaali'` | `aria-label` for the close button |
| `children` | `React.ReactNode` | No | — | Content displayed inside the modal |

### Type Definitions

```tsx
export interface ModalDSProps {
  modalRef?: React.RefObject<ModalHandle>;
  onClose?: () => void;
  children?: React.ReactNode;
  scrollBehavior?: 'content' | 'body';
  closeOnOutsideClick?: boolean;
  hideCloseButton?: boolean;
  closeButtonLabel?: string;
}

export type ModalProps = HTMLAttributes<HTMLDialogElement> & ModalDSProps;

export type ModalHandle = {
  open: () => void;
  close: () => void;
};
```

### useModal Hook

The `useModal` hook provides a convenient way to manage modal state.

#### Returns

| Property | Type | Description |
|----------|------|-------------|
| `modalRef` | `React.RefObject<ModalHandle>` | Ref object to pass to the Modal component |
| `openModal` | `() => void` | Function to open the modal |
| `closeModal` | `() => void` | Function to close the modal |

## Related Components

- [Dialog](../Dialog/Dialog.md) – Often used inside Modal for content structure
- [BottomSheet](../BottomSheet/BottomSheet.md) – Alternative component for mobile-friendly modals
- [useModal](../Modal/Modal.md) – Hook for managing modal state

# NavigationTabs

NavigationTabs is a primary navigation pattern that lets users switch between pages or top-level views within a service.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=4570-5045)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-navigationtabs--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/NavigationTab/NavigationTab.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/NavigationTabs/)*

<details open>
<summary>Code example</summary>

```tsx
import { NavigationTab, NavigationTabList } from '@yleisradio/yds-components-react';

<div style={{ height: '48px' }}>
  <NavigationTabList>
    <NavigationTab id="tab-1" selected>Tab 1</NavigationTab>
    <NavigationTab id="tab-2">Tab 2</NavigationTab>
    <NavigationTab id="tab-3">Tab 3</NavigationTab>
  </NavigationTabList>
</div>
```
</details>

> **Warning**
> NavigationTabs stretch to fill 100% of their parent’s height. Set an explicit height on the surrounding element so the tabs have a defined size. Typical heights are 48px on mobile and 72px on desktop.

## Why to use

NavigationTabs provides a familiar, highly discoverable way to move between top-level sections. It makes the current location clear and supports fast switching without requiring deep menus.

## When to use

Use NavigationTabs when selecting a tab takes the user to a different page or view context (primary navigation).

> **Do**
> - Use NavigationTabs when each tab represents a different page or top-level view.
> - Use them as primary or secondary navigation between major sections.
> - Use NavigationTabs when switching tabs changes the overall context or route.
> - Use when users need a persistent and always-visible way to move between destinations.

> **Don't**
> - Don’t use NavigationTabs for filtering or toggling content within the same view.
> - Don’t use them to switch between sections on the same page — use [SectionTabs](../SectionTabs/SectionTabs.md) instead.
> - Don’t use NavigationTabs for small, state-based selections — use [ButtonGroup](../ButtonGroup/ButtonGroup.md) instead.
> - Don’t use them for long or complex option lists — use [DropdownMenuGroup](../DropdownMenuGroup/DropdownMenuGroup.md) or [Select](../Select/Select.md) instead.

### Differences between navigation components

| Component | Use case | Description |
|----------|----------|-------------|
| **NavigationTabs** | Navigation between pages or top-level views | Used when selecting a tab takes the user to a different page or changes the overall view context. Clearly communicates movement to a different “place” in the service. |
| **SectionTabs** | Switching content within the same page | Used to divide content within a single view into logical sections. Changing tabs does not change the route, only the visible content. |
| **ButtonGroup** | Filtering or toggling state | Used for filtering content or toggling between different states within the same context. Options remain visible at all times. |

## Content Guidelines

NavigationTab labels should describe the destination clearly.

> **Do**
> - Use short, destination-based labels (e.g., “Etusivu”, “Veikkaukset”, “Kimpat”).
> - Keep grammar parallel across tabs.
> - Prefer nouns over verbs for destinations.

> **Don't**
> - Don’t use long phrases or sentences as labels.
> - Don’t use ambiguous labels like “Other” without context.
> - Don’t change labels dynamically in ways that make the destination unclear.

## Anatomy

![NavigationTab anatomy](../../img/navigation-tab-anatomy.svg)

1. **Tab list container** – Wraps the row and controls alignment, padding, and scrolling.
2. **Tab** – A single navigation destination.
3. **Label** – The visible tab text.
4. **Selection indicator** – Visual cue for the active tab.
5. **Badge (optional)** – Small indicator that can be used to indicate new or updated content or a required action.

## Key NavigationTab Props

Use these props to configure the NavigationTab component.

### href

URL to navigate to when the tab is clicked.

| Type | Example | Description |
|------|---------|-------------|
| `string` | <NavigationTabList style={{ height: '48px' }}><NavigationTab id="tab-1" selected href="#href">Tab 1</NavigationTab><NavigationTab id="tab-2" href="#href">Tab 2</NavigationTab></NavigationTabList> | Navigates to specified URL |

<details>
<summary>Code example</summary>

```tsx
<NavigationTabList>
  <NavigationTab id="tab-1" selected href="#href">Tab 1</NavigationTab>
  <NavigationTab id="tab-2" selected href="#href">Tab 2</NavigationTab>
</NavigationTabList>
```
</details>

### selected
Whether the tab is currently selected.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <NavigationTabList style={{ height: '48px' }}><NavigationTab id="tab-1" selected>Tab</NavigationTab><NavigationTab id="tab-2" selected={false}>Tab</NavigationTab></NavigationTabList> | Marks tab as selected |

<details>
<summary>Code example</summary>

```tsx
<NavigationTabList>
  <NavigationTab id="tab-1" selected>Selected Tab</NavigationTab>
  <NavigationTab id="tab-2" selected={false}>Unselected Tab</NavigationTab>
</NavigationTabList>
```
</details>

### badge
Whether to show a badge indicator.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <NavigationTabList style={{ height: '48px' }}><NavigationTab id="tab-1" selected badge>Tab</NavigationTab><NavigationTab id="tab-2" >Tab</NavigationTab></NavigationTabList> | Shows badge indicator |

<details>
<summary>Code example</summary>

```tsx
<NavigationTabList>
  <NavigationTab id="tab-1" selected badge>Tab with Badge</NavigationTab>
  <NavigationTab id="tab-2">Tab</NavigationTab>
</NavigationTabList>
```
</details>

### removePadding
Removes padding from the tab.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` |<NavigationTab id="tab-1" selected removePadding style={{ height: '48px' }}>Tab</NavigationTab> | Removes default padding. Works only when NavigationTab is used with NavigationTabList |

<details>
<summary>Code example</summary>

```tsx
  <NavigationTab id="tab-1" removePadding>Tab</NavigationTab>
```
</details>

## Key NavigationTabList Props

Use these props to configure the NavigationTabList component.

### children
NavigationTab components to display.

| Type | Example | Description |
|------|---------|-------------|
| `React.ReactNode` | <NavigationTabList style={{ height: '48px' }}><NavigationTab id="tab-1" selected>Tab</NavigationTab></NavigationTabList> | NavigationTab components |

<details>
<summary>Code example</summary>

```tsx
<NavigationTabList>
  <NavigationTab id="tab-1">Tab 1</NavigationTab>
  <NavigationTab id="tab-2">Tab 2</NavigationTab>
</NavigationTabList>
```
</details>

### align
Horizontal alignment of the tab list.

| Value | Example | Description |
|-------|---------|-------------|
| `start` | <NavigationTabList align="start" style={{ height: '48px' }}><NavigationTab id="tab-1" selected>Tab</NavigationTab></NavigationTabList> | Aligns tabs to the start (default) |
| `center` | <NavigationTabList align="center" style={{ height: '48px' }}><NavigationTab id="tab-1" selected>Tab</NavigationTab></NavigationTabList> | Centers the tabs |

<details>
<summary>Code example</summary>

```tsx
<NavigationTabList align="start">
  <NavigationTab id="tab-1">Tab 1</NavigationTab>
</NavigationTabList>
<NavigationTabList align="center">
  <NavigationTab id="tab-1">Tab 1</NavigationTab>
</NavigationTabList>
```
</details>

### removePadding
Removes padding from all tabs.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <NavigationTabList removePadding style={{ height: '48px' }}><NavigationTab id="tab-1" selected>Tab</NavigationTab></NavigationTabList> | Removes padding from all tabs |

<details>
<summary>Code example</summary>

```tsx
<NavigationTabList removePadding>
  <NavigationTab id="tab-1">Tab 1</NavigationTab>
</NavigationTabList>
```
</details>

## Behavior

- NavigationTabs fill 100% of their parent’s height, so the surrounding element must have an explicit height (typically 48px on mobile and 72px on desktop).
- Selecting a tab changes the current page/view context.
- Tabs are text-width and should not wrap; when there are many, the list should be horizontally scrollable (swipe on touch devices).
- Selected, hover, focus, pressed, and disabled states are visually distinct.
- onTabClick can be used to handle navigation (routing) consistently.

## Accessibility

- Tabs must be reachable and operable with a keyboard.
  (WCAG 2.1.1 — [Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html))

## Implementation Examples

### Tietäjä navigation

*[Live preview](https://design-system.yle.fi/docs/components/NavigationTabs/)*

## API Reference

### NavigationTab Props

The NavigationTab component accepts all standard Button props in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `id` | `string` | Yes | — | Unique identifier for the tab |
| `selected` | `boolean` | No | `false` | Whether the tab is selected |
| `badge` | `boolean` | No | `false` | Shows badge indicator |
| `removePadding` | `boolean` | No | `false` | Removes default padding |
| `onTabClick` | `(id: string) => void` | No | — | Callback fired when tab is clicked |
| `children` | `React.ReactNode` | No | — | Tab content |

### NavigationTabList Props

The NavigationTabList component accepts all standard HTML `<div>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | Yes | — | NavigationTab components |
| `align` | `'start' \| 'center'` | No | `'start'` | Horizontal alignment of tabs |
| `removePadding` | `boolean` | No | `false` | Removes padding from all tabs |
| `onTabClick` | `(id: string) => void` | No | — | Callback fired when any tab is clicked |

### Type Definitions

```tsx
export interface NavigationTabDSProps {
  removePadding?: boolean;
  onTabClick?: (id: string) => void;
  selected?: boolean;
  badge?: boolean;
  children?: React.ReactNode;
}

export type NavigationTabProps<T extends React.ElementType> = ButtonProps<T> & NavigationTabDSProps;

export interface NavigationTabListDSProps {
  align?: 'start' | 'center';
  removePadding?: boolean;
  onTabClick?: (id: string) => void;
  children: React.ReactNode;
}

export type NavigationTabListProps = HTMLAttributes<HTMLDivElement> & NavigationTabListDSProps;
```

## Related Components

- [SectionTabs](../SectionTabs/SectionTabs.md) – Alternative tab component for section-based navigation.
- [Button](../Button/Button.md) – NavigationTab extends Button functionality.
- [ButtonGroup](../ButtonGroup/ButtonGroup.md) – Alternative component for button-based selection.
- [PageIndicator](../PageIndicator/PageIndicator.md) – Alternative component for indicating position in a sequence.
- [Badge](../Badge/Badge.md) – Can be used on tabs to show notification counts.

# Notification

A Notification highlights important information inline with content or across an entire view, communicating success, warning, error, or informational status.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=8113-1253)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-notification--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Notification/Notification.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/Notification/)*

<details open>
<summary>Code example</summary>

```tsx
import { Notification } from '@yleisradio/yds-components-react';

<Notification level="info" variant="primary" title="Notification">
  Notification is used inline with other content.
</Notification>
```
</details>

## Why to use

Notifications call attention to changes of state, validation results, or important contextual information. Messages should be short, specific, and easy to scan. To maintain their impact, display only one notification at a time in the same area. Use levels (info, success, warning, error) and variants (primary, secondary, text) consistently across your product.

## When to use

Notifications are used to clearly communicate important information that requires the user’s attention, understanding, or action. They help users stay informed about system states and the results of their actions.

> **Do**
> - Use a Notification when users need to be informed about an important state, result, or condition.
> - Use it when a user action succeeds, fails, or requires correction.
> - Use it when the system enters a notable state (e.g. warning, error, maintenance).
> - Use it when the message must be noticed and should remain visible until acknowledged or resolved.

> **Don’t**
> - Don’t use Notifications for transient or background feedback.
> - Don’t use Notifications for short-lived confirmations — use a [Toast](../ToastNotification/ToastNotification.md) instead.
> - Don’t show multiple Notifications in the same area at once.
> - Don’t make essential messages dismissible.
> - Don’t use them for trivial or decorative content.

### Differences between Notification Types

| Type | Purpose | Placement | Use case |
|------|---------|-----------|----------|
| **Banner Notification**| A notification covering the entire view or service (e.g., maintenance, error state).| Fixed, below the header. | “Maintenance in progress” |
| **Inline Notification** | A local notification within content or a form (e.g., field error). | Embedded in content. | “This field is required” |
| **Toast Notification** | A short-lived, automatically disappearing feedback message (e.g., save confirmation). | Floating near the bottom of the screen, sliding in and out smoothly. | “Saved successfully” |

## Content Guidelines

Notification content should be easy to scan, clearly communicate what happened, and guide the user toward the next step when needed.

> **Do**
> - Start with the key information; use a title for clarity (e.g., “Huoltokatko”).
> - Keep body text short and focused on the outcome.
> - Provide a clear next step when relevant (e.g., “Päivitä sivu”, “Avaa asetukset”).
> - Use clear, actionable wording and action verbs when actions are available.
> - Use consistent terminology and phrasing across the product.
> - Use concise language and avoid unnecessary qualifiers (e.g., “Tiedosto tallennettu”).
> - Use action buttons only when the user can meaningfully act.
> - Allow users to dismiss non-critical notifications.

> **Don’t**
> - Don’t write long paragraphs or explanatory text.
> - Don’t use vague, duplicated, or filler messages.
> - Don’t combine unrelated topics in a single notification.
> - Don’t use jargon or language that assumes technical knowledge.

## Anatomy

![Notification anatomy](../../img/notification-anatomy.svg)

1. **Icon** – Icon indicating the message level (info, success, warning, error).
2. **Title** – Short heading.
3. **Body** – Main message content.
4. **Close Button** – Optional dismiss control that allows the user to close non-critical or informational notifications.
5. **Primary Button (Actions)** – Main action guiding the user’s next step.
6. **Secondary Button (Actions)** – Optional supporting or alternative action.

## Key Notification Props

Use these props to configure the Notification component to fit your needs.

### level
Sets semantic and visual level (icon + colors).

| Value | Example | Description |
|-------|---------|-------------|
| `info` | <Notification level="info">General information.</Notification> | Neutral informational context. |
| `success` | <Notification level="success">Task completed.</Notification> | Positive confirmation. |
| `warning` | <Notification level="warning">Check details.</Notification> | Caution, requires attention soon. |
| `error` | <Notification level="error">Action failed.</Notification> | Critical or blocking issue. |

<details>
<summary>Code example</summary>

```tsx
<Notification level="info">General information.</Notification>
<Notification level="success">Task completed.</Notification>
<Notification level="warning">Check details.</Notification>
<Notification level="error">Action failed.</Notification>
```
</details>

### variant
Visual style variant. Primary and secondary typically include background; text variant is minimal.

| Value | Example | Description |
|-------|---------|-------------|
| `primary` | <Notification variant="primary">Primary style.</Notification> | Default style with standard emphasis. Used only with `info` level. |
| `secondary` | <Notification variant="secondary">Secondary style.</Notification> | Alternate accent (lighter weight). Used only with `info` level. |
| `text` | <Notification variant="text">Text-only minimal.</Notification> | Transparent background. |

<details>
<summary>Code example</summary>

```tsx
<Notification variant="primary" title="Primary variant">Message</Notification>
<Notification variant="secondary" title="Secondary variant">Message</Notification>
<Notification variant="text" title="Text variant">Message</Notification>
```
</details>

### title
Optional short heading preceding body.

| Type | Example | Description |
|------|---------|-------------|
| `ReactNode` | <Notification title="Upload complete">Files saved.</Notification> | Concise summary of message. |

<details>
<summary>Code example</summary>

```tsx
<Notification title="Upload complete">Files saved.</Notification>
```
</details>

### children (body)
Main descriptive text.

| Type | Example | Description |
|------|---------|-------------|
| `ReactNode` | <Notification title="Saved">Your changes are stored.</Notification> | Explains status or guidance. |

<details>
<summary>Code example</summary>

```tsx
<Notification title="Saved">Your changes are stored.</Notification>
<Notification>Standalone message without title.</Notification>
```
</details>

### hideIcon
Suppresses level icon (text/color still convey status).

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Notification hideIcon>Plain text only.</Notification> | Removes icon for very constrained spaces. |

<details>
<summary>Code example</summary>

```tsx
<Notification hideIcon>Plain text only.</Notification>
```
</details>

### isMultiline

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Notification isMultiline title="Long title that wraps across lines">Detailed guidance that also wraps.</Notification> | Forces title and description to separate lines. |

<details>
<summary>Code example</summary>

```tsx
<Notification
  isMultiline
  title="Long title that wraps across lines"
>
  Detailed guidance that also wraps to multiple lines for clarity.
</Notification>
```
</details>

### onClose (close button)

| Type | Example | Description |
|------|---------|-------------|
| `() => void` | <Notification onClose={() => {}} title="Dismissable">Close me.</Notification> | If provided, displays close button at the right side. Closing the notification needs to be handled in the callback. |

<details>
<summary>Code example</summary>

```tsx
const [show, setShow] = useState(true);
{show && (
  <Notification onClose={() => setShow(false)} title="Dismissable">Close me.</Notification>
)}
```
</details>

### actions
Inline actionable elements related to the message (e.g., Retry, Undo, View details).

| Type | Example | Description |
|------|---------|-------------|
| `ReactNode` | <Notification actions={<Button size="xs" text="Undo" />} title="Item removed">You can undo this action.</Notification> | Buttons placed in actions area. |

<details>
<summary>Code example</summary>

```tsx
<Notification
  title="Item removed"
  actions={<Button size="xs" text="Undo" />}
>
  You can undo this action.
</Notification>
```
</details>

## Behavior

- Notifications provide persistent, contextual feedback and remain visible until the user acknowledges the message or the related condition changes.
- Notifications appear inline with related content or across a full view, depending on context.
- They remain visible until dismissed or until the underlying state is resolved.
- Placement stays close to the content or interaction they relate to.
- Only one Notification should be shown per context to maintain focus and clarity.
- Actions, when present, are clearly labeled and consistently positioned.
- Dismissible Notifications require an explicit user action to close.

## Accessibility

- Inline Notifications inherit meaning from their surrounding context and are placed visually and semantically close to the relevant content, such as directly below a form field or near an interactive element.
- Critical information should remain visible until the issue is resolved or acknowledged by the user.
- If notification appears dynamically, ensure it is announced appropriately to screen readers with `aria-live`-attribute.

## Implementation examples

### With actions
*[Live preview](https://design-system.yle.fi/docs/components/Notification/)*
<details open>
<summary>Code example</summary>

```tsx
<Notification
  level="error"
  title="Saving changes failed"
  actions={(
    <div style={{display: 'flex', gap: 8}}>
      <Button variant="secondary" size="xs" text="Dismiss" />
      <Button size="xs" text="Retry" />
    </div>
  )}
>
  Please check your network connection and try again.
</Notification>
```
</details>

### Multiline content
*[Live preview](https://design-system.yle.fi/docs/components/Notification/)*

<details open>
<summary>Code example</summary>

```tsx
  <Notification
    isMultiline
    level="error"
    title="Upload failed for 3 files"
    actions={<Button size="xs" text="Retry" />}
  >
    Some files exceeded size limits. Reduce file size or choose different files and try again.
  </Notification>
  ```
</details>

### Dismissible (controlled)

*[Live preview](https://design-system.yle.fi/docs/components/Notification/)*

## API Reference

### Props

The Notification component accepts all standard HTML `<div>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | No | — | |
| `title` | `React.ReactNode` | No | — | |
| `level` | `NotificationLevel` | No | `'info'` | |
| `variant` | `NotificationVariant` | No | `'primary'` | |
| `hideIcon` | `boolean` | No | — | |
| `isMultiline` | `boolean` | No | — | |
| `onClose` | `() => void` | No | — | |
| `actions` | `React.ReactNode` | No | — | |

### Type Definitions

```tsx
export type NotificationLevel = 'info' | 'success' | 'warning' | 'error';
export type NotificationVariant = 'primary' | 'secondary' | 'text';

export interface NotificationDSProps {
  children?: React.ReactNode;
  title?: React.ReactNode;
  level?: NotificationLevel;
  variant?: NotificationVariant;
  hideIcon?: boolean;
  isMultiline?: boolean;
  onClose?: () => void;
  actions?: React.ReactNode;
}

export type NotificationProps = Omit<HTMLAttributes<HTMLDivElement>, keyof NotificationDSProps> &
  NotificationDSProps;
```

## Related Components

- [BannerNotification](../BannerNotification/BannerNotification.md) – View- or service-wide announcements (sticky below header).
- [Toast Notification](../ToastNotification/ToastNotification.md) – Short-lived floating feedback.

# PageIndicator

A compound component used to display a row of dot-style navigation buttons that communicate the current position within a set of pages or slides.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=4513-4170)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-pageindicator--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/PageIndicator/PageIndicator.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/PageIndicator/)*

## Why to Use

PageIndicator provides a consistent, accessible way to show a user's position within a paginated or slide-based sequence. The compound structure (`PageIndicatorContainer` + `PageIndicator`) separates grouping concerns from individual indicator state, keeping usage explicit and predictable.

## When to Use

Use PageIndicator when users need to know their position within a finite, ordered set of pages or slides, and may need to navigate between them.

> **Do**
> - Use in carousels and image galleries to show the current slide.
> - Use in multi-step flows or onboarding sequences.
> - Use when the page count is small (up to ~8 items).

> **Don't**
> - Don't use for primary site navigation — use [NavigationTabs](../NavigationTabs/NavigationTabs.md) instead.
> - Don't use for section-level tab switching — use [SectionTabs](../SectionTabs/SectionTabs.md) instead.
> - Don't use when the number of pages exceeds ~8, as the dots become difficult to distinguish.

## Key PageIndicator Props

### isActive

Marks the indicator as the currently active page. Sets the active visual state and adds `aria-current="page"` to the button. Defaults to `false`.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <PageIndicatorContainer><PageIndicator isActive aria-label="Page 1, current" /><PageIndicator aria-label="Page 2" /><PageIndicator aria-label="Page 3" /></PageIndicatorContainer> | Highlights the current page indicator. |

<details>
<summary>Code example</summary>

```tsx
<PageIndicatorContainer>
  <PageIndicator isActive aria-label="Page 1, current" />
  <PageIndicator aria-label="Page 2" />
</PageIndicatorContainer>
```
</details>

## Behavior

- `PageIndicatorContainer` renders a `<div>` with `role="group"` to semantically group the buttons.
- Each `PageIndicator` renders a `<button>` element; all native button attributes (`onClick`, `disabled`, etc.) are forwarded.
- When `isActive` is `true`, the button receives `aria-current="page"` and a distinct active visual style.
- Only one indicator should have `isActive` at a time; state management is the responsibility of the consuming component.

## Accessibility

- Each `PageIndicator` must have an `aria-label` describing its page position and, when active, its current state (e.g. `"Page 1, current"`).<br />([WCAG 1.3.1 — Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships))
- `PageIndicatorContainer` uses `role="group"` to associate the indicators semantically.<br />([WCAG 4.1.2 — Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value))
- The active indicator uses `aria-current="page"` to communicate the current position to assistive technologies.
- Ensure indicators are reachable and operable via keyboard (Tab, Enter/Space).

## Implementation examples

### Controlled carousel indicator

*[Live preview](https://design-system.yle.fi/docs/components/PageIndicator/)*

## API Reference

### PageIndicatorContainer Props

The `PageIndicatorContainer` component accepts all standard HTML `<div>` attributes. It renders a `role="group"` wrapper — provide an `aria-label` to describe the group when needed.

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | No | — | `PageIndicator` buttons to display. |
| `aria-label` | `string` | No | — | Accessible label for the group (recommended). |

### PageIndicator Props

The `PageIndicator` component accepts all standard HTML `<button>` attributes in addition to the following prop:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `isActive` | `boolean` | No | `false` | Marks this indicator as the current page. Adds `aria-current="page"`. |
| `aria-label` | `string` | Yes* | — | Describes the page position. Required for accessibility. |

\* Technically optional at the type level, but required for accessible usage.

### Type Definitions

```tsx
export type PageIndicatorContainerProps = HTMLAttributes<HTMLDivElement>;

export interface PageIndicatorDSProps {
  isActive?: boolean;
}

export type PageIndicatorProps = HTMLAttributes<HTMLButtonElement> & PageIndicatorDSProps;
```

## Related Components

- [NavigationTabs](../NavigationTabs/NavigationTabs.md) – For primary top-level navigation between sections.
- [SectionTabs](../SectionTabs/SectionTabs.md) – For switching between content sections within a page.

# ProgressBar

A visual indicator that displays the completion status of a task or process. Supports both determinate (known progress) and indeterminate (unknown duration) states.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=11984-3804)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-progressbar--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/ProgressBar/ProgressBar.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/ProgressBar/)*

<details open>
<summary>Code example</summary>

```tsx
import { ProgressBar } from '@yleisradio/yds-components-react';

<ProgressBar
  value={50}
  max={100}
  label="Loading"
  description="50% complete"
/>
```
</details>

## Why to use

Use the ProgressBar component to provide visual feedback about the status of ongoing operations such as file uploads, downloads, form submissions, or any process with measurable progress.

## When to use

Use ProgressBar when you need to communicate progress of a task to users, helping them understand how much work has been completed and how much remains.

> **Do**
> - File uploads or downloads where size/progress is known
> - Multi-step processes like form submissions or wizards
> - Data processing, importing, or exporting operations
> - Installation, setup, or configuration workflows
> - Media buffering when duration can be calculated

> **Don't**
> - Don't use for instantaneous actions (under ~300ms) — no indicator needed, or use a brief [Spinner](../Spinner/Spinner.md) for visual consistency
> - Don't use when progress cannot be measured and the operation may complete quickly — use a [Spinner](../Spinner/Spinner.md) instead
> - Don't display fabricated progress values — use the indeterminate variant when actual progress is unknown

## Anatomy

1. **Label** – Optional text above the progress bar describing the operation
2. **Status Icon** – Checkmark (success) or alert triangle (error) shown next to label
3. **Track** – Background container showing the full extent of progress
4. **Indicator** – Filled portion showing current progress
5. **Description** – Optional text below the bar with additional context

## Key ProgressBar Props

Use these props to configure the ProgressBar component.

### variant

Defines whether the progress is measurable or unknown.

| Value           | Example                                                                                          | Description                             |
| --------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------- |
| `determinate`   | <div style={{ width: '200px' }}><ProgressBar variant="determinate" value={60} max={100} /></div> | Shows specific progress percentage      |
| `indeterminate` | <div style={{ width: '200px' }}><ProgressBar variant="indeterminate" /></div>                    | Animated indicator for unknown duration |

<details>
<summary>Code example</summary>

```tsx
  <ProgressBar variant="determinate" value={60} max={100} />
  <ProgressBar variant="indeterminate" />
  ```
</details>

### status

Indicates the current state of the progress operation.

| Value     | Example                                                                                                   | Description                              |
| --------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `active`  | <div style={{ width: '200px' }}><ProgressBar status="active" value={50} max={100} /></div>                | Operation in progress (turquoise)        |
| `success` | <div style={{ width: '200px' }}><ProgressBar status="success" value={100} max={100} label="Done" /></div> | Operation completed successfully (green) |
| `error`   | <div style={{ width: '200px' }}><ProgressBar status="error" value={75} max={100} label="Failed" /></div>  | Operation failed (red)                   |

<details>
<summary>Code example</summary>

```tsx
  <ProgressBar status="active" value={50} max={100} />
  <ProgressBar status="success" value={100} max={100} label="Done" />
  <ProgressBar status="error" value={75} max={100} label="Failed" />
  ```
</details>

### value and max

Controls the progress percentage. Follows HTML `<progress>` element convention.

| Props          | Example                                                                    | Description                             |
| -------------- | -------------------------------------------------------------------------- | --------------------------------------- |
| `value`, `max` | <div style={{ width: '200px' }}><ProgressBar value={30} max={100} /></div> | Current value (30) out of maximum (100) |

<details>
<summary>Code example</summary>

```tsx
  <ProgressBar value={30} max={100} />
  <ProgressBar value={3} max={10} />
  ```
</details>

### label

Provides descriptive text above the progress bar.

| Type     | Example                                                                                               | Description                           |
| -------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `string` | <div style={{ width: '200px' }}><ProgressBar value={50} max={100} label="Uploading files..." /></div> | Text displayed above the progress bar |

<details>
<summary>Code example</summary>

```tsx
  <ProgressBar value={50} max={100} label="Uploading files..." />
  ```
</details>

### description

Provides additional context below the progress bar.

| Type     | Example                                                                                                        | Description                           |
| -------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `string` | <div style={{ width: '200px' }}><ProgressBar value={50} max={100} description="2 of 4 files uploaded" /></div> | Text displayed below the progress bar |

<details>
<summary>Code example</summary>

```tsx
  <ProgressBar value={50} max={100} description="2 of 4 files uploaded" />
  <ProgressBar status="error" value={75} max={100} description="Upload failed" />
  ```
</details>

## Behavior

- Determinate progress smoothly animates as the value changes
- Indeterminate progress continuously animates with a sliding indicator
- Success and error states display corresponding icons next to the label
- Error state changes description text color to red

## Implementation examples

### File upload simulation

This example demonstrates how to use the ProgressBar component to show upload progress with dynamic state updates, transitioning from active to success or error states.

*[Live preview](https://design-system.yle.fi/docs/components/ProgressBar/)*

<details>
<summary>Code example</summary>

```tsx
import { useState, useCallback } from 'react';
import { Button, ProgressBar } from '@yleisradio/yds-components-react';

type UploadState = 'idle' | 'uploading' | 'success' | 'error';

export const ProgressBarUploadSimulation = () => {
  const [progress, setProgress] = useState(0);
  const [uploadState, setUploadState] = useState<UploadState>('idle');

const simulateUpload = useCallback(() => {
setProgress(0);
setUploadState('uploading');

    let currentProgress = 0;
    const interval = setInterval(() => {
      const increment = Math.random() * 15 + 5;
      currentProgress = Math.min(currentProgress + increment, 100);
      setProgress(Math.round(currentProgress));

      if (currentProgress >= 100) {
        clearInterval(interval);
        setUploadState('success');
      }
    }, 300);

}, []);

const getStatus = () => {
if (uploadState === 'success') return 'success';
if (uploadState === 'error') return 'error';
return 'active';
};

const getLabel = () => {
switch (uploadState) {
case 'idle': return 'Ready to upload';
case 'uploading': return 'Uploading file...';
case 'success': return 'Upload complete';
case 'error': return 'Upload failed';
}
};

const getDescription = () => {
switch (uploadState) {
case 'idle': return 'Click the button to start upload';
case 'uploading': return `${progress}% complete`;
case 'success': return 'Your file has been uploaded successfully';
case 'error': return 'Network error occurred. Please try again.';
}
};

return (
<div style={{ maxWidth: '400px' }}>
<ProgressBar
        value={progress}
        max={100}
        status={getStatus()}
        label={getLabel()}
        description={getDescription()}
      />
<div style={{ marginTop: '16px' }}>
{uploadState === 'idle' && (
<Button onClick={simulateUpload}>Start Upload</Button>
)}
{(uploadState === 'success' || uploadState === 'error') && (
<Button onClick={() => { setProgress(0); setUploadState('idle'); }}>
Reset
</Button>
)}
</div>
</div>
);
};

````
</details>

## Accessibility

- Uses `role="progressbar"` for semantic meaning
- Includes `aria-valuenow`, `aria-valuemin`, `aria-valuemax` for screen readers
- Label text is connected via `aria-label`
- Color is not the only indicator of status (icons are included)

## API Reference

### Props

The ProgressBar component accepts all standard HTML `<div>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `number` | No | `0` | Current progress value |
| `max` | `number` | No | `100` | Maximum progress value |
| `variant` | `'determinate' \| 'indeterminate'` | No | `'determinate'` | Progress bar variant |
| `status` | `'active' \| 'success' \| 'error'` | No | `'active'` | Current status of the operation |
| `label` | `string` | No | — | Text label above the progress bar |
| `description` | `string` | No | — | Description text below the progress bar |

### Type Definitions

```tsx
export const progressBarStatuses = ['active', 'success', 'error'] as const;
export const progressBarVariants = ['determinate', 'indeterminate'] as const;

export type ProgressBarStatus = (typeof progressBarStatuses)[number];
export type ProgressBarVariant = (typeof progressBarVariants)[number];

export interface ProgressBarDSProps {
  value?: number;
  max?: number;
  variant?: ProgressBarVariant;
  status?: ProgressBarStatus;
  label?: string;
  description?: string;
}

export type ProgressBarProps = ProgressBarDSProps & HTMLAttributes<HTMLDivElement>;
````

## Related Components

- [Spinner](../Spinner/Spinner.md) – For loading states without progress tracking
- [Notification](../Notification/Notification.md) – For displaying success/error messages after completion
- [Slider](../Slider/Slider.md) – For letting users select a value from a range, rather than displaying read-only progress

# Radio

A Radio Group is a collection of individual Radios that allows users to select one option from a small, clearly defined set.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=285-1932)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-radio--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Radio/Radio.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/Radio/)*
<details open>
<summary>Code example</summary>

```tsx
import { Radio, RadioGroup } from '@yleisradio/yds-components-react';

<RadioGroup
  id="contact-pref"
  name="contact"
  label="Preferred contact method"
  selectedValue="email"
  onChange={() => {}}
>
  <Radio value="email" label="Email" />
  <Radio value="sms" label="SMS" />
  <Radio value="phone" label="Phone" />
</RadioGroup>
```
</details>

## Why to use

Radio Groups provide an accessible and consistent way to make a single, mutually exclusive choice. They keep all options visible for easy comparison and clarify the selection context with a shared label, optional description, and unified validation.

## When to use

Use a RadioGroup when users must choose exactly one option from a small, mutually exclusive set and the options should stay visible for comparison. NumericScale when the choice represents a position on a low–high range (e.g., satisfaction, agreement, ratings).

### Differences between RadioGroup types

| Type | Purpose | Placement | Use case |
|------|---------|-----------|----------|
| **RadioGroup**| One mutually exclusive choice from a short list.| Mostly vertical; horizontal only for short labels. | Form questions, settings, preference selections (e.g., “Sähköposti”, “SMS”, “Puhelu”). |
| **NumericScale** | Choosing a point on a defined numerical range. | Horizontal with clearly labelled endpoints. | Ratings, satisfaction scores, Likert-style scales (e.g., “En pitänyt” – “Pidin erittäin paljon”). |

> **Do**
> - Use when one option must be selected from a small set.
> - Use when all options should be visible to support quick comparison.
> - Use RadioGroupNumericScale for Likert-style or rating questions.

> **Don’t**
> - Don’t use for multiple selections — use [Checkboxes](../Checkbox/Checkbox.md).
> - Don’t use for an instant on/off UI state — use [Switch](../Switch/Switch.md).
> - Don’t use when the list is long or needs searching — use [Select](../Select/Select.md) or [ComboboxSingleSelect](../ComboboxSingleSelect/ComboboxSingleSelect.md).
> - Don’t use when “no selection” is allowed but a single toggle would communicate better — consider [Checkbox](../Checkbox/Checkbox.md) (single option) or [Switch](../Switch/Switch.md) depending on intent.

## Content Guidelines

Radio labels should be short, comparable, and unambiguous so users can scan and understand differences between options quickly.

> **Do**
> - Write a concise group label that reads like a question or heading.(e.g., “Mieluisin yhteydenottotapa”)
>  - Keep option labels short and parallel in structure.(e.g., “Sähköposti”, “SMS”, “Puhelu”)
>  - Use the group description for brief clarification when needed.
>  - For NumericScale, label both ends of the range clearly.(e.g., “En pitänyt” – “Pidin erittäin paljon”)

> **Don’t**
> - Don’t use long sentences as option labels—move explanations to the description.
>  - Don’t create overlapping or unclear choices.
>  - Don’t repeat label wording in each option.
>  - Don’t mix different answer types in one group.

## Anatomy

![Radio anatomy](../../img/radio-group-anatomy.svg)

1. **Group label** – Defines the purpose of the group.
2. **Description** – Optional helper text below the label.
3. **Radio control** – Circular selector; only one can be active.
4. **Option label** – Text linked to each radio choice.

## Key Radio Props

Use the following props to customize the Radio component to fit your needs.

### variant

| Value | Example                                                | Description |
|------|--------------------------------------------------------|------------------|
| `primary` | <Radio value="email" label="Email" checked /> | Default style for most use cases. |
| `secondary` | <Radio variant="secondary" value="email" label="Email" checked /> | Uses highlight color for the control. |

<details>
<summary>Code example</summary>

```tsx
  <Radio variant="primary" value="email" label="Email" checked />
  <Radio variant="secondary" value="email" label="Email" checked />
  ```
</details>

### isDisabled
Non-interactive, dimmed styling.

| Type | Example                                                | Description |
|------|--------------------------------------------------------|-------------|
| `boolean` | <Radio value="email" label="Email" isDisabled checked /> | Temporarily prevents user interaction. |

<details>
<summary>Code example</summary>

```tsx
  <Radio value="email" label="Email" isDisabled checked />
  ```
</details>

### hideLabel

| Type | Example                                                | Description |
|------|--------------------------------------------------------|-------------|
| `boolean` | <Radio value="email" label="Email" hideLabel /> | Visually hides label but keeps it accessible. |

<details>
<summary>Code example</summary>

```tsx
  <Radio value="email" label="Email" hideLabel />
  ```
</details>

### controlAlign

| Value | Example                                                | Description |
|------|--------------------------------------------------------|-------------|
| `start` | <Radio value="email" label="Email" controlAlign="start" /> | Positions the control before the label text. |
| `end` | <Radio value="email" label="Email" controlAlign="end" /> | Positions the control after the label text. |

<details>
<summary>Code example</summary>

```tsx
  <Radio value="email" label="Email" controlAlign="start" />
  <Radio value="email" label="Email" controlAlign="end" />
  ```
</details>

## Key RadioGroup Props

Use the following props to customize the RadioGroup component to fit your needs.

### label

| Type | Example                                                | Description |
|------|--------------------------------------------------------|-------------|
| `string` | <RadioGroup id="contact" name="contact" label="Contact method" onChange={() => {}}><Radio label="Email" value="email" /><Radio label="Phone" value="phone" /></RadioGroup> | Text label describing the purpose of the group. |

<details>
<summary>Code example</summary>

```tsx
  <RadioGroup
    id="contact"
    name="contact"
    label="Contact method"
    onChange={() => {}}
  >
    <Radio label="Email" value="email" />
    <Radio label="Phone" value="phone" />
  </RadioGroup>
  ```
</details>

### description
Helper guidance placed below the group label.

| Type | Example                                                | Description |
|------|--------------------------------------------------------|-------------|
| `string` | <RadioGroup id="contact" name="contact" label="Contact method" description="How should we reach you?" onChange={() => {}}><Radio label="Email" value="email" /><Radio label="Phone" value="phone" /></RadioGroup> | Provides additional context or instructions for the group. |

<details>
<summary>Code example</summary>

```tsx
  <RadioGroup
    id="contact"
    name="contact"
    label="Contact method"
    description="How should we reach you?"
    onChange={() => {}}
  >
    <Radio label="Email" value="email" />
    <Radio label="Phone" value="phone" />
  </RadioGroup>
  ```
</details>

### errorMessage

| Type | Example                                                | Description |
|------|--------------------------------------------------------|-------------|
| `string` | <RadioGroup id="contact" name="contact" label="Contact method" errorMessage="Please select a contact method" onChange={() => {}}><Radio label="Email" value="email" /><Radio label="Phone" value="phone" /></RadioGroup> | Shows an error message and applies error styles to the group. |

<details>
<summary>Code example</summary>

```tsx
  <RadioGroup
    id="contact"
    name="contact"
    label="Contact method"
    errorMessage="Please select a contact method"
    onChange={() => {}}
  >
    <Radio label="Email" value="email" />
    <Radio label="Phone" value="phone" />
  </RadioGroup>
  ```
</details>

### direction

Layout orientation of the radio options.

| Value | Example                                                | Description |
|------|--------------------------------------------------------|-------------|
| `vertical` | <RadioGroup id="contact" name="contact" label="Contact method" direction="vertical" onChange={() => {}}><Radio label="Email" value="email" /><Radio label="Phone" value="phone" /></RadioGroup> | Stacks radios vertically (default). |
| `horizontal` | <RadioGroup id="contact" name="contact" label="Contact method" direction="horizontal" onChange={() => {}}><Radio label="Email" value="email" /><Radio label="Phone" value="phone" /></RadioGroup> | Arranges radios horizontally. |

<details>
<summary>Code example</summary>

```tsx
  <RadioGroup
    id="contact"
    name="contact"
    label="Contact method"
    direction="vertical"
    onChange={() => {}}
  >
    <Radio label="Email" value="email" />
    <Radio label="Phone" value="phone" />
  </RadioGroup>

  <RadioGroup
    id="contact"
    name="contact"
    label="Contact method"
    direction="horizontal"
    onChange={() => {}}
  >
    <Radio label="Email" value="email" />
    <Radio label="Phone" value="phone" />
  </RadioGroup>
  ```
</details>

## RadioGroupNumericScale (Likert / Rating)
Extends `RadioGroup` with optional semantic boundary labels.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `startLabel` | `string` | — | Text describing the low end of the scale (e.g. "Not at all"). |
| `endLabel` | `string` | — | Text describing the high end (e.g. "Very satisfied"). |

<details>
<summary>Code example</summary>

```tsx
<RadioGroupNumericScale
  id="satisfaction"
  name="satisfaction"
  label="Satisfaction"
  startLabel="Low"
  endLabel="High"
  direction="horizontal"
  selectedValue="3"
  onChange={() => {}}
>
  <Radio value="1" label="1" />
  <Radio value="2" label="2" />
  <Radio value="3" label="3" />
  <Radio value="4" label="4" />
  <Radio value="5" label="5" />
</RadioGroupNumericScale>
```
</details>

## Behavior

- Only one option can be selected at a time; choosing a new one deselects the previous.
- Radios in the same group share the same name attribute to ensure correct selection and navigation.
- The group label defines the question or context for all options.
- Use vertical layout for readability and horizontal for compact or scale-type choices.
- Disabled Radios remain visible but non-interactive.
- Supports both controlled (selectedValue, onChange) and uncontrolled (defaultChecked) usage.
- Error messages appear below the group and guide users to correct input.

## Accessibility

- Each Radio must have a visible or programmatically associated label.<br />([WCAG 3.3.2 — Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions))
- Group related Radios under a shared group label describing the selection’s purpose.<br />([WCAG 1.3.1 — Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships))
- Keyboard navigation: users move between Radios with arrow keys and select with Space or Enter.<br />([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard))
- Numeric Scale groups should include clear start and end labels to define the range meaning.<br />([WCAG 1.3.1 — Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships))

## Implementation examples

### With description

*[Live preview](https://design-system.yle.fi/docs/components/Radio/)*
<details open>
<summary>Code example</summary>

```tsx
<RadioGroup
  id="newsletter"
  name="newsletter"
  label="Preferred learning method"
  description=" Choose the learning method that best supports your studying."
  selectedValue="weekly"
  onChange={() => {}}
>
  <Radio value="online" label="Online self-paced courses" />
  <Radio value="classroom" label="Instructor-led classroom training" />
  <Radio value="hybrid" label="Hybrid sessions" />
  <Radio value="group" label="Group discussions" />
  <Radio value="independent" label="Independent study" />
</RadioGroup>
```
</details>

### With error message

*[Live preview](https://design-system.yle.fi/docs/components/Radio/)*

<details open>
<summary>Code example</summary>

```tsx
<RadioGroup
  id="newsletter"
  name="newsletter"
  label="Preferred learning method"
  description=" Choose the learning method that best supports your studying."
  errorMessage="Please select a preference"
  onChange={() => {}}
>
  <Radio value="online" label="Online self-paced courses" />
  <Radio value="classroom" label="Instructor-led classroom training" />
  <Radio value="hybrid" label="Hybrid sessions" />
  <Radio value="group" label="Group discussions" />
  <Radio value="independent" label="Independent study" />
</RadioGroup>
```
</details>

### Numeric scale rating

*[Live preview](https://design-system.yle.fi/docs/components/Radio/)*

<details open>
<summary>Code example</summary>

```tsx
<RadioGroupNumericScale
  id="article"
  name="article"
  label="Did you like this article?"
  startLabel="Did not like"
  endLabel="Liked a lot"
  direction="horizontal"
  selectedValue="3"
  onChange={() => {}}
>
  <Radio value="1" label="1" />
  <Radio value="2" label="2" />
  <Radio value="3" label="3" />
  <Radio value="4" label="4" />
  <Radio value="5" label="5" />
</RadioGroupNumericScale>
```
</details>

[See more examples in Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-radio--docs)

## API Reference

### Props

#### Radio

The Radio component accepts all standard HTML `<input>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `VariantType` | No | `'primary'` | |
| `isDisabled` | `boolean` | No | `false` | |
| `error` | `boolean` | No | — | |
| `label` | `ReactNode` | Yes | — | |
| `name` | `string` | No | — | |
| `hideLabel` | `boolean` | No | `false` | |
| `useUnderlay` | `boolean` | No | `false` | |
| `onChange` | `(event: ChangeEvent<HTMLInputElement>) => void` | No | — | |
| `controlAlign` | `InputControlAlign` | No | `'start'` | |

#### RadioGroup

The RadioGroup component accepts the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `id` | `string` | Yes | — | |
| `name` | `string` | Yes | — | |
| `selectedValue` | `string` | No | — | |
| `errorMessage` | `string` | No | — | |
| `label` | `string` | No | — | |
| `labelOptions` | `FormGroupLabelProps` | No | — | |
| `description` | `string` | No | — | |
| `children` | `ReactNode` | Yes | — | |
| `direction` | `RadioGroupDirection` | No | `'vertical'` | |
| `onChange` | `(event: ChangeEvent<HTMLInputElement>) => void` | Yes | — | |

#### RadioGroupNumericScale

The RadioGroupNumericScale component extends RadioGroup and accepts the following additional props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `startLabel` | `string` | No | — | |
| `endLabel` | `string` | No | — | |

### Type Definitions

#### Radio

```tsx
export type VariantType = 'primary' | 'secondary';
export type InputControlAlign = 'start' | 'end';
export type RadioGroupDirection = 'vertical' | 'horizontal';

export interface RadioDSProps {
  variant?: VariantType;
  isDisabled?: boolean;
  error?: boolean;
  label: ReactNode;
  name?: string;
  hideLabel?: boolean;
  useUnderlay?: boolean;
  onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
  controlAlign?: InputControlAlign;
}

export type RadioProps = InputHTMLAttributes<HTMLInputElement> & RadioDSProps;
```

#### RadioGroup

```tsx
export interface RadioGroupProps {
  id: string;
  name: string;
  selectedValue?: string;
  errorMessage?: string;
  label?: string;
  labelOptions?: FormGroupLabelProps;
  description?: string;
  children: ReactNode;
  direction?: RadioGroupDirection;
  onChange: (event: ChangeEvent<HTMLInputElement>) => void;
}
```
#### RadioGroupNumericScale

```tsx
export interface RadioGroupNumericScaleProps extends RadioGroupProps {
  startLabel?: string;
  endLabel?: string;
}
```

## Related Components

- [Checkbox](../Checkbox/Checkbox.md) – For multiple independent selections.
- [Switch](../Switch/Switch.md) – Immediate binary toggles.
- [ChoiceBox](../ChoiceBox/ChoiceBox.md) – Alternative visual single-choice pattern.
- [Select](../Select/Select.md) – Alternative for single selection from a dropdown list.
- [ButtonGroup](../ButtonGroup/ButtonGroup.md) – Alternative single-selection pattern using buttons.

# SearchInput

A Search Input allows users to find the content they need from a service by entering keywords, supporting those who may not be able to locate the desired content through navigation alone.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=3777-1839&p=f&t=U4uSG0M5o85iz0VX-0)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-searchinput--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/SearchInput/SearchInput.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/SearchInput/)*
<details open>
<summary>Code example</summary>

```tsx
import { SearchInput, SearchSubmitButton, createClearIcon } from '@yleisradio/yds-components-react';

<SearchInput
  id="search-basic"
  label="Search"
  placeholder="Search articles"
  name="q"
  submitButton={<SearchSubmitButton aria-label="Search" />}
  iconClear={createClearIcon({ ariaLabel: 'Clear search' })}
/>
```
</details>

## Why to use

The Search Input helps users quickly locate specific content when navigation alone is not sufficient. It enhances usability and supports accessibility by allowing users to find information using familiar search interaction patterns. It provides users with a direct way to find content on a page, application, or service, offers an alternative to browsing for those who may not know where to look, and improves efficiency for returning users who already know what they want to find.

## When to use

Use SearchInput when users need to search a content set by typing keywords and triggering a dedicated search action.

> **Do**
> - Use SearchInput for services with large content sets where users may not find content by browsing.
> - Use it for global search (e.g., header search) or scoped search within a page or section.
> - Use it when the search is triggered by submitting (button or Enter), not instant filtering.
> - Use it when users are likely to know what they want to search for (keywords, titles, names).

> **Don’t**
> - Don’t use SearchInput for choosing from predefined options — use [Select](../Select/Select.md) or [ComboboxSingleSelect](../ComboboxSingleSelect/ComboboxSingleSelect.md).
> - Don’t use it for instant filtering of small lists — use a filter field / [TextInput](../TextInput/TextInput.md) pattern instead.
> - Don’t place SearchInput where search is not relevant or expected.
> - Don’t use it without an accessible label (visible or visually hidden).

## Content Guidelines

SearchInput text should help users understand what they can search and how. Keep labels and placeholders short, familiar, and specific to the search scope.

> **Do**
> - Use a clear label that describes the search scope (e.g., “Hae”, “Hae artikkeleita”, “Hae ohjelmia”).
> - Use placeholder text as an example (e.g., “Kirjoita hakusana”, “Hae artikkeleita”).
> - If the scope is not obvious, add helper text nearby (e.g., “Hakee vain ohjelmista”).
> - Use explicit accessible labels for icon buttons (e.g., submit and clear).

> **Don’t**
> - Don’t rely on placeholder text alone to explain purpose.
> - Don’t duplicate the label in the placeholder.
> - Don’t use long instructional placeholders or rules — put constraints in helper text instead.
> - Don’t use jargon or unclear labels that don’t indicate what is being searched.

## Anatomy

![SearchInput anatomy](../../img/search-input-anatomy.svg)

1. **Search text** – Example text inside the field.
2. **Search field (input)** – Area where the user types the query.
3. **Clear button** – Appears when text is present; clears the field.
4. **Search button** – Always visible; triggers the search action.

## Key Props

Use the following props to customize the SearchInput component to fit your needs.

SearchInput extends TextInput, so it also supports all [TextInput props](../TextInput/TextInput.md#key-props).

### submitButton

Provides an explicit search action. Use the supplied `<SearchSubmitButton />` or a custom button.

| Type        | Example                                                                                                                                   | Description                                        |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `ReactNode` | <SearchInput id="submit-button" label="Search" placeholder="Search articles" submitButton={<SearchSubmitButton aria-label="Search" />} /> | Renders actionable search trigger at end of field. |

<details>
<summary>Code example</summary>

```tsx
  <SearchInput
    id="submit-button"
    label="Search"
    placeholder="Search articles"
    submitButton={<SearchSubmitButton aria-label="Search" />}
  />
  ```
</details>

### iconClear

Shows a clickable icon to clear the current value. Prefer [`createClearIcon`](../TextInput/TextInput.md#createclearicon) with a `value` for visibility and focus behaviour.

| Type             | Example                                                                                                                                                                                                                          | Description       |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `InputIconProps` | <SearchInput id="submit-button" label="Search" defaultValue="Search articles" submitButton={<SearchSubmitButton aria-label="Search" />} iconClear={createClearIcon({ ariaLabel: 'Clear search' })} /> | Clears the input. |

<details>
<summary>Code example</summary>

```tsx
  <SearchInput
    id="s-clear"
    label="Search"
    value="term"
    submitButton={<SearchSubmitButton aria-label="Search" />}
    iconClear={createClearIcon({ ariaLabel: 'Clear search' })}
  />
  ```
</details>

## SearchSubmitButton component

Helper button that displays a search icon or spinner.

| Prop         | Type      | Default | Description                                      |
| ------------ | --------- | ------- | ------------------------------------------------ |
| `isDisabled` | `boolean` | `false` | Non-interactive state; sets `aria-disabled`.     |
| `loading`    | `boolean` | `false` | Shows spinner instead of icon; adds `aria-busy`. |

<details>
<summary>Code example</summary>

```tsx
  <SearchSubmitButton aria-label="Search" />
  <SearchSubmitButton loading aria-label="Searching" />
  <SearchSubmitButton isDisabled aria-label="Search" />
  ```
</details>

## Behavior

- The search is triggered by pressing Enter or activating the submit button.
- The submit button is always available as the explicit action.
- The clear button (if provided) clears the current value and should be available when text exists.
- The component can show a loading state (e.g., while fetching results).
- Disabled state prevents interaction but keeps the field visible.
- All interactive elements (input, submit, clear) must be keyboard operable.

## Accessibility

- Always provide a label — it may be hidden visually, but it must remain accessible. This ensures users of assistive technologies know what the field is for. <br />([WCAG 3.3.2 — Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions)).
- Submit and clear controls must have descriptive accessible names (e.g., “Search”, “Clear search”). <br />([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard)).
- Keyboard support: Tab/Shift+Tab moves focus; Enter submits; buttons are operable with keyboard.
- Pressing Enter or clicking the search button performs the search. The user is taken to a search results page or results are displayed dynamically on the same page. <br /> ([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard)).
- The magnifying glass icon is a widely recognized symbol and doesn’t need to include the word “search” visually. However, it must have an accessible label for screen readers. <br /> ([WCAG 3.3.2 — Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions)).

## Implementation examples

### Basic search inside a form

*[Live preview](https://design-system.yle.fi/docs/components/SearchInput/)*
<details open>
<summary>Code example</summary>

```tsx
  <form action="https://haku.yle.fi" method="get" role="search">
    <SearchInput
      id="ex-form"
      name="q"
      label="Search site"
      placeholder="Search site"
      submitButton={<SearchSubmitButton aria-label="Search" />}
    />
  </form>
  ```
</details>

### Without form (manual handler)

*[Live preview](https://design-system.yle.fi/docs/components/SearchInput/)*
<details open>
<summary>Code example</summary>

```tsx
  <SearchInput
    id="ex-nf"
    label="Search"
    placeholder="Type term"
    submitButton={
      <SearchSubmitButton
        aria-label="Search"
        type="button"
        onClick={() => alert('Search triggered')}
      />
    }
    onKeyDown={(e) => {
      if (e.key === 'Enter') alert('Search triggered');
    }}
  />
  ```
</details>

### With clear button

*[Live preview](https://design-system.yle.fi/docs/components/SearchInput/)*
<details open>
<summary>Code example</summary>

```tsx
  <SearchInput
    id="ex-clear"
    label="Search"
    value="Initial term"
    placeholder="Search"
    submitButton={<SearchSubmitButton aria-label="Search" />}
    iconClear={createClearIcon({
      ariaLabel: 'Clear search',
      value: query,
      onClear: () => setQuery(''),
    })}
    onChange={(e) => setQuery(e.currentTarget.value)}
  />
  ```
</details>

### Loading state

*[Live preview](https://design-system.yle.fi/docs/components/SearchInput/)*
<details open>
<summary>Code example</summary>

```tsx
  <SearchInput
    id="ex-loading"
    label="Search"
    value="query"
    submitButton={<SearchSubmitButton aria-label="Searching" loading />}
  />
  ```
</details>

### Disabled

*[Live preview](https://design-system.yle.fi/docs/components/SearchInput/)*
<details open>
<summary>Code example</summary>

```tsx
  <SearchInput
    id="ex-disabled"
    label="Search"
    placeholder="Search disabled"
    isDisabled
    submitButton={<SearchSubmitButton aria-label="Search" isDisabled />}
  />
  ```
</details>

## API Reference

### Props

#### SearchInput

The SearchInput component accepts all standard HTML `<input>` attributes in addition to the following props. SearchInput extends TextInput, so it supports all TextInput props except `icon`:

| Prop           | Type        | Required | Default | Description |
| -------------- | ----------- | -------- | ------- | ----------- |
| `submitButton` | `ReactNode` | No       | —       |             |

#### SearchSubmitButton

The SearchSubmitButton component accepts all standard HTML `<button>` attributes in addition to the following props:

| Prop         | Type      | Required | Default | Description |
| ------------ | --------- | -------- | ------- | ----------- |
| `isDisabled` | `boolean` | No       | `false` |             |
| `loading`    | `boolean` | No       | `false` |             |

### Type Definitions

#### SearchInput

```tsx
export type SearchInputDSProps = Omit<TextInputDSProps, 'icon'>;

export type SearchSubmitButtonDSProps = {
  isDisabled?: boolean;
  loading?: boolean;
};
```

#### SearchSubmitButton

```tsx
export type SearchInputProps = InputHTMLAttributes<HTMLInputElement> & SearchInputDSProps;

export type SearchSubmitButtonProps = ButtonHTMLAttributes<HTMLButtonElement> &
  SearchSubmitButtonDSProps;
```

## Related Components

- [TextInput](../TextInput/TextInput.md): For single-line responses.
- [TextArea](../TextArea/TextArea.md): For multi-line responses.
- [Select](../Select/Select.md): For single-select dropdowns.
- [ComboboxSingleSelect](../ComboboxSingleSelect/ComboboxSingleSelect.md): For searchable single-select dropdowns.

# SectionTabs

SectionTabs is a navigation pattern for switching between content sections within the same page or view, without changing the overall page context.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=4630-183)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-sectiontabs--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/SectionTabs/SectionTabs.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/SectionTabs/)*

<details open>
<summary>Code example</summary>

```tsx
import { SectionTabs, SectionTabList, SectionTab, SectionTabPanel } from '@yleisradio/yds-components-react';

<SectionTabs>
  <SectionTabList>
    <SectionTab index={0}>Tab 1</SectionTab>
    <SectionTab index={1}>Tab 2</SectionTab>
    <SectionTab index={2}>Tab 3</SectionTab>
  </SectionTabList>
  <SectionTabPanel index={0}>Content for Tab 1</SectionTabPanel>
  <SectionTabPanel index={1}>Content for Tab 2</SectionTabPanel>
  <SectionTabPanel index={2}>Content for Tab 3</SectionTabPanel>
</SectionTabs>
```
</details>

## Why to use

SectionTabs helps organize large amounts of related content into clearly separated sections within the same view. It allows users to focus on one section at a time without navigating away or reloading the page, improving clarity and usability in content-dense layouts.

## When to use

Use SectionTabs when users need to switch between different content sections within the same page or view, while staying in the same context.

> **Do**
> - Use SectionTabs to divide complex or content-heavy views into logical sections.
> - Use when switching tabs updates only part of the page, not the route or page context.
> - Use when users need to compare or explore related content areas without leaving the view.
> - Use when all tabs belong to the same conceptual level.

> **Don't**
> - Don’t use SectionTabs for page-level navigation — use [NavigationTabs](../NavigationTabs/NavigationTabs.md) instead.
> - Don’t use SectionTabs for filtering or state toggling — use [ButtonGroup](../ButtonGroup/ButtonGroup.md) instead.
> - Don’t use SectionTabs when options must stay visible at all times — use [ButtonGroup](../ButtonGroup/ButtonGroup.md).
> - Don’t use too many tabs; consider other patterns if the list becomes long.

### Differences between navigation components

| Component | Use case | Description |
|----------|----------|-------------|
| **NavigationTabs** | Navigation between pages or top-level views | Used when selecting a tab takes the user to a different page or changes the overall view context. Clearly communicates movement to a different “place” in the service. |
| **SectionTabs** | Switching content within the same page | Used to divide content within a single view into logical sections. Changing tabs does not change the route, only the visible content. |
| **ButtonGroup** | Filtering or toggling state | Used for filtering content or toggling between different states within the same context. Options remain visible at all times. |

## Content Guidelines

SectionTab labels should clearly describe the content shown in the panel.

> **Do**
> - Use short, descriptive labels (e.g., “Omat”, “Tulokset”).
> - Keep labels parallel and at the same level of abstraction.
> - Prefer nouns that describe content, not actions.
> - The content of tab panels should be balanced in length and complexity.

> **Don't**
> - Don’t use long sentences or explanations as tab labels.
> - Don’t mix unrelated content under the same tab set.
> - Don’t use vague labels like “Muut” or “Sekalaista”.

## Anatomy

![SectionTabs anatomy](../../img/section-tab-anatomy.svg)

1. **Tab list container** – Wraps the row and controls alignment, padding, and scrolling.
2. **Tab** – A single navigation destination.
3. **Selection indicator** – Visual cue for the active tab.
4. **Label** – The visible tab text.

## Key SectionTabs Props

Use these props to configure the SectionTabs component.

### defaultTab
Initial active tab index for uncontrolled component.

| Type | Example | Description |
|------|---------|-------------|
| `number` | <SectionTabs defaultTab={1}><SectionTabList><SectionTab index={0}>Tab 1</SectionTab><SectionTab index={1}>Tab 2</SectionTab><SectionTab index={2}>Tab 3</SectionTab></SectionTabList></SectionTabs> | Initial active tab index |

<details>
<summary>Code example</summary>

```tsx
<SectionTabs defaultTab={1}>
  <SectionTabList>
    <SectionTab index={0}>Tab 1</SectionTab>
    <SectionTab index={1}>Tab 2</SectionTab>
    <SectionTab index={2}>Tab 3</SectionTab>
  </SectionTabList>
  <SectionTabPanel index={0}>Content for Tab 1</SectionTabPanel>
  <SectionTabPanel index={1}>Content for Tab 2</SectionTabPanel>
  <SectionTabPanel index={2}>Content for Tab 3</SectionTabPanel>
</SectionTabs>
```
</details>

### tab
Current active tab index for controlled component.

| Type | Example | Description |
|------|---------|-------------|
| `number` | <SectionTabs tab={0}><SectionTabList><SectionTab index={0}>Tab 1</SectionTab><SectionTab index={1}>Tab 2</SectionTab><SectionTab index={2}>Tab 3</SectionTab></SectionTabList></SectionTabs> | Controlled active tab index |

<details>
<summary>Code example</summary>

```tsx
const [activeTab, setActiveTab] = useState(0);

<SectionTabs tab={activeTab} onTabChange={(e) => setActiveTab(e.currentTab)}>
  <SectionTabList>
    <SectionTab index={0}>Tab 1</SectionTab>
    <SectionTab index={1}>Tab 2</SectionTab>
    <SectionTab index={2}>Tab 3</SectionTab>
  </SectionTabList>
  <SectionTabPanel index={0}>Content for Tab 1</SectionTabPanel>
  <SectionTabPanel index={1}>Content for Tab 2</SectionTabPanel>
  <SectionTabPanel index={2}>Content for Tab 3</SectionTabPanel>
</SectionTabs>
```
</details>

### onTabChange
Callback fired when the active tab changes.

| Type | Example | Description |
|------|---------|-------------|
| `(event: TabChangeEvent) => void` | <SectionTabs onTabChange={(e) => {console.log('Previous tab:', e.previousTab); console.log('Current tab:', e.currentTab);}}><SectionTabList><SectionTab index={0}>Tab 1</SectionTab><SectionTab index={1}>Tab 2</SectionTab><SectionTab index={2}>Tab 3</SectionTab></SectionTabList></SectionTabs> | Callback with tab change event |

<details>
<summary>Code example</summary>

```tsx
<SectionTabs
  onTabChange={(event) => {
    console.log('Previous tab:', event.previousTab);
    console.log('Current tab:', event.currentTab);
  }}
>
  <SectionTabList>
    <SectionTab index={0}>Tab 1</SectionTab>
    <SectionTab index={1}>Tab 2</SectionTab>
    <SectionTab index={2}>Tab 3</SectionTab>
  </SectionTabList>
  <SectionTabPanel index={0}>Content for Tab 1</SectionTabPanel>
  <SectionTabPanel index={1}>Content for Tab 2</SectionTabPanel>
  <SectionTabPanel index={2}>Content for Tab 3</SectionTabPanel>
</SectionTabs>
```
</details>

## Key SectionTabList Props

Use these props to configure the SectionTabList component.

### enableTransitions
Controls whether transitions should be enabled.

| Type | Example | Description |
|------|---------|-------------|
| `boolean \| undefined` | <SectionTabs><SectionTabList enableTransitions={false}><SectionTab index={0}>Tab 1</SectionTab><SectionTab index={1}>Tab 2</SectionTab><SectionTab index={2}>Tab 3</SectionTab></SectionTabList><SectionTabPanel index={0}>Content for Tab 1</SectionTabPanel><SectionTabPanel index={1}>Content for Tab 2</SectionTabPanel><SectionTabPanel index={2}>Content for Tab 3</SectionTabPanel></SectionTabs> | Controls transition behavior |

<details>
<summary>Code example</summary>

```tsx
<SectionTabs>
  <SectionTabList enableTransitions={false}>
    <SectionTab index={0}>Tab 1</SectionTab>
    <SectionTab index={1}>Tab 2</SectionTab>
    <SectionTab index={2}>Tab 3</SectionTab>
  </SectionTabList>
  <SectionTabPanel index={0}>Content for Tab 1</SectionTabPanel>
  <SectionTabPanel index={1}>Content for Tab 2</SectionTabPanel>
  <SectionTabPanel index={2}>Content for Tab 3</SectionTabPanel>
</SectionTabs>
```
</details>

## Key SectionTab Props

Use these props to configure the SectionTab component.

### disabled
Whether the tab is disabled.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <SectionTab index={0} disabled>Tab</SectionTab> | Disables the tab |

<details>
<summary>Code example</summary>

```tsx
<SectionTab index={0} disabled>Disabled Tab</SectionTab>
```
</details>

### isActiveUncontrolled
Whether the tab should appear active regardless of parent state.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <SectionTab index={0} isActiveUncontrolled>Tab</SectionTab> | Forces active appearance |

<details>
<summary>Code example</summary>

```tsx
<SectionTab index={0} isActiveUncontrolled>Tab</SectionTab>
```
</details>

## Key SectionTabPanel Props

Use these props to configure the SectionTabPanel component.

### index
Index of the panel (0-based). Must match the corresponding tab index.

| Type | Example | Description |
|------|---------|-------------|
| `number` | <SectionTabs><SectionTabList><SectionTab index={0}>Tab 1</SectionTab><SectionTab index={1}>Tab 2</SectionTab><SectionTab index={2}>Tab 3</SectionTab></SectionTabList><SectionTabPanel index={0}>Content for Tab 1</SectionTabPanel><SectionTabPanel index={1}>Content for Tab 2</SectionTabPanel><SectionTabPanel index={2}>Content for Tab 3</SectionTabPanel></SectionTabs> | Panel index for identification |

<details>
<summary>Code example</summary>

```tsx
<SectionTabPanel index={0}>Content for Tab 1</SectionTabPanel>
<SectionTabPanel index={1}>Content for Tab 2</SectionTabPanel>
```
</details>

## Behavior

- Only one tab panel is visible at a time.
- Selecting a tab updates the visible panel without changing the page context.
- Tabs are always rendered in a single horizontal row.
- Disabled tabs cannot be activated.
- Transitions can be enabled or disabled via SectionTabList.
- Height of the tab panel should not generally exceed the viewport height.
- Nested SectionTabs should be avoided.

## Accessibility

- Tabs must be reachable and operable with a keyboard.
  (WCAG 2.1.1 — [Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html))

## API Reference

### SectionTabs Props

The SectionTabs component accepts all standard HTML `<div>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | Yes | — | SectionTabList and SectionTabPanel components |
| `defaultTab` | `number` | No | `0` | Initial active tab index (uncontrolled) |
| `tab` | `number` | No | — | Current active tab index (controlled) |
| `onTabChange` | `(event: TabChangeEvent) => void` | No | — | Callback fired when tab changes |

### SectionTabList Props

The SectionTabList component accepts all standard HTML `<div>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | Yes | — | SectionTab components |
| `enableTransitions` | `boolean \| undefined` | No | `undefined` | Controls transition behavior (undefined = disabled on initial render, enabled afterwards) |

### SectionTab Props

The SectionTab component accepts all standard HTML `<button>` attributes (except `onClick`) in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `index` | `number` | Yes | — | Tab index (0-based) |
| `disabled` | `boolean` | No | `false` | Whether the tab is disabled |
| `isActiveUncontrolled` | `boolean` | No | `false` | Forces active appearance |
| `onClick` | `(index: number) => void` | No | — | Callback fired when tab is clicked |
| `children` | `React.ReactNode` | Yes | — | Tab content |

### SectionTabPanel Props

The SectionTabPanel component accepts all standard HTML `<div>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `index` | `number` | Yes | — | Panel index (must match corresponding tab) |
| `children` | `React.ReactNode` | Yes | — | Panel content |

### Type Definitions

```tsx
export interface TabChangeEvent {
  previousTab: number;
  currentTab: number;
}

export interface SectionTabsDSProps {
  children: React.ReactNode;
  defaultTab?: number;
  tab?: number;
  onTabChange?: (event: TabChangeEvent) => void;
}

export type SectionTabsProps = HTMLAttributes<HTMLDivElement> & SectionTabsDSProps;

export interface SectionTabListDSProps {
  children: React.ReactNode;
  enableTransitions?: boolean;
}

export type SectionTabListProps = HTMLAttributes<HTMLDivElement> & SectionTabListDSProps;

export interface SectionTabDSProps {
  children: React.ReactNode;
  index: number;
  disabled?: boolean;
  isActiveUncontrolled?: boolean;
  onClick?: (index: number) => void;
}

export type SectionTabProps = Omit<HTMLAttributes<HTMLButtonElement>, 'onClick'> & SectionTabDSProps;

export interface SectionTabPanelDSProps {
  children: React.ReactNode;
  index: number;
}

export type SectionTabPanelProps = HTMLAttributes<HTMLDivElement> & SectionTabPanelDSProps;
```

## Related Components

- [NavigationTabs](../NavigationTabs/NavigationTabs.md) – Alternative component for page-level navigation tabs.
- [PageIndicator](../PageIndicator/PageIndicator.md) – For indicating current page/section.
- [ButtonGroup](../ButtonGroup/ButtonGroup.md) – Alternative component for button-based selection within a view.
- [Accordion](../Accordion/Accordion.md) – Alternative component for organizing collapsible content sections.

# Select

The Select component displays a predefined list of options, allowing the user to choose one, and is commonly used in forms or filters.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=252-179)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-select--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Select/Select.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/Select/)*
<details open>
<summary>Code example</summary>

```tsx
import { Select } from '@yleisradio/yds-components-react';

<Select
  id="select-basic"
  name="selectBasic"
  label="Category"
  placeholder="Select an option"
  items={[
    { label: 'News', value: 'news' },
    { label: 'Sports', value: 'sports' },
    { label: 'Culture', value: 'culture', disabled: true }
  ]}
  onChange={() => {}}
/>
```
</details>

## Why to use

Select provides a compact way to display multiple options and ensures consistent input values by restricting users to a predefined list.

## When to use

Use a Select when users must choose a single option from a predefined list. Select works best with short, familiar lists where searching is unnecessary and where restricting input prevents errors.

Select is well suited for forms, filters and settings where choices are stable and clearly defined.

> **Do**
> - Use a Select when the user needs to choose a single item from a short list (fewer than 8 options).
> - Use a Select when filtering by typing is not required.
> - Organize options logically or alphabetically.
> - Provide helper text when options need clarification.
> - Keep option lists short and comparable.
> - Always provide a clear, descriptive label.

> **Don’t**
> - Don’t use a Select when there are 8 or more options — use a [ComboboxSingleSelect](../ComboboxSingleSelect/ComboboxSingleSelect.md) instead.
> - Don’t use a Select if the user needs to filter or search options by typing.
> - Don’t use Select for navigation or triggering actions — use an [ActionMenu](../ActionMenu/ActionMenu.md) instead.
> - Don’t rely on placeholder text as the only instruction, as it’s skipped by screen readers.
> - Don’t overload the dropdown with unnecessary contextual information.

## Content Guidelines

Select fields must present clear, concise labels and easy-to-scan option lists. Consistency is important, as users choose from predetermined values.

> **Do**
> - Use short, descriptive labels (e.g., “Kategoria”, “Kieli”, “Tila”).
> - Keep option labels consistent in style (esim. kaikki substantiiveja).
> - Use compact placeholder text (e.g., “Valitse vaihtoehto”).
> - Add helper text when selection needs extra context (e.g., “Valitse pääasiallinen kategoria”).
> - Write specific and helpful error messages (e.g., “Valinta vaaditaan”).
> - Order items logically (alphabetically, most common first).

> **Don’t**
> - Don’t duplicate the same text in label and placeholder.
> - Don’t use ambiguous labels (e.g., “Vaihtoehto 1”).
> - Don’t embed explanations inside option labels.
> - Don’t rely solely on placeholder text — it disappears after selection.
> - Don’t mix inconsistent naming patterns.

## Anatomy

![Select anatomy](../../img/select-anatomy.svg)

1. **Label** – Describes the purpose of the field.
2. **Placeholder** – Example or hint text shown before a selection is made.
3. **Description** – Additional guidance or context below the field.
4. **Input field** – Visual container that communicates interaction and validation states.
5. **Dropdown indicator** – Icon showing the dropdown state and affordance to open options.

> **Warning**
> Select dropdown follows native browser rendering and behavior, which may vary slightly across platforms.

## Key Props

Use the following props to customize the Select component to fit your needs.

### items

Array of option objects. Each option renders an `<option>` inside the native `<select>`.

| Prop    | Shape                                                     | Description                                                                                        |
| ------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `items` | `{ label: string; value?: string; disabled?: boolean }[]` | List of options. `value` defaults to `label` when omitted. `disabled` makes option non-selectable. |

<details>
<summary>Code example</summary>

```tsx
  <Select
    id="country"
    name="country"
    label="Country"
    items={[
      { label: 'Finland', value: 'fi' },
      { label: 'Sweden', value: 'se' },
      { label: 'Norway', value: 'no', disabled: true },
    ]}
    onChange={() => {}}
    placeholder="Select country"
    onChange={() => {}}
  />
  ```
</details>

### placeholder

Shown as the first hidden option. If provided, the underlying select is marked `required`, encouraging explicit selection.

| Type     | Example                                                                                                                            | Description                  |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `string` | <Select id="ph" name="ph" label="Category" placeholder="Select an option" items={[{label:'A'},{label:'B'}]} onChange={() => {}} /> | Initial unselected guidance. |

<details>
<summary>Code example</summary>

```tsx
  <Select
    id="ph"
    name="ph"
    label="Category"
    placeholder="Select an option"
    items={[{ label: 'Option A' }, { label: 'Option B' }]}
    onChange={() => {}}
  />
  ```
</details>

### label

> **Warning**
> Label can be visually hidden but must remain readable for screen readers.

| Type     | Example                                                                                                         | Description                         |
| -------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `string` | <Select id="desc" name="desc" label="Category" items={[{label:'News'},{label:'Sports'}]} onChange={() => {}} /> | Provides a clear purpose the field. |

<details>
<summary>Code example</summary>

```tsx
  <Select
    id="desc"
    name="desc"
    label="Category"
    items={[{ label: 'News' }, { label: 'Sports' }]}
    onChange={() => {}}
  />
  ```
</details>

### description

Helper guidance placed below the field.

| Type     | Example                                                                                                                                               | Description                                   |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `string` | <Select id="desc" name="desc" label="Category" description="Choose primary category" items={[{label:'News'},{label:'Sports'}]} onChange={() => {}} /> | Provides additional guidance below the field. |

<details>
<summary>Code example</summary>

```tsx
  <Select
    id="desc"
    name="desc"
    label="Category"
    description="Choose primary category"
    items={[{ label: 'News' }, { label: 'Sports' }]}
    onChange={() => {}}
  />
  ```
</details>

### success

| Type      | Example                                                                                                               | Description                                 |
| --------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `boolean` | <Select id="ok" name="ok" label="Category" success items={[{label:'A'},{label:'B'}]} value="A" onChange={() => {}} /> | Shows success border when no error present. |

<details>
<summary>Code example</summary>

```tsx
  <Select
    id="ok"
    name="ok"
    label="Category"
    success
    items={[{ label: 'Option A' }, { label: 'Option B' }]}
    value="Option A"
    onChange={() => {}}
  />
  ```
</details>

### errorMessage

| Type     | Example                                                                                                                                              | Description                                                       |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `string` | <Select id="err" name="err" label="Category" errorMessage="Selection required" items={[{label: ''}, {label:'A'},{label:'B'}]} onChange={() => {}} /> | Displays a validation error below the field. Sets `aria-invalid`. |

<details>
<summary>Code example</summary>

```tsx
  <Select
    id="err"
    name="err"
    label="Category"
    errorMessage="Selection required"
    items={[{ label: '' }, { label: 'Option A' }, { label: 'Option B' }]}
    onChange={() => {}}
  />
  ```
</details>

### isDisabled

| Type      | Example                                                                                                              | Description                            |
| --------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `boolean` | <Select id="dis" name="dis" label="Category" isDisabled items={[{label:'One'},{label:'Two'}]} onChange={() => {}} /> | Temporarily prevents user interaction. |

<details>
<summary>Code example</summary>

```tsx
  <Select
    id="dis"
    name="dis"
    label="Category"
    isDisabled
    items={[{ label: 'One' }, { label: 'Two' }]}
    onChange={() => {}}
  />
  ```
</details>

## Behavior

- The dropdown opens on click and closes after selection.
- The selected item replaces the placeholder text.
- Disabled state blocks user interaction and dims visuals.
- Error state displays a red outline and error message.
- Optional fields are indicated with (Optional) in the label.
- Tooltips provide contextual information but not essential content.

## Accessibility

- Always provide a label — required for assistive technologies.
- Placeholder text is not read by screen readers and disappears after selection.
- Ensure full keyboard accessibility (Tab, Arrow keys, Enter)<br /> ([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard))

## Implementation examples

### Gender selection

*[Live preview](https://design-system.yle.fi/docs/components/Select/)*
<details open>
<summary>Code example</summary>

```tsx
  <Select
    id="ex-basic"
    name="exBasic"
    label="Gender"
    placeholder="Select an option"
    items={[
      { label: 'Female' },
      { label: 'Male' },
      { label: 'Other' },
      { label: 'Prefer not to say' },
    ]}
    onChange={() => {}}
  />
  ```
</details>

### Preselected value

*[Live preview](https://design-system.yle.fi/docs/components/Select/)*
<details open>
<summary>Code example</summary>

```tsx
  <Select
    id="ex-pre"
    name="exPre"
    label="Status"
    items={[{ label: 'Open' }, { label: 'Closed' }]}
    value="Closed"
    onChange={() => {}}
  />
  ```
</details>

### With error

*[Live preview](https://design-system.yle.fi/docs/components/Select/)*
<details open>
<summary>Code example</summary>

```tsx
  <Select
    id="ex-error"
    name="exError"
    label="Category"
    errorMessage="Selection required"
    items={[{ label: '' }, { label: 'Option A' }, { label: 'Option B' }]}
    onChange={() => {}}
  />
  ```
</details>

## API Reference

### Props

The Select component accepts all standard HTML `<select>` attributes in addition to the following props:

| Prop           | Type                                                | Required | Default | Description |
| -------------- | --------------------------------------------------- | -------- | ------- | ----------- |
| `label`        | `string`                                            | Yes      | —       |             |
| `labelOptions` | `FormElementLabelDSProps`                           | No       | `{}`    |             |
| `name`         | `string`                                            | Yes      | —       |             |
| `id`           | `string`                                            | Yes      | —       |             |
| `value`        | `string`                                            | No       | —       |             |
| `placeholder`  | `string`                                            | No       | —       |             |
| `onChange`     | `(e: React.ChangeEvent<HTMLSelectElement>) => void` | Yes      | —       |             |
| `description`  | `string`                                            | No       | —       |             |
| `errorMessage` | `string`                                            | No       | —       |             |
| `success`      | `boolean`                                           | No       | `false` |             |
| `isDisabled`   | `boolean`                                           | No       | `false` |             |
| `items`        | `Option[]`                                          | Yes      | —       |             |

### Type Definitions

```tsx
interface Option {
  value?: string;
  label: string;
  disabled?: boolean;
}

export interface SelectDSProps {
  label: string;
  labelOptions?: FormElementLabelDSProps;
  name: string;
  id: string;
  value?: string;
  placeholder?: string;
  onChange: (e: React.ChangeEvent<HTMLSelectElement>) => void;
  description?: string;
  errorMessage?: string;
  success?: boolean;
  isDisabled?: boolean;
  items: Option[];
}

export type SelectProps = SelectHTMLAttributes<HTMLSelectElement> & SelectDSProps;
```

## Related Components

- [TextInput](../TextInput/TextInput.md): For single-line open text responses.
- [TextArea](../TextArea/TextArea.md): For multi-line open text responses.
- [SearchInput](../SearchInput/SearchInput.md): For search functionality.
- [ComboboxSingleSelect](../ComboboxSingleSelect/ComboboxSingleSelect.md): For searchable single-select dropdowns.
- [DropdownMenu](../DropdownMenu/DropdownMenu.md): For actionable dropdowns.
- [Radio](../Radio/Radio.md): For selecting one option from a small set of choices.
- [Slider](../Slider/Slider.md): For selecting a numeric value from a bounded range.

# Slider

A Slider lets users select a numeric value from a defined range by dragging a circle along a track.

- [Figma](https://www.figma.com/design/pbZJxEQAbQu2EmhQojAj8K/Koneiden-standardointi?node-id=555-9501)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-slider--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Slider/Slider.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/Slider/)*

<details open>
<summary>Code example</summary>

```tsx
import { Slider } from '@yleisradio/yds-components-react';

<Slider label="Label" min={0} max={100} defaultValue={40} />
```
</details>

## Why to use

Slider makes it easy to pick a numeric value from a bounded range without typing. It's fast to adjust, which makes it especially well suited to touch and mobile contexts. It's also great for quick adjustments where the change can be seen continuously and immediately.

## When to use

Use Slider when users need to pick a value within a defined numeric range and the relative position (low, mid, high) communicates meaning — for example, a price ceiling, age range, rating, or a filter threshold.

> **Do**
> - Use Slider for bounded numeric ranges where approximate selection is acceptable and the range has a clear low-to-high direction.
> - Use Slider when the interaction should be fast and easy, for example on touch and mobile surfaces, where dragging is easier than typing into a small field.
> - Use Slider for quick, low-stakes adjustments where users want to see the effect of the change immediately (volume, brightness, filter thresholds).
> - Use Slider with the `highlight` variant to draw attention to the slider in key user interactions (e.g. filter panels, calculators, infographic controls).

> **Don't**
> - Don't use Slider when the user must enter a value that doesn't map to a continuous range — use [TextInput](../TextInput/TextInput.md) or [Select](../Select/Select.md) instead.
> - Don't use Slider for large discrete sets (e.g. selecting 1 of 50 named categories) — use a [Select](../Select/Select.md) or [ComboboxSingleSelect](../ComboboxSingleSelect/ComboboxSingleSelect.md).
> - Don't use Slider when the exact value is critical and an approximate selection creates errors (e.g. a date of birth) — use a [TextInput](../TextInput/TextInput.md).
> - Don't use Slider for star ratings or other expressive scoring — use a [RadioGroupNumericScale](../Radio/Radio.md) or a dedicated rating control.
> - Don't use Slider when there are fewer than five steps to choose from — the thumb is hard to land precisely on a coarse scale; use [Radio](../Radio/Radio.md) buttons or a [Select](../Select/Select.md) instead.
> - Don't use Slider for media playback – use dedicated media player controls instead.

## Content Guidelines

> **Do**
> - Use a short, descriptive `label` (e.g. "Maximum price", "Volume").
> - Use `unit` to add a unit suffix to the value box (e.g. "€", "%", "vuotta"). Remember to take singular/plural into account when the unit is a word.
> - Use `description` sparinglyfor a short explanatory sentence when the range limits alone are not self-evident.

> **Don't**
> - Don't repeat the label in the description.
> - Don't use errorMessage for per-keystroke validation or for range overflows that are automatically corrected when user finishes typing.

## Anatomy

1. **Label** – Describes the purpose of the range. Always visible (or visually hidden for screen readers via `labelOptions`).
2. **Value box** – A compact editable [TextInput](../TextInput/TextInput.md) that displays and accepts numeric input. Enabled by default; hide with `showValueBox={false}`.
3. **Track** – The background bar representing the full range.
4. **Fill** – The coloured segment from `min` to the current value, using the variant colour.
5. **Thumb** – The circular drag handle positioned at the current value.
6. **Min / Max labels** – Small text labels at the left and right ends of the track. Default to the numeric `min` / `max` values; customise with `minLabel` / `maxLabel`.
7. **Description** – Optional helper text below the min/max row.
8. **Error message** – Optional message for externally-driven validation (e.g. a server response or a no-results condition). Set via `errorMessage`.

## Key Props

### value / defaultValue / onChange

The Slider supports both controlled and uncontrolled usage.

| Pattern      | Example                                    | Notes                                                   |
| ------------ | ------------------------------------------ | ------------------------------------------------------- |
| Controlled   | `<Slider value={val} onChange={setVal} />` | You manage state; `onChange` receives the new `number`. |
| Uncontrolled | `<Slider defaultValue={40} />`             | Internal state; use `onChange` to observe changes.      |

<details>
<summary>Code example</summary>

```tsx
// Controlled
const [price, setPrice] = useState(40000);
<Slider label="Maximum price" value={price} onChange={setPrice} min={0} max={100000} />

// Uncontrolled

<Slider label="Volume" defaultValue={50} />
```
</details>

### min / max / step

Define the range and granularity of valid values.

| Prop   | Type     | Default | Description                                                                                                                     |
| ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `min`  | `number` | `0`     | Minimum selectable value.                                                                                                       |
| `max`  | `number` | `100`   | Maximum selectable value.                                                                                                       |
| `step` | `number` | `1`     | Snapping interval. Value box entry is clamped and snapped to step on blur (snapping can be disabled with `snapToStep={false}`). |

<details>
<summary>Code example</summary>

```tsx
  <Slider label="Price" min={8000} max={80000} step={1000} defaultValue={40000} />
  ```
</details>

### variant

Controls the colour of the fill and thumb.

| Value       | Example                                                                                                   | Description                                                                                  |
| ----------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `default`   | <Slider label="Default" min={0} max={100} defaultValue={40} variant="default" showValueBox={false} />     | Suitable for forms and situations where you don't want to emphasize the slider control.      |
| `highlight` | <Slider label="Highlight" min={0} max={100} defaultValue={40} variant="highlight" showValueBox={false} /> | Suitable for situations where you want to emphasize or draw attention to the slider control. |

<details>
<summary>Code example</summary>

```tsx
  <Slider
    label="Default"
    min={0}
    max={100}
    defaultValue={40}
    variant="default"
    showValueBox={false}
  />
  <Slider
    label="Highlight"
    min={0}
    max={100}
    defaultValue={40}
    variant="highlight"
    showValueBox={false}
  />
  ```
</details>

### minLabel / maxLabel

Override the text shown at each end of the track.

| Type        | Example                                                                                                           | Description                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `ReactNode` | <Slider label="Price" min={0} max={100} defaultValue={50} minLabel="0 €" maxLabel="100 €" showValueBox={false} /> | Any React content; defaults to the number-formatted `min` / `max`, with `unit` appended when set. |

<details>
<summary>Code example</summary>

```tsx
  <Slider
    label="Price"
    min={0}
    max={100}
    defaultValue={50}
    minLabel="0 €"
    maxLabel="100 €"
    showValueBox={false}
  />
  ```
</details>

### showMinMaxLabels

Controls visibility of the min/max labels at the ends of the track. Use it for compact contexts where the boundaries are already clear (e.g. when the value box and a description convey the range).

| Type      | Default | Description                                         |
| --------- | ------- | --------------------------------------------------- |
| `boolean` | `true`  | Set to `false` to hide both the min and max labels. |

<details>
<summary>Code example</summary>

```tsx
  <Slider label="Volume" defaultValue={50} showMinMaxLabels={false} />
  ```
</details>

### description

Helper text displayed below the min/max labels.

| Type     | Example                                                                                                                    | Description                  |
| -------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `string` | <Slider label="Volume" min={0} max={100} defaultValue={50} description="Affects all audio output." showValueBox={false} /> | Short guidance for the user. |

<details>
<summary>Code example</summary>

```tsx
  <Slider
    label="Volume"
    min={0}
    max={100}
    defaultValue={50}
    description="Affects all audio output."
    showValueBox={false}
  />
  ```
</details>

### errorMessage

For surfacing externally-driven feedback about the **overall result** of the selection — for example when the chosen value produces no results or an invalid calculation — rather than validation of the value itself. The Slider never produces an invalid value: out-of-range or non-numeric value-box input is silently corrected on blur. Because the message reflects the overall outcome rather than a momentary invalid keystroke, it is announced with `aria-live="polite"`, so it waits for a natural pause instead of interrupting the user.

| Type     | Example                                                                                                                                     | Description                                                                      |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `string` | <Slider label="Maximum price" min={0} max={100} defaultValue={50} errorMessage="No results match this price range." showValueBox={false} /> | Renders the message below the slider, announced politely (`aria-live="polite"`). |

<details>
<summary>Code example</summary>

```tsx
  <Slider
    label="Maximum price"
    min={0}
    max={100}
    defaultValue={50}
    errorMessage="No results match this price range."
    showValueBox={false}
  />
  ```
</details>

### showValueBox

Controls visibility of the editable TextInput value box in the top-right corner.

| Type      | Default | Description                           |
| --------- | ------- | ------------------------------------- |
| `boolean` | `true`  | Set to `false` to hide the value box. |

<details>
<summary>Code example</summary>

```tsx
  <Slider label="Volume" defaultValue={50} showValueBox={false} />
  ```
</details>

### unit

Appends a unit suffix inside the value box (e.g. `€`, `%`, `vuotta`). The box grows to fit varying-length units while the value stays right-aligned. When set, the unit is also appended to the default `minLabel` / `maxLabel` (e.g. `0 €` / `80 000 €`) unless you override them.

| Type     | Example                                                                                                           | Description                            |
| -------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `string` | <Slider label="Loan period" min={1} max={30} step={1} defaultValue={15} unit="vuotta" showMinMaxLabels={false} /> | Unit shown after the value in the box. |

<details>
<summary>Code example</summary>

```tsx
  <Slider label="Loan period" min={1} max={30} defaultValue={15} unit="vuotta" />
  <Slider label="Maximum price" min={8000} max={80000} step={1000} defaultValue={43000} unit="€" />
  ```
</details>

### numberFormat

Controls how the value is displayed in and parsed from the value box, min/max labels, and the screen-reader `aria-valuetext`. **Defaults to Finnish (fi-FI) conventions** — a no-break space groups thousands and a comma is the decimal delimiter — so you rarely need to set it. Override individual fields when needed; pass `thousandSeparator: ''` to disable grouping.

| Field               | Type     | Default                     | Description                               |
| ------------------- | -------- | --------------------------- | ----------------------------------------- |
| `thousandSeparator` | `string` | `'\u00a0'` (no-break space) | Character between groups of three digits. |
| `decimalDelimiter`  | `string` | `','`                       | Decimal delimiter.                        |
| `decimalPlaces`     | `number` | precision of `step`         | Number of decimal places to display.      |

*[Live preview](https://design-system.yle.fi/docs/components/Slider/)*

<details>
<summary>Code example</summary>

```tsx
// fi-FI by default → "43 000"
<Slider label="Maximum price" min={8000} max={80000} step={1000} defaultValue={43000} unit="€" />

// Interest rate with two decimals → "3,50"

<Slider
  label="Interest rate"
  min={0}
  max={10}
  step={0.01}
  defaultValue={3.5}
  unit="%"
  numberFormat={{ decimalPlaces: 2 }}
/>

// Disable grouping → "43000"

<Slider label="Code" min={0} max={99999} defaultValue={43000} numberFormat={{ thousandSeparator: '' }} />
```
</details>

### inputMode

Sets the virtual-keyboard hint for the value box. Defaults to `'decimal'` when fractional values are allowed (via `step` or `numberFormat.decimalPlaces`), otherwise `'numeric'`. Override it when the automatic choice isn't appropriate.

| Type                                         | Default | Description                                         |
| -------------------------------------------- | ------- | --------------------------------------------------- |
| `'numeric' \| 'decimal' \| 'text' \| 'none'` | auto    | Forwarded to the value box `<input>`'s `inputMode`. |

<details>
<summary>Code example</summary>

```tsx
  <Slider label="Amount" min={0} max={100} step={0.5} defaultValue={10} inputMode="decimal" />
  ```
</details>

### snapToStep

Controls whether the value box snaps entries to `step`. Defaults to `true`. When `false`, the box accepts any number within `[min, max]` (a typed value like `43 521` is kept as-is and the thumb sits exactly on it), while dragging the slider still snaps to `step`. The range temporarily uses `step="any"` after a value is typed so the thumb can rest on the exact value, and the prop `step` is restored the moment the slider is engaged.

| Type      | Default | Description                                                                                      |
| --------- | ------- | ------------------------------------------------------------------------------------------------ |
| `boolean` | `true`  | Set to `false` to allow exact, off-step values via the value box while keeping a stepped slider. |

<details>
<summary>Code example</summary>

```tsx // Numbers format with Finnish (fi-FI) conventions by default — no numberFormat needed.
  <Slider
    label="Maximum price"
    min={8000}
    max={80000}
    step={1000}
    defaultValue={43000}
    unit="€"
    snapToStep={false}
  />
  ```
</details>

### isDisabled

Prevents user interaction with both the range input and the value box.

| Type      | Example                                                                                         | Description           |
| --------- | ----------------------------------------------------------------------------------------------- | --------------------- |
| `boolean` | <Slider label="Disabled" min={0} max={100} defaultValue={50} isDisabled showValueBox={false} /> | Disables the control. |

<details>
<summary>Code example</summary>

```tsx
  <Slider label="Disabled" min={0} max={100} defaultValue={50} isDisabled showValueBox={false} />
  ```
</details>

## Behavior

- Dragging the thumb or pressing arrow keys on the focused range input updates the value immediately and calls `onChange`.
- The value box reflects the current value at all times. Editing the box updates the range on blur or when `Enter` is pressed.
- Numbers are formatted with Finnish (fi-FI) conventions by default (no-break space thousands separator, comma decimal); customise via `numberFormat`.
- Invalid input in the value box is silently corrected on blur with no error state shown: out-of-range values are clamped to `[min, max]` and (unless `snapToStep={false}`) snapped to the nearest `step`; empty or non-numeric input reverts to the current value.
- With `snapToStep={false}`, the range temporarily switches to `step="any"` after a value is typed so the thumb rests on the exact value, and restores the prop `step` the moment the slider is engaged so dragging snaps to the grid.
- In controlled mode, state is managed by the parent. In uncontrolled mode, state is managed internally.
- The `ref` is forwarded to the underlying `<input type="range">` element.

## Accessibility

Things to keep in mind when using this component:

- Always pass a clear, descriptive `label`. It names both the slider and its value box. Only use `labelOptions={{ isHidden: true }}` when the surrounding content already makes the purpose unambiguous.<br />([WCAG 3.3.2 — Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions))
- When you set a `unit` (e.g. `€`, `%`), choose a value that reads well aloud — it is spoken as part of the value (e.g. "43 000 euroa" depends on how the screen reader pronounces the symbol). Prefer a word unit (`vuotta`) when a symbol would be ambiguous.
- Don't rely on the `variant` colour alone to convey meaning; the colour difference is decorative.<br />([WCAG 1.4.1 — Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color))
- Use `errorMessage` only for outcome-level feedback (no results, failed calculation), not for per-keystroke validation. It is announced politely so it won't talk over the user — avoid putting time-critical or blocking information in it.
- Give the range meaningful context through `min` / `max` labels (or a `description`) when the bare numbers aren't self-explanatory; hiding them with `showMinMaxLabels={false}` is fine only when the value box and surrounding copy already convey the range.
- The value box is a real text field — keep `step`, `numberFormat`, and `unit` consistent with what users are expected to type, so keyboard entry matches what they see.
- There are unresolved accessibility difficulties with `input type="number"`, thus we use `input type="text"` with a custom value box. Component tries to use the correct `inputMode` for the expected mobile keyboard input (e.g. `decimal` for fractional values, `numeric` for whole numbers).

## Implementation examples

### Price range slider

A common use case — a budget selector with currency min/max labels and a description.

*[Live preview](https://design-system.yle.fi/docs/components/Slider/)*

<details open>
<summary>Code example</summary>

```tsx
import { Slider } from '@yleisradio/yds-components-react';

<Slider
  label="Maximum price"
  min={8000}
  max={80000}
  step={1000}
  defaultValue={43000}
  minLabel="8 000 €"
  maxLabel="80 000 €"
  description="Select the maximum price for your search."
  variant="highlight"
/>
```
</details>

### With external validation feedback

Use `errorMessage` when the parent determines the selected value is invalid — for example when a search returns no results for the chosen range.

*[Live preview](https://design-system.yle.fi/docs/components/Slider/)*

<details open>
<summary>Code example</summary>

```tsx
import { Slider } from '@yleisradio/yds-components-react';

<Slider
  label="Maximum price"
  min={8000}
  max={80000}
  step={1000}
  defaultValue={79000}
  minLabel="8 000 €"
  maxLabel="80 000 €"
  variant="highlight"
  errorMessage="No results match this price range."
/>
```
</details>

## API Reference

### Props

The Slider component forwards additional props to the underlying `<input type="range">` element. Note that `onChange`, `value`, and `defaultValue` are replaced by the Slider-specific versions below.

| Prop               | Type                                         | Required | Default                    | Description                                                                                                                                                                                  |
| ------------------ | -------------------------------------------- | -------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`            | `string`                                     | Yes      | —                          | Visible label for the field.                                                                                                                                                                 |
| `labelOptions`     | `FormElementLabelProps`                      | No       | `{}`                       | Options forwarded to `FormElementLabel` (e.g. `isHidden`, `optionalLabel`).                                                                                                                  |
| `id`               | `string`                                     | No       | auto-generated             | HTML `id` for the range input. Used to wire label and ARIA attributes.                                                                                                                       |
| `value`            | `number`                                     | No       | —                          | Controlled value.                                                                                                                                                                            |
| `defaultValue`     | `number`                                     | No       | `min`                      | Uncontrolled initial value.                                                                                                                                                                  |
| `onChange`         | `(value: number) => void`                    | No       | —                          | Called with the new numeric value on every change.                                                                                                                                           |
| `min`              | `number`                                     | No       | `0`                        | Minimum value.                                                                                                                                                                               |
| `max`              | `number`                                     | No       | `100`                      | Maximum value.                                                                                                                                                                               |
| `step`             | `number`                                     | No       | `1`                        | Step interval. Box entry snaps to it unless `snapToStep={false}`.                                                                                                                            |
| `variant`          | `SliderVariant`                              | No       | `'default'`                | `'default'` or `'highlight'`.                                                                                                                                                                |
| `description`      | `string`                                     | No       | —                          | Helper text shown below min/max labels.                                                                                                                                                      |
| `errorMessage`     | `string`                                     | No       | —                          | External outcome feedback (e.g. no results or failed calculation), announced via `aria-live="polite"`.                                                                                       |
| `minLabel`         | `ReactNode`                                  | No       | formatted `min` (+ `unit`) | Content shown at the left end of the track. Defaults to the number-formatted `min`, with `unit` appended when set.                                                                           |
| `maxLabel`         | `ReactNode`                                  | No       | formatted `max` (+ `unit`) | Content shown at the right end of the track. Defaults to the number-formatted `max`, with `unit` appended when set.                                                                          |
| `showMinMaxLabels` | `boolean`                                    | No       | `true`                     | Show/hide the min and max track labels.                                                                                                                                                      |
| `showValueBox`     | `boolean`                                    | No       | `true`                     | Show/hide the editable value box.                                                                                                                                                            |
| `valueBoxLabel`    | `string`                                     | No       | `label`                    | Accessible label for the value box (visually hidden).                                                                                                                                        |
| `unit`             | `string`                                     | No       | —                          | Unit suffix shown inside the value box (e.g. `€`, `%`, `vuotta`).                                                                                                                            |
| `numberFormat`     | `SliderNumberFormat`                         | No       | fi-FI                      | Thousand separator, decimal delimiter and decimal places for display/parse. Defaults to Finnish (fi-FI) conventions: a no-break space groups thousands and a comma is the decimal delimiter. |
| `inputMode`        | `'numeric' \| 'decimal' \| 'text' \| 'none'` | No       | auto                       | Virtual-keyboard hint for the value box. Defaults to `decimal` when fractional values are allowed, otherwise `numeric`.                                                                      |
| `snapToStep`       | `boolean`                                    | No       | `true`                     | When `false`, the value box accepts any number within `[min, max]` (no rounding to `step`) and the thumb sits exactly on it; dragging the slider still snaps to `step`.                      |
| `isDisabled`       | `boolean`                                    | No       | `false`                    | Disables the slider and value box.                                                                                                                                                           |
| `isRequired`       | `boolean`                                    | No       | `false`                    | Marks the field as required.                                                                                                                                                                 |

### Type Definitions

```tsx
export type SliderVariant = 'default' | 'highlight';

export interface SliderDSProps {
  label: string;
  labelOptions?: FormElementLabelProps;
  id?: string;
  value?: number;
  defaultValue?: number;
  onChange?: (value: number) => void;
  min?: number;
  max?: number;
  step?: number;
  variant?: SliderVariant;
  description?: string;
  errorMessage?: string;
  minLabel?: ReactNode;
  maxLabel?: ReactNode;
  showMinMaxLabels?: boolean;
  showValueBox?: boolean;
  valueBoxLabel?: string;
  unit?: string;
  numberFormat?: SliderNumberFormat;
  inputMode?: 'numeric' | 'decimal' | 'text' | 'none';
  snapToStep?: boolean;
  isDisabled?: boolean;
  isRequired?: boolean;
}

export interface SliderNumberFormat {
  /** Character inserted between groups of three digits. Defaults to a no-break space ('\u00a0'), per Finnish (fi-FI) convention. Pass '' to disable grouping. */
  thousandSeparator?: string;
  /** Character used as the decimal delimiter. Defaults to ',', per Finnish (fi-FI) convention. */
  decimalDelimiter?: string;
  /** Number of decimal places to display. Defaults to the precision implied by `step`. */
  decimalPlaces?: number;
}

export type SliderProps = Omit<
  InputHTMLAttributes<HTMLInputElement>,
  'onChange' | 'value' | 'defaultValue'
> &
  SliderDSProps;
```

## Related Components

- [ProgressBar](../ProgressBar/ProgressBar.md): For displaying read-only progress or completion, not for user input.
- [TextInput](../TextInput/TextInput.md): For free-form numeric entry without a range constraint.
- [Select](../Select/Select.md): For choosing from a fixed set of discrete values.

# Spinner

A Spinner indicates that a process is ongoing and the user must wait, typically shown when content is loading or when interaction is temporarily blocked.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=285-1946)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-spinner--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Spinner/Spinner.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/Spinner/)*

<details open>
<summary>Code example</summary>

```tsx
import { Spinner } from '@yleisradio/yds-components-react';

<Spinner />
```
</details>

## Why to use

A Spinner communicates that the system is working and reduces uncertainty while users wait. It provides simple, lightweight feedback when progress cannot be measured precisely (for example when duration is unknown or no percentage can be shown).

## When to use

Use a Spinner to indicate a temporary waiting state when the system is working in the background and progress cannot be clearly measured or predicted.

> **Do**
> - Use a Spinner when content is loading or updating asynchronously.
> - Use it when an operation is in progress and its duration is short or unpredictable.
> - Use a Spinner when progress cannot be meaningfully expressed with a progress bar (no clear steps or percentage).
> - Use it when part of the UI is temporarily unavailable while data is being fetched or processed.

> **Don't**
> - Don’t use a Spinner for long-running operations where progress can be measured — use a [ProgressBar](../ProgressBar/ProgressBar.md) instead.
> - Don’t block essential content with a Spinner for an extended time without additional explanation.
> - Don’t use a Spinner when users need to understand how much work remains.
> - Don't show multiple spinners in close proximity, as this can create visual clutter and confusion.

## Content Guidelines

> **Do**
> - Use a label only when the loading duration is long enough to read it.
> - Use a label to clarify what is loading when it’s not otherwise obvious.
> - Use short, descriptive labels (e.g., “Ladataan sisältöä…”).

> **Don't**
> - Don’t use placeholders like “Lataa…” or “Ladataan…” — they’re not helpful.
> - Don’t use vague or verbose text (e.g., “Odota hetki, käsittelemme pyyntöäsi.”).
> - Don’t rely on the label to explain long or complex operations.

## Key Spinner Props

Use these props to configure the Spinner component.

### size
Controls the dimensions of the spinner.

| Value | Example | Description |
|-------|---------|-------------|
| `sm` | <Spinner size="sm" /> | Small spinner (24px) for inline use |
| `md` | <Spinner size="md" /> | Default size (48px) for general use |
| `lg` | <Spinner size="lg" /> | Large spinner (72px) for prominent loading states |

<details>
<summary>Code example</summary>

```tsx
<Spinner size="sm" />
<Spinner size="md" />
<Spinner size="lg" />
```
</details>

### variant
Defines the visual style and color scheme.

| Value | Example | Description |
|-------|---------|-------------|
| `default` | <Spinner variant="default" /> | Standard spinner using default text color |
| `highlight` | <Spinner variant="highlight" /> | Highlighted spinner using accent color |
| `default-negative` | <div style={{ background: '#333', padding: '16px', borderRadius: '4px' }}><Spinner variant="default-negative" /></div> | Default spinner for dark backgrounds |
| `highlight-negative` | <div style={{ background: '#333', padding: '16px', borderRadius: '4px' }}><Spinner variant="highlight-negative" /></div> | Highlighted spinner for dark backgrounds |

<details>
<summary>Code example</summary>

```tsx
<Spinner variant="default" />
<Spinner variant="highlight" />
<Spinner variant="default-negative" />
<Spinner variant="highlight-negative" />
```
</details>

### hasBackground
Adds a background circle to improve visibility.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Spinner hasBackground /> | Shows a subtle background circle behind the spinner |

<details>
<summary>Code example</summary>

```tsx
<Spinner hasBackground />
<Spinner hasBackground={false} />
```
</details>

### label
Provides descriptive text below the spinner.

| Type | Example | Description |
|------|---------|-------------|
| `string` | <Spinner label="Loading content..." /> | Addtitional text to clarify the reason for showing spinner |

<details>
<summary>Code example</summary>

```tsx
<Spinner label="Loading content..." />
<Spinner label="Processing your request" />
```
</details>

### colors
Custom color overrides for advanced styling.

| Type | Example | Description |
|------|---------|-------------|
| `{ spinner?: string; background?: string }` | <Spinner colors={{ spinner: '#ff0000', background: '#cccccc' }} hasBackground /> | Custom colors for spinner and background |

<details>
<summary>Code example</summary>

```tsx
<Spinner colors={{ spinner: '#ff0000' }} />
<Spinner colors={{ spinner: '#0066cc', background: '#e6f3ff' }} hasBackground />
```
</details>

## Behavior

- The spinner animates continuously to indicate an active process.
- It remains visible until loading completes or the view updates.
- Remove the spinner immediately once content is ready.
- Inline spinners should not block the surrounding UI.
- Larger spinners can indicate that the user must wait before continuing.
- Use a visible label only if the loading duration is long enough to be read.
- Enable `hasBackground` when the spinner is placed on visually complex surfaces.

## Accessibility

- **Provide a descriptive label when no visible text is present** (via `label` or `aria-label`).
  [(WCAG 4.1.3 — Status Messages)](https://www.w3.org/WAI/WCAG22/Understanding/status-messages)
- **Mark content regions as busy using `aria-busy="true"`** when loading updates a specific area.
  [(WCAG 4.1.3 — Status Messages)](https://www.w3.org/WAI/WCAG22/Understanding/status-messages)
- **Ensure sufficient contrast** between the spinner, background circle, and surrounding UI. Use background circle (`hasBackground`) to enhance contrast if needed.
  [(WCAG 1.4.3 — Contrast)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum)
## API Reference

### Props

The Spinner component accepts all standard HTML `<div>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `size` | `'sm' \| 'md' \| 'lg'` | No | `'md'` | Size of the spinner |
| `variant` | `'default' \| 'highlight' \| 'default-negative' \| 'highlight-negative'` | No | `'default'` | Visual style variant |
| `hasBackground` | `boolean` | No | `false` | Whether to show background circle |
| `label` | `string` | No | — | Text label displayed below spinner |
| `colors` | `{ spinner?: string; background?: string }` | No | — | Custom color overrides |

### Type Definitions

```tsx
export const spinnerSizes = ['sm', 'md', 'lg'] as const;
export const spinnerVariants = [
  'default',
  'highlight',
  'default-negative',
  'highlight-negative',
] as const;

interface colors {
  spinner?: string;
  background?: string;
}

export type SpinnerDSProps = {
  size?: (typeof spinnerSizes)[number];
  variant?: (typeof spinnerVariants)[number];
  hasBackground?: boolean;
  label?: string;
  colors?: colors;
};

export type SpinnerProps = SpinnerDSProps & HTMLAttributes<HTMLDivElement>;
```

## Related Components

- [Button](../Button/Button.md) – Can show loading state with spinner.
- [TextInput](../TextInput/TextInput.md) – Has showLoadingIndicator prop for inline spinners.
- [ProgressBar](../ProgressBar/ProgressBar.md) – Alternative for loading states where progress is measurable.

# Switch

A Switch toggles between two mutually exclusive states (“on” / “off”) and applies the change immediately.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=285-1934)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-switch--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Switch/Switch.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

<ComponentPreview style={{ gap: 8 }}>
    <Switch id="darkmode" name="darkmode" label="Enable dark mode" defaultChecked />
</ComponentPreview>
<details open>
<summary>Code example</summary>

```tsx
import { Switch } from '@yleisradio/yds-components-react';

<Switch id="darkmode" name="darkmode" label="Enable dark mode" defaultChecked />
```
</details>

## Why to use

Switch communicates an instant, persistent state change. Use it when the user expects something to happen immediately after toggling (e.g., enable/disable a feature or visibility), and when the two states are clear opposites.

## When to use

Use a Switch when the user is toggling a binary setting and expects the change to take effect immediately.

> **Do**
> - Use when the choice is strictly binary (on / off, enabled / disabled).
> - Use when the change should apply immediately without a save or submit action.
> - Use when the control should remain visible to reflect the current state.
> - Use for preferences, feature toggles, and visibility settings.

> **Don’t**
> - Don’t use for selecting one option among many — use [RadioGroup](../Radio/Radio.md).
> - Don’t use for selecting multiple independent items — use [Checkbox](../Checkbox/Checkbox.md).
> - Don’t use when changes are applied only after form submission.
> - Don’t use for non-persistent or momentary actions.

## Content Guidelines

Switch labels must clearly describe what is enabled when the switch is on. Users should understand the outcome of toggling the switch without guessing.

> **Do**
> - Write labels as states or features (e.g., “Tumma tila”, “Sähköposti-ilmoitukset”).
> - Ensure the meaning of the on state is clear.
> - Keep labels short, concrete, and easy to scan.
> - Use helper text if the effect is complex or has consequences.
> - Use consistent wording across similar switches.

> **Don’t**
> - Don’t use vague labels (e.g., “Käytössä”, “Vaihtoehto”, “Asetus”).
> - Don’t phrase labels as actions (e.g., “Ota tumma tila käyttöön”).
> - Don’t use long explanatory sentences as labels.
> - Don’t rely on color alone to communicate the state.

## Key Props

Use the following props to customize the Switch component to your needs.

### label
Descriptive text for the setting—phrase its meaning in the ON state.

| Type | Example | Description |
|------|---------|-------------|
| `string` | <Switch id="metrics" name="metrics" label="Enable usage analytics" defaultChecked /> | Visible label describing the effect when enabled. |

<details>
<summary>Code example</summary>

```tsx
<Switch id="metrics" name="metrics" label="Enable usage analytics" defaultChecked />
```
</details>

### defaultChecked
Uncontrolled initial state.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Switch id="auto-sync" name="auto-sync" label="Auto sync" defaultChecked /> | Sets starting state to ON without manual state management. |

<details>
<summary>Code example</summary>

```tsx
<Switch id="auto-sync" name="auto-sync" label="Auto sync" defaultChecked />
```
</details>

### checked
Controlled state—must pair with `onChange`.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Switch id="beta-toggle" name="beta-toggle" label="Enable beta" checked onChange={() => {}} /> | Explicitly sets state; component is read-only without onChange. |

<details>
<summary>Code example</summary>

```tsx
const [enabled, setEnabled] = useState(false);
<Switch
  id="beta"
  name="beta"
  label="Enable beta features"
  checked={enabled}
  onChange={(e) => setEnabled(e.currentTarget.checked)}
/>
```
</details>

### isDisabled
Non-interactive, dimmed styling.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Switch id="sync" name="sync" label="Auto sync" isDisabled /> | Temporarily prevents user interaction. |

<details>
<summary>Code example</summary>

```tsx
<Switch id="sync" name="sync" label="Auto sync" isDisabled />
```
</details>

## Behavior

- Toggling the switch applies the change immediately and persistently; no submit or confirmation is required.
- The switch always reflects the current state and should never appear “unset”.
- Disabled switches remain visible but are non-interactive.
- Disabled switches remain visible but are non-interactive.
- Supports both uncontrolled (defaultChecked) and controlled (checked + onChange) usage.
- Related content that appears or disappears based on the state should be placed close to the switch.
- In complex layouts, the label may be separated or wrapped as needed without changing behavior.

## Accessibility

- Every Switch must have a visible or programmatically associated label.<br />([WCAG 3.3.2 — Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions))
- Use labels that clearly describe the effect when turned on (e.g., “Enable notifications”).<br /> ([WCAG 2.4.6 – Headings and Labels](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels))
- Keyboard: Tab/Shift+Tab moves focus; Space toggles the state; Enter also toggles in many browsers.<br />([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard))
- If helper or error text is present, link via aria-describedby so it’s announced by assistive tech.<br />([WCAG 1.3.1 — Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships))

## Implementation examples

### Accessibility naming without `label`
You may use `aria-label` / `aria-labelledby` for programmatic naming.

*[Live preview](https://design-system.yle.fi/docs/components/Switch/)*

<details>
<summary>Code example</summary>

```tsx
  <Switch id="updates2" name="updates2" label="" aria-label="Enable updates" />
  ```
</details>

## API Reference

### Props

The Switch component accepts all standard HTML `<input>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `isDisabled` | `boolean` | No | `false` | |
| `name` | `string` | Yes | — | |
| `label` | `string` | Yes | — | |
| `labelOptions` | `FormElementLabelDSProps` | No | `{}` | |

### Type Definitions

```tsx
export interface SwitchDSProps {
  isDisabled?: boolean;
  name: string;
  label: string;
  labelOptions?: FormElementLabelDSProps;
}

export type SwitchProps = InputHTMLAttributes<HTMLInputElement> & SwitchDSProps;
```

## Related Components

- [Radio](../Radio/Radio.md): Single required choice among options.
- [Checkbox](../Checkbox/Checkbox.md): Independent multi-select options.
- [TextInput](../TextInput/TextInput.md): For text entry when changes saved on submit.

# Tag

A non-interactive tag that displays a short, easily scannable keyword or status label.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=285-1945)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-tag--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/Tag/Tag.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/Tag/)*
<details open>
<summary>Code example</summary>

```tsx
  import { Tag } from '@yleisradio/yds-components-react';

  <Tag variant="live" animate>Live</Tag>
    ```
</details>

## Why to Use

A Tag provides a concise, high-visibility label that helps users quickly scan and categorize content, such as live broadcasts, opinions, or corporate items. It supports consistent visual communication across Yle services and saves space in user interfaces.

## When to Use

Use a Tag to highlight short categorical or status information that aids quick recognition: content type (Opinion), real‑time state (Live), context (Chat), or sourcing (Yle Corporate). Tags are ideal for lists, cards, alongside headings, and compact metadata areas.

> **Do**
> - Use Tags to indicate content type or category (e.g. Opinion, Chat).
> - Use Tags to communicate status or state (e.g. Live, Right now).
> - Use Tags in lists, cards, headers, and compact metadata areas.
> - Use Tags when the information is optional but helpful for scanning..

> **Don’t**
> - Don’t use Tags as interactive elements — use [TagLink](../TagLink/TagLink.md) or [Button](../Button/Button.md) instead.
> - Don’t use Tags to convey complex or critical information on their own.
> - Don’t use Tags where users are expected to make a choice or take action.
> - Don’t use Tags when the information needs to be editable..

## Content Guidelines

Tag labels must be short, scannable, and immediately understandable. Users should grasp the meaning without additional explanation.

> **Do**
> - Use short labels (ideally 1–2 words).
> - Choose the semantic variant that matches the meaning of the content.
> - Use preventTransformUppercase only when casing is meaningful (e.g. brand names).

> **Don’t**
> - Don’t manually force uppercase text — rely on the component’s default behavior.

## Key Props

Use the following props to customize the Tag component to fit your needs.

### size

Controls vertical padding and height density. `md` offers more breathing room while `sm` is compact. Defaults to `md`. The `xs` size is recommended primarily for native mobile applications (e.g. Yle Areena).

| Value | Example                           | Description                            |
| ----- | --------------------------------- | -------------------------------------- |
| `md`  | <Tag size="md" >Medium</Tag>      | Medium size with comfortable padding.  |
| `sm`  | <Tag size="sm" >Small</Tag>       | Small size with comfortable padding.   |
| `xs`  | <Tag size="xs" >Extra Small</Tag> | Extra small size with tighter padding. |

<details>
<summary>Code example</summary>

```tsx
  import { Tag } from '@yleisradio/yds-components-react';

  <Tag size="md">Medium</Tag>
  <Tag size="sm">Small</Tag>
  <Tag size="xs">Extra Small</Tag>
  ```
</details>

### variant

Visual semantic meaning controlling background & text color. Use the variant matching the content’s status or classification.

| Value          | Example                                         | Description                                                            |
| -------------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
| `default`      | <Tag variant="default" >default</Tag>           | Generic categorization. eg. 'Uusi jakso' or 'Kaikki kaudet' in Areena. |
| `neutral`      | <Tag variant="neutral" >neutral</Tag>           | Neutral or uncategorized content.                                      |
| `highlight`    | <Tag variant="highlight" >highlight</Tag>       | Highlighted metadata for custom functionality (calculators, games).    |
| `live`         | <Tag variant="live" >live</Tag>                 | Live broadcast or stream. Usually animated.                            |
| `chat`         | <Tag variant="chat" >chat</Tag>                 | Active chat or discussion feature.                                     |
| `rightnow`     | <Tag variant="rightnow" >rightnow</Tag>         | Immediate, breaking or currently happening content.                    |
| `online`       | <Tag variant="online" >online</Tag>             | Online-only or digital-specific content.                               |
| `opinion`      | <Tag variant="opinion" >opinion</Tag>           | Opinion, editorial or commentary content.                              |
| `ylecorporate` | <Tag variant="ylecorporate" >ylecorporate</Tag> | Yle corporate, brand or organizational context.                        |

<details>
<summary>Code example</summary>

```tsx
  import { Tag } from '@yleisradio/yds-components-react';

<Tag variant="default">Default</Tag>
<Tag variant="neutral">Neutral</Tag>
<Tag variant="highlight">Highlight</Tag>
<Tag variant="live">Live</Tag>
<Tag variant="chat">Chat</Tag>
<Tag variant="rightnow">Right Now</Tag>
<Tag variant="online">Online</Tag>
<Tag variant="opinion">Opinion</Tag>
<Tag variant="ylecorporate">Yle</Tag>

````
</details>

### preventTransformUppercase

By default the component applies an uppercase text transform derived from typography tokens. Set `preventTransformUppercase` to `true` to preserve original casing (e.g. for brand names or mixed case). Defaults to `false`.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Tag preventTransformUppercase >default</Tag> | Preserves original casing. |

<details>
<summary>Code example</summary>

```tsx
import { Tag } from '@yleisradio/yds-components-react';
<Tag preventTransformUppercase={false}>live</Tag>
<Tag preventTransformUppercase>Live</Tag>
````
</details>

### animate

Adds a subtle pulsing glow animation (prefers-reduced-motion respected) for the `live` variant to draw attention. Ignored for other variants. Defaults to `false`.

| Type      | Example                                   | Description                                        |
| --------- | ----------------------------------------- | -------------------------------------------------- |
| `boolean` | <Tag animate variant="live">default</Tag> | Adds a background animation to the `live` variant. |

<details>
<summary>Code example</summary>

```tsx import {Tag} from '@yleisradio/yds-components-react';
  <Tag variant="live" animate>
    Live (Animated)
  </Tag>
  ```
</details>

[See more examples in Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-tag--docs)

## Behavior

- Tags are non-interactive and purely informational.
- Tags are rendered inline and do not interrupt content flow.
- Visual styling is controlled by the selected variant.
- The live variant may use a subtle animation when animate is enabled.
- Animation respects the user’s prefers-reduced-motion setting.
- Tags do not manage state or user input.

## Implementation examples

### Example: Language preferences

*[Live preview](https://design-system.yle.fi/docs/components/Tag/)*

<details>
<summary>Code example</summary>

```tsx
  import { Tag } from '@yleisradio/yds-components-react';

  <div style={{ display: 'flex', gap: '8px' }}>
    <Tag size="md" variant="neutral">
      Suomi
    </Tag>
    <Tag size="md" variant="neutral">
      Svenska
    </Tag>
  </div>;
  ```
</details>

## API Reference

### Props

The Tag component accepts all standard HTML `<span>` attributes in addition to the following props:

| Prop                        | Type              | Required | Default     | Description     |
| --------------------------- | ----------------- | -------- | ----------- | --------------- |
| `size`                      | `TagSizeProp`     | No       | `'md'`      | Size of the tag |
| `children`                  | `React.ReactNode` | No       | —           |                 |
| `variant`                   | `TagVariantProp`  | No       | `'default'` |                 |
| `preventTransformUppercase` | `boolean`         | No       | `false`     |                 |
| `animate`                   | `boolean`         | No       | `false`     |                 |

### Type Definitions

```tsx
export type TagSizeProp = 'md' | 'sm';
export type TagVariant =
  | 'default'
  | 'neutral'
  | 'live'
  | 'chat'
  | 'rightnow'
  | 'online'
  | 'opinion'
  | 'highlight'
  | 'ylecorporate';

export type TagVariantProp = TagVariant;

export interface TagDSProps {
  size?: TagSizeProp;
  children?: React.ReactNode;
  variant?: TagVariantProp;
  preventTransformUppercase?: boolean;
  animate?: boolean;
}

export type TagProps = HTMLAttributes<HTMLSpanElement> & TagDSProps;
```

## Related Components

- [TagLink](../TagLink/TagLink.md): An interactive keyword link that provides navigational context for an article or content item
- [TagFilter](../TagFilter/TagFilter.md): Tag Filters are used to indicate selections and to allow their removal. They are typically used as a group.
- [Badge](../Badge/Badge.md): Badges are used to indicate a notification, item count, or other information relating to a navigation destination.

# TagFilter

Filter tags are used to indicate user selections and to allow their removal.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=7114-8081)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-tagfilter--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/TagFilter/TagFilter.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/TagFilter/)*
<details open>
<summary>Code example</summary>

```tsx
import { TagFilter } from '@yleisradio/yds-components-react';

<TagFilter text="Tag Filter" size="md" onClose={() => {}} />;
```
</details>

## Why to Use

TagFilter makes active filters visible and manageable. It helps users understand which filters are currently applied and gives them a clear, direct way to remove individual selections.

TagFilters improve usability in complex filtering scenarios by reducing cognitive load and increasing transparency. They are commonly used together with selection components such as Combobox, DropdownMenuGroup, or multi-select menus.

## When to Use

Use TagFilter when users need to see and remove active filters or selections.

> **Do**
> - Use to represent active filters applied via another component.
> - Use when users need to remove selections individually.
> - Use as a group to summarize multiple active filters.
> - Use in search, filtering, and content discovery flows.

> **Don’t**
> - Don’t use TagFilter for navigation — use [TagLink](../TagLink/TagLink.md) instead.
> - Don’t use TagFilter for static or informational labels — use [Tag](../Tag/Tag.md) instead.
> - Don’t use TagFilter if there is nothing the user can remove.

  ## Content Guidelines

TagFilter labels must be short, scannable, and clearly describe the selected filter.

> **Do**
> - Use short, clear labels (preferably one word).
> - Match the label exactly to the selected option (e.g. "Politiikka", "Kulttuuri").
> - Keep TagFilters visually close to the component that created them.
> - Present multiple TagFilters as a grouped set.

> **Don’t**
> - Don’t use long phrases or explanatory text.
> - Don’t allow labels to wrap to multiple lines.
> - Don’t include icons or decorative elements inside the tag.
> - Don’t mix different types of meaning (e.g. filters + status) in the same group.

## Key Props

Use the following props to customize the TagFilter component to fit your needs.

### size

Controls the component’s overall padding, height and font size mapping. Defaults to `md`.

| Value | Example                                                         | Description                                      |
| ---- | --------------------------------------------------------------- | ------------------------------------------------ |
| `md` | <TagFilter text="Medium filter" size="md" onClose={() => {}} /> | Default medium size for most use cases.          |
| `lg` | <TagFilter text="Large filter" size="lg" onClose={() => {}} />  | Large size for prominent or primary filter sets. |

<details>
<summary>Code example</summary>

```tsx
<TagFilter text="Medium filter" size="md" onClose={() => {}} />
<TagFilter text="Large filter" size="lg" onClose={() => {}} />
```
</details>

### text

Defines the visible label for the filter. Keep it short and descriptive. Long content is truncated with an ellipsis.

| Type   | Example                                                   | Description                 |
| ------ | --------------------------------------------------------- | --------------------------- |
| `string` | <TagFilter text="Culture" size="md" onClose={() => {}} /> | The displayed filter label. |

<details>
<summary>Code example</summary>

```tsx
<TagFilter text="Culture" size="md" onClose={() => {}} />
<TagFilter text="News" size="lg" onClose={() => {}} />
```
</details>

### onClose

Callback fired when the user activates the close button. Use it to remove the filter or update filtered data.

| Type      | Example                                                                               | Description                     |
| --------- | ------------------------------------------------------------------------------------- | ------------------------------- |
| `(e: MouseEvent<HTMLButtonElement>) => void` | <TagFilter text="Politics" size="md" onClose={() => console.log('Filter removed')} /> | Removal handler for the filter. |

<details>
<summary>Code example</summary>

```tsx
<TagFilter
  text="Politics"
  size="md"
  onClose={() => console.log('Filter removed')}
/>
```
</details>

### closeText

Accessible label for the close button, read by assistive technologies. Defaults to `Poista valinta` (Finnish for “Remove selection”). Localize as needed.

| Type        | Example                                                                                 | Description                            |
| ----------- | --------------------------------------------------------------------------------------- | -------------------------------------- |
| `string` | <TagFilter text="Environment" size="md" onClose={() => {}} closeText="Remove filter" /> | Overrides the close button aria-label. |

<details>
<summary>Code example</summary>

```tsx
<TagFilter
  text="Environment"
  size="md"
  onClose={() => {}}
  closeText="Remove Environment"
/>
```
</details>

## Behavior

- TagFilter displays a selected filter with a close (remove) action.
- Activating the close button removes the filter and updates the filtered result.
- Each TagFilter operates independently.
- TagFilters are typically controlled by application state.
- The component does not manage filtering logic itself — it only represents selection state.

## Accessibility

- Close button is a native `button` with an `aria-label` for screen readers (from `closeText`).
- Customize closeText for each FilterTag to provide context (e.g. "Remove Politics").

<details>
<summary>Code example</summary>

```tsx
<TagFilter
  id="politics"
  text="Politics"
  size="md"
  onClose={() => {}}
  closeText="Remove Politics"
/>
```
</details>

## Implementation examples

### Adding and removing tag filters

Tag Filters can be controlled by application state by setting the onClose to remove themselves from the list.

*[Live preview](https://design-system.yle.fi/docs/components/TagFilter/)*

[See more examples in Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-tagfilter--docs)

## API Reference

### Props

The TagFilter component accepts all standard HTML `<div>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `size` | `'md' \| 'lg'` | Yes | — | |
| `onClose` | `(e: MouseEvent<HTMLButtonElement>) => void` | Yes | — | |
| `text` | `string` | Yes | — | |
| `closeText` | `string` | No | `'Poista valinta'` | |

### Type Definitions

```tsx
export type TagFilterDSProps = {
  size: 'md' | 'lg';
  onClose: (e: MouseEvent<HTMLButtonElement>) => void;
  text: string;
  closeText?: string;
};

export type TagFilterProps = HTMLAttributes<HTMLDivElement> & TagFilterDSProps;
```

## Related Components

- [ComboboxSingleSelect](../ComboboxSingleSelect/ComboboxSingleSelect.md) – For selecting from large sets or searching filters.
- [DropdownMenuGroup](../DropdownMenuGroup/DropdownMenuGroup.md) – For grouped or hierarchical filter selections.
- [Tag](../Tag/Tag.md) – Non-interactive labels providing content context.
- [TagLink](../TagLink/TagLink.md) – Interactive keyword link for navigation.

# TagLink

An interactive keyword link that provides navigational context for an article or content item.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=252-181)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-taglink--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/TagLink/TagLink.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/TagLink/)*
<details open>
<summary>Code example</summary>

```tsx
import { TagLink } from '@yleisradio/yds-components-react';

<TagLink href="#" variant="primary">Strömsö</TagLink>
```
</details>

## Why to Use

TagLink provides a lightweight, scannable way to connect content to related topics, brands, campaigns, or themes. It supports content discovery by helping users explore related material without interrupting their reading flow. TagLinks are commonly used near headlines or at the end of articles to surface contextual navigation.

## When to Use

Use TagLink when you need a clickable keyword or label that navigates the user to a related page or collection.

> **Do**
> - Use when a keyword should lead to a topic, brand, campaign, or themed collection.
> - Use beside article headlines to highlight the primary topic or brand.
> - Use at the end of articles to link to related topics.
> - Use when navigation is the primary purpose of the label.

> **Don’t**
> - Don’t use TagLink for triggering actions — use [Button](../Button/Button.md) instead.
> - Don’t use TagLink for purely informational labels — use [Tag](../Tag/Tag.md) instead.
> - Don’t use when the destination is unclear or ambiguous.

## Content Guidelines

TagLink labels must be short, clear, and meaningful on their own. Users should immediately understand what kind of content they will navigate to.

> **Do**
> - Keep text short and scannable (ideally 1–2 words).
> - Use proper nouns or established topic names (e.g. Strömsö, Culture, Nature).
> - Place TagLinks close to the content they describe.
> - Use consistent terminology across similar content.

> **Don’t**
> - Don’t use long phrases or explanatory text.
> - Don’t include icons or images inside TagLinks.
> - Don’t allow TagLinks to wrap to multiple lines unnecessarily.
> - Don’t rely on visual styling alone to explain meaning.

## Key Props

Use the following props to customize the TagLink component to fit your needs.

### variant

Controls the visual semantic meaning (background & text color). Pick the variant that matches the context or classification.

| Value | Example | Typical usage |
|---------|---------|---------------|
| `primary` | <TagLink href="#" variant="primary">Strömsö</TagLink> | Highlighted topical or editorial category; used beside headlines for campaigns, brands, or trending topics (e.g. Strömsö, MOT, Nenäpäivä). |
| `secondary` | <TagLink href="#" variant="secondary">Culture</TagLink> | Used at the end of an article for related keyword link groups (e.g. Culture, Nature). |
| `text` | <TagLink href="#" variant="text">Nature</TagLink> |  Inline keyword link beside a headline; lightweight visual style for subtle emphasis. |

<details>
<summary>Code example</summary>

```tsx
<TagLink href="#" variant="primary">Strömsö</TagLink>
<TagLink href="#" variant="secondary">Culture</TagLink>
<TagLink href="#" variant="text">Nature</TagLink>
```
</details>

### removePadding

Removes the internal horizontal & vertical padding when used with the `text` variant for tight inline placement near headings. Ignored for other variants (they keep their pill shape). To keep alignment with other rows, place to the beginning of a row of text.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <TagLink href="#" variant="text" removePadding>Topic</TagLink> | Eliminates padding for inline text variant. |

<details>
<summary>Code example</summary>

```tsx
<TagLink href="#" variant="text">Topic</TagLink>
<TagLink href="#" variant="text" removePadding>Topic</TagLink>
```
</details>

### Non-Interactive Fallback

If you omit both `href` and `onClick`, TagLink renders a visually styled `<span>` (`TagLinkBaseNonInteractive`). Prefer using the separate `Tag` component for semantic non-interactive labels, but this fallback supports layout scenarios where a link may conditionally exist.

```tsx
// Renders as <span>
<TagLink variant="primary">Conditional Label</TagLink>

// Renders as <a>
<TagLink href="#" variant="primary">Strömsö</TagLink>
```

[See more examples in Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-taglink--docs)

## Behavior
- TagLink behaves like a standard link.
- Activating a TagLink navigates the user to a related page or view.
- Variants affect visual emphasis, not behavior.
- When href or onClick is missing, TagLink renders as a non-interactive `span` for layout fallback.
- Padding can be removed in text variant for tight inline alignment near headings.

## Accessibility

TagLinks behave like standard hyperlinks:
- Use `aria-label` if the visible keyword needs additional context.
- Keep text concise to minimize cognitive load.
- Avoid setting `numberOfLines` > 1 unless truncation is required for extremely long keyword phrases.

## API Reference

### Props

The TagLink component accepts all standard HTML `<a>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `TagLinkVariant` | No | `'primary'` | |
| `children` | `React.ReactNode` | No | — | |
| `removePadding` | `boolean` | No | `false` | |
| `numberOfLines` | `number` | No | `1` | |

### Type Definitions

```tsx
export type TagLinkVariant = 'primary' | 'secondary' | 'text';

export interface TagLinkDSProps {
  variant?: TagLinkVariant;
  children?: React.ReactNode;
  removePadding?: boolean;
  numberOfLines?: number;
}

export type TagLinkProps = AnchorHTMLAttributes<HTMLAnchorElement> & TagLinkDSProps;
```

## Related Components

- [Tag](../Tag/Tag.md): Non-interactive keyword or status label.
- [TagFilter](../TagFilter/TagFilter.md): Used to indicate selected filters and allow removal (typically in groups).
- [Badge](../Badge/Badge.md): Displays notifications, counts, or related numeric indicators.

# TextArea

A TextArea is a multi-line input field used for longer, free‑form responses that span multiple lines, such as descriptions, messages or feedback.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=252-177)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-textarea--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/TextArea/TextArea.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/TextArea/)*
<details open>
<summary>Code example</summary>

```tsx
import { Textarea } from '@yleisradio/yds-components-react';

<Textarea
  id="basic"
  label="Message"
  placeholder="Type here..."
  rows={4}
/>
```
</details>

## Why to use

TextArea enables users to write longer, open-ended content that does not fit into a single line. It supports helper text, character limits, and validation feedback, helping users understand expectations and compose content confidently within given constraints. Use TextArea whenever users need space to explain, describe, or elaborate.

## When to use

Use TextArea when users need to provide multi-line or open-ended text that may span several sentences or paragraphs.

> **Do**
> - Use TextArea for long-form or expressive input (e.g., descriptions, feedback, messages).
> - Use it when users need space to explain or elaborate.
> - Use it in forms, support flows, reporting tools, and writing tasks.
> - Use it when input length varies or is hard to predict.

> **Don’t**
> - Don’t use TextArea for short, single-line input — use [TextInput](../TextInput/TextInput.md).
> - Don’t use it for selecting predefined options — use [Select](../Select/Select.md), [Radio](../Radio/Radio.md), or [Checkbox](../Checkbox/Checkbox.md).
> - Don’t use it when rich text formatting is required — use a rich text editor.
> - Don’t use it when only a short identifier or value is needed.

## Content Guidelines

TextArea content should guide users without overwhelming them. Labels, descriptions, and error messages must support open-ended writing while staying concise and scannable.

> **Do**
> - Use short, clear labels (e.g., “Kuvaus”, “Viesti”, “Palaute”).
> - Provide helpful descriptions to set expectations (esim. “Kuvaile ongelmaa mahdollisimman tarkasti”).
> - Use placeholder text for examples, not instructions (e.g., “Kaikki alkoi siitä…”)
> - Explain character limits and show a counter when used.
> - Write actionable error messages (e.g., “Kirjoita vähintään 50 merkkiä”).
> - Keep guidance brief and scannable.

> **Don’t**
> - Don’t duplicate the label in the description.
> - Don’t use vague wording like “Kirjoita jotain”.
> - Don’t rely on placeholder text as the only guidance.
> - Don’t use generic errors like “Virheellinen syöte”.
> - Don’t include filler like “Huomioithan että…”.
> - Don’t include long, dense instructional paragraphs.

## Anatomy

![TextArea anatomy](../../img/text-area-anatomy.svg)

1. **Label** – Describes the purpose of the field.
2. **Placeholder** – Example or hint text inside the area.
3. **Input field** – Multi-line area where users enter text.
4. **Description** – Additional guidance or context below the field.
5. **Character counter** – Displays the number of typed and remaining characters.
6. **Optional field indicator** – Shows that the field is not required to fill.

## Key Props

Use the following props to configure the Textarea component.

### rows
Sets the initial visible height (in text rows). Content beyond this height becomes scrollable.

| Type | Example | Description |
|------|---------|-------------|
| `number` | <Textarea id="rows-demo" label="Comments" rows={3} placeholder="Type your message..." /> | Controls initial vertical size of the field. |

<details>
<summary>Code example</summary>

```tsx
<Textarea
  id="rows-demo"
  label="Comments"
  rows={3}
  placeholder="Type your message..."
/>
```
</details>

### label

> **Warning**
> Label can be visually hidden but must remain readable for screen readers.

| Type | Example | Description |
|------|---------|-------------|
| `string` | <Textarea id="bio" label="Bio"/> | Provides a clear purpose for the field. |

<details>
<summary>Code example</summary>

```tsx
<Textarea
  id="bio"
  label="Bio"
/>
```
</details>

### description
Helper guidance placed below the field.

| Type | Example | Description |
|------|---------|-------------|
| `string` | <Textarea id="bio" label="Bio" description="Tell us about yourself" placeholder="I like carrots..." /> | Clarifies purpose, format, or constraints. |

<details>
<summary>Code example</summary>

```tsx
<Textarea
  id="bio"
  label="Bio"
  description="Tell us about yourself"
  placeholder="I like carrots..."
/>
```
</details>

### success
Provide feedback after user action or async validation.

| Type | Example | Description |
|-------|---------|-------------|
| `boolean` | <Textarea id="s1" label="Feedback" defaultValue="All set" success /> | Indicates successful validation. |

<details>
<summary>Code example</summary>

```tsx
  <Textarea
    id="s1"
    label="Feedback"
    defaultValue="All set"
    success
  />
  ```
</details>

### errorMessage
Provide feedback after user action or async validation.

| Type | Example | Description |
|-------|---------|-------------|
| `string` | <Textarea id="e1" label="Feedback" defaultValue="Too short" errorMessage="Text should be at least 50 characters" /> | Displays a validation error below the field. Sets `aria-invalid`. |

<details>
<summary>Code example</summary>

```tsx
  <Textarea
    id="e1"
    label="Feedback"
    defaultValue="Too short"
    errorMessage="Text should be at least 50 characters"
  />
```
</details>

### isDisabled
Makes the field non‑interactive and visually dimmed.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` | <Textarea id="dis" label="Summary" value="Confirmed text" isDisabled description="Confirmed value cannot be edited" /> | Temporarily prevents user interaction. |

<details>
<summary>Code example</summary>

```tsx
<Textarea id="dis" label="Summary" value="Confirmed text" isDisabled description="Confirmed value cannot be edited" />
```
</details>

### characterLimit
Restricts input length and shows a live character counter (current / limit). Prevents exceeding the limit via `maxLength`.

| Type | Example | Description |
|------|---------|-------------|
| `number` | <Textarea id="limit" label="Bio" characterLimit={140} description="Max 140 characters." /> | Enforces and displays remaining capacity. |

<details>
<summary>Code example</summary>

```tsx
<Textarea id="limit" label="Bio" characterLimit={140} description="Max 140 characters." />
```
</details>

## Behavior

- Default height is controlled via rows; the area becomes scrollable when content exceeds the visible space.
- The label appears above the field; helper text is read immediately after the label.
- Error messages explain how to fix the issue.
- Validation feedback appears as error or success states with color and text.
- Disabled state blocks input and dims visuals.
- On mobile, the component should be full-width.
- Match the default height and width to the expected content length (do not oversize).

## Accessibility

- Every TextArea must have a visible or programmatically associated label.
- Provide meaningful helper text for constraints ([WCAG 3.3.2 — Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions)).
- Ensure full keyboard accessibility — users should be able to navigate using `Tab`, `Shift+Tab`, and activate controls with `Enter`.<br /> ([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard)).

## Implementation examples

### Describe your problem

How to use placeholder, description and optional label in TextArea.

*[Live preview](https://design-system.yle.fi/docs/components/TextArea/)*
<details open>
<summary>Code example</summary>

```tsx
<Textarea
  id="opt-ex"
  label="Describe your problem"
  description="Provide as much detail as possible."
  labelOptions={{ optionalLabel: '(Optional)' }}
  rows={3}
  placeholder="It all started, when..."
/>
```
</details>

### With error

Error state provides a clear indication that went wrong and error message tells how to fix it.

*[Live preview](https://design-system.yle.fi/docs/components/TextArea/)*
<details open>
<summary>Code example</summary>

```tsx
<Textarea
  id="err-ex"
  label="Describe your problem"
  labelOptions={{ optionalLabel: '(Optional)' }}
  defaultValue="It all started, when..."
  errorMessage="Please provide more detail"
  rows={3}
/>
```
</details>

### Character limit

*[Live preview](https://design-system.yle.fi/docs/components/TextArea/)*

## API Reference

### Props

The Textarea component accepts all standard HTML `<textarea>` attributes in addition to the following props:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | Yes | — | |
| `labelOptions` | `FormElementLabelDSProps` | No | `{}` | |
| `id` | `string` | Yes | — | |
| `value` | `string` | Yes | — | |
| `onChange` | `(e: React.ChangeEvent<HTMLTextAreaElement>) => void` | Yes | — | |
| `placeholder` | `string` | No | — | |
| `rows` | `number` | No | — | |
| `description` | `string` | No | — | |
| `errorMessage` | `string` | No | — | |
| `success` | `boolean` | No | `false` | |
| `isDisabled` | `boolean` | No | `false` | |
| `characterLimit` | `number` | No | — | |

### Type Definitions

```tsx
export interface TextareaDSProps {
  label: string;
  labelOptions?: FormElementLabelDSProps;
  id: string;
  value: string;
  onChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
  placeholder?: string;
  rows?: number;
  description?: string;
  errorMessage?: string;
  success?: boolean;
  isDisabled?: boolean;
  characterLimit?: number;
}

export type TextareaProps = React.TextareaHTMLAttributes<HTMLTextAreaElement> & TextareaDSProps;
```

## Related Components

- [TextInput](../TextInput/TextInput.md): For single-line responses.
- [SearchInput](../SearchInput/SearchInput.md): For search functionality.
- [Select](../Select/Select.md): For single-select dropdowns.
- [ComboboxSingleSelect](../ComboboxSingleSelect/ComboboxSingleSelect.md): For searchable single-select dropdowns.

# TextInput

A TextInput is a single-line field that allows users to enter short, structured information such as names, email addresses or titles.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=252-2)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-textinput--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/TextInput/TextInput.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/TextInput/)*
<details open>
<summary>Code example</summary>

```tsx
  import { TextInput } from '@yleisradio/yds-components-react';

{' '}
<TextInput label="Label" placeholder="Placeholder" />

````
</details>

## Why to use

TextInput allows users to enter short, structured information quickly and accurately. It supports validation, helper text, and clear feedback, helping users understand what is expected and complete tasks efficiently. Use TextInput whenever a concise textual value is required as part of a form, dialog, or inline interaction.

## When to use

Use TextInput when users need to enter short, single-line information that benefits from clarity, validation, or guidance.

> **Do**
> - Use TextInput for short, single-line input (e.g., “Etunimi”, “Sähköposti”).
> - Use it when input follows clear rules or formats.
> - Use it in forms, dialogs, inline edits, and search fields.
> - Use it when the value fits naturally on one line and should be easy to scan.

> **Don’t**
> - Don’t use TextInput for multi-line input — use [TextArea](../TextArea/TextArea.md).
> - Don’t use it for choosing from predefined options — use [Select](../Select/Select.md) or [ComboboxSingleSelect](../ComboboxSingleSelect/ComboboxSingleSelect.md).
> - Don’t use it for long or unstructured free-form text.
> - Don’t use it when input purpose is unclear or hidden.

## Content Guidelines

TextInput content should clearly communicate what information is required and how to provide it, without unnecessary cognitive effort.

> **Do**
> - Use short, descriptive labels (e.g., “Sähköposti”, “Otsikko”).
> - Use placeholder text only as an example, not as instructions.
> - Add concise helper text for extra context (esim. “3–16 merkkiä”).
> - Write specific error messages that explain how to fix the problem. (e.g.,“Syötä voimassa oleva sähköpostiosoite”).
> - Keep terminology and phrasing consistent across similar fields.

> **Don’t**
> - Don’t use placeholder text instead of a label.
> - Don’t repeat the label text inside the placeholder.
> - Don’t use vague or generic labels (e.g., “Teksti”, “Arvo”).
> - Don’t include long explanations in labels or descriptions.
> - Don’t rely on placeholder text alone — it disappears when typing starts.

## Anatomy
![TextInput anatomy](../../img/text-input-anatomy.svg)

1. **Label** – Describes the purpose of the field.
2. **Start icon** – Decorative or contextual symbol.
3. **Description** – Provides additional guidance below the field.
4. **Placeholder** – Example or hint text inside the field.
5. **Input field** – Area where users enter text.
6. **End icon** – Decorative or functional symbol, e.g., visibility toggle.
7. **Optional field indicator** – Shows that the field is not required to fill.

## Key Props

Use the following props to customize the TextInput component to fit your needs.

### type
Supported HTML input types. Invalid values fall back to `text`.

| Value |  Example |Description |
|------|-------------|---------|
| `text` | <TextInput size="50" label="Username" id="username" placeholder="Enter username" /> | Generic free-form text. |
| `email` | <TextInput size="50" label="Email" id="email" type="email" placeholder="name@example.com" /> | Email address pattern (may trigger native validation/UI). |
| `password` | <TextInput size="50" label="Password" id="pwd" type="password" /> | Obscures characters for secrets. |
| `number` | <TextInput size="50" label="Age" id="age" type="number" /> | Numeric value (spinner / numeric keyboard). |
| `tel` | <TextInput size="50" label="Phone" id="phone" type="tel" /> | Telephone number (phone keypad on mobile). |
| `search` | <TextInput size="50" label="Search" id="search" type="search" placeholder="Search" /> | Search field styling (enables native clear in some browsers). |

<details>
<summary>Code example</summary>

```tsx
<TextInput label="Email" id="email" type="email" placeholder="name@example.com" />
<TextInput label="Password" id="pwd" type="password" />
<TextInput label="Search" id="search" type="search" placeholder="Search" />
````
</details>

### label

> **Warning**
> Label can be visually hidden but must remain readable for screen readers.

| Type     | Example                                          | Description                             |
| -------- | ------------------------------------------------ | --------------------------------------- |
| `string` | <TextInput size="50" label="Username" id="u"  /> | Provides a clear purpose for the field. |

<details>
<summary>Code example</summary>

```tsx
  <TextInput label="Username" id="username" />
  ```
</details>

### description

Helper guidance placed below the field.

| Type     | Example                                                                       | Description                                   |
| -------- | ----------------------------------------------------------------------------- | --------------------------------------------- |
| `string` | <TextInput size="50" label="Username" id="u" description="3–16 characters" /> | Provides additional guidance below the field. |

<details>
<summary>Code example</summary>

```tsx
  <TextInput
    label="Username"
    id="username"
    description="3–16 characters"
    placeholder="Enter username"
  />
  ```
</details>

### success

| Type      | Example                                                            | Description                      |
| --------- | ------------------------------------------------------------------ | -------------------------------- |
| `boolean` | <TextInput size="50" label="Email" id="e2" type="email" success /> | Indicates successful validation. |

<details>
<summary>Code example</summary>

```tsx
  <TextInput label="Email" id="email-input" type="email" success />
  ```
</details>

### errorMessage

| Type     | Example                                                                                 | Description                                                       |
| -------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `string` | <TextInput size="50"  label="Email" id="e" type="email" errorMessage="Invalid email" /> | Displays a validation error below the field. Sets `aria-invalid`. |

<details>
<summary>Code example</summary>

```tsx
  <TextInput label="Email" id="email-error" type="email" errorMessage="Invalid email" />
  ```
</details>

### isDisabled

Non-interactive, dimmed styling.

| Type      | Example                                                                       | Description                            |
| --------- | ----------------------------------------------------------------------------- | -------------------------------------- |
| `boolean` | <TextInput size="50" label="Disabled input" id="disabled-input" isDisabled /> | Temporarily prevents user interaction. |

<details>
<summary>Code example</summary>

```tsx
  <TextInput label="Disabled input" id="disabled-input" isDisabled />
  ```
</details>

### isRequired

| Type      | Example                                                         | Description                           |
| --------- | --------------------------------------------------------------- | ------------------------------------- |
| `boolean` | <TextInput size="50" label="First name" id="name" isRequired /> | Marks field mandatory for submission. |

<details>
<summary>Code example</summary>

```tsx
  <TextInput label="First name" id="name" isRequired />
  ```
</details>

### showLoadingIndicator

Shows a spinner inside the input (left side) while async work occurs (e.g. validating, fetching suggestions).

| Type      | Example                                                                                           | Description                          |
| --------- | ------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `boolean` | <TextInput size="50" label="Search" id="search-loading" showLoadingIndicator value="Searching" /> | Renders spinner and adjusts padding. |

<details>
<summary>Code example</summary>

```tsx
  <TextInput label="Search" id="search-loading" showLoadingIndicator value="Searching" />
  ```
</details>

### Icons

Decorative or actionable icons. Provide meaningful `ariaLabel` for interactive ones.

| Props        | Example                                                                                                                                 | Description                           |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `iconBefore` | <TextInput label="Search" id="s1" iconBefore={{ componentFn: Search, ariaLabel: 'Search icon' }} />                                     | Static or clickable icon before text. |
| `icon`       | <TextInput label="Password" id="pwd1" type="password" icon={{ componentFn: Eye, ariaLabel: 'Toggle visibility', onClick: () => {} }} /> | Static or clickable icon after text.  |

<details>
<summary>Code example</summary>

```tsx
import { Eye, Search } from '@yleisradio/yds-icons-react';

<TextInput
  label="Search"
  id="search-x"
  type="search"
  iconBefore={{ componentFn: Search, ariaLabel: 'Search icon' }}
/>

<TextInput
  label="Password"
  id="pwd"
  type="password"
  icon={{ componentFn: Eye, ariaLabel: 'Toggle password visibility', onClick: () => {} }}
/>
```
</details>

### unit

An optional unit string displayed right-aligned and bold inside the input box (e.g. `%`, `€`, `vuotta`). Intended for numeric inputs where the unit is a fixed contextual label. The unit is linked to the input via `aria-describedby` so screen readers announce it when the input is focused.

| Type     | Example                                                                                              | Description                                             |
| -------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `string` | <TextInput size="50" label="Maksuaika" id="unit-ex" type="number" defaultValue="20" unit="vuotta" /> | Displays a unit after the typed value inside the field. |

<details>
<summary>Code example</summary>

```tsx
  <TextInput label="Maksuaika" id="maksuaika" type="number" unit="vuotta" />
  <TextInput label="Lainan määrä" id="laina" type="number" unit="€" />
  <TextInput label="Viitekorko" id="korko" type="number" unit="%" />
  ```
</details>

> **Warning**
> - The `unit` prop is not designed to be combined with `icon`, `iconClear`, or `submitButton`. It can coexist with `iconBefore` and `showLoadingIndicator`.
> - Use short, static strings. The unit takes its natural width and pushes the input to the left.

### autocomplete

Pass through native browser autocomplete hint (e.g. `email`, `username`, `current-password`).

| Prop           | Example                                                                     | Description                                                    |
| -------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `autocomplete` | <TextInput label="Email" id="email-ac" type="email" autocomplete="email" /> | Helps browsers suggest stored values / show suitable keyboard. |

<details>
<summary>Code example</summary>

```tsx
  <TextInput label="Email" id="email-ac" type="email" autocomplete="email" />
  ```
</details>

See [MDN Autocomplete attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) for all possible values.

## Behavior

- The label is always associated with the input and appears above it.
- The input shows a visible focus state when focused.
- Validation feedback is shown using success or error states.
- Error messages appear below the input and describe how to resolve the issue.
- Disabled inputs remain visible but cannot be edited.
- Placeholder text disappears once the user starts typing.
- Icons may be decorative or interactive; interactive icons must be operable and accessible.
- After the `iconClear` button is clicked, TextInput returns focus to the input unless the click handler moved focus elsewhere. TextInput holds no state for this.
- Set `iconClear.props.hidden` to hide the clear button while keeping it in the DOM (for example via [`createClearIcon`](#createclearicon)).
- Supports both controlled and uncontrolled usage.

## Accessibility

- Every TextInput must have a visible or programmatically associated label.
- Interactive icons (such as password visibility toggles) must include a descriptive `aria-label`.<br /> ([WCAG 3.3.2 — Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions))
- Ensure full keyboard accessibility — users should be able to navigate using `Tab`, `Shift+Tab`, and activate controls with `Enter`.<br /> ([WCAG 2.1.1 — Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard))

## Implementation examples

### Phone number

How to use placeholder, description and optional label in TextInput.

*[Live preview](https://design-system.yle.fi/docs/components/TextInput/)*
<details open>
<summary>Code example</summary>

```tsx
  import { TextInput } from '@yleisradio/yds-components-react';
  <TextInput label="Phone number" labelOptions={{ optionalLabel: '(Optional)' }} placeholder="+358" description="Enter phone number in international format" type="tel" />

````
</details>

### With error

Error state provides a clear indication that went wrong and error message tells how to fix it.

*[Live preview](https://design-system.yle.fi/docs/components/TextInput/)*
<details open>
<summary>Code example</summary>

```tsx
import { TextInput } from '@yleisradio/yds-components-react';
<TextInput label="Email" value="Invalid value" type="email" errorMessage="Please enter a valid email address" />

````
</details>

### createClearIcon

Helper that returns a standard clear `InputIconProps` (`CloseSmall`, default aria-label `Tyhjennä`). Pass `value` to set `props.hidden` when the value is an empty string. Pass `onClear` for controlled clearing, or omit it to clear the native input and fire a bubbling `input` event (works for uncontrolled forms).

```tsx
import { TextInput, createClearIcon } from '@yleisradio/yds-components-react';

<TextInput
  label="Search"
  value={query}
  onChange={(e) => setQuery(e.currentTarget.value)}
  iconClear={createClearIcon({ value: query, onClear: () => setQuery('') })}
/>;
```

| Option      | Type         | Default    | Description                                           |
| ----------- | ------------ | ---------- | ----------------------------------------------------- |
| `ariaLabel` | `string`     | `Tyhjennä` | Accessible name for the clear button.                 |
| `value`     | `string`     | —          | When `''`, sets `props.hidden`. Omit to always show.  |
| `onClear`   | `() => void` | —          | Custom clear logic; omit for native input clear.      |

## API Reference

### Props

The TextInput component accepts all standard HTML `<input>` attributes in addition to the following props:

| Prop                   | Type                                                               | Required | Default  | Description                                                                                                      |
| ---------------------- | ------------------------------------------------------------------ | -------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `label`                | `string`                                                           | Yes      | —        |                                                                                                                  |
| `labelOptions`         | `FormElementLabelProps`                                            | No       | `{}`     |                                                                                                                  |
| `id`                   | `string`                                                           | No       | —        |                                                                                                                  |
| `value`                | `string`                                                           | No       | —        |                                                                                                                  |
| `onChange`             | `React.ChangeEventHandler<HTMLInputElement>`                       | No       | —        |                                                                                                                  |
| `placeholder`          | `string`                                                           | No       | —        |                                                                                                                  |
| `description`          | `string`                                                           | No       | —        |                                                                                                                  |
| `errorMessage`         | `string`                                                           | No       | —        |                                                                                                                  |
| `autocomplete`         | `string`                                                           | No       | —        |                                                                                                                  |
| `type`                 | `'text' \| 'email' \| 'password' \| 'number' \| 'tel' \| 'search'` | No       | `'text'` |                                                                                                                  |
| `success`              | `boolean`                                                          | No       | `false`  |                                                                                                                  |
| `isRequired`           | `boolean`                                                          | No       | `false`  |                                                                                                                  |
| `isDisabled`           | `boolean`                                                          | No       | `false`  |                                                                                                                  |
| `children`             | `ReactNode`                                                        | No       | —        |                                                                                                                  |
| `icon`                 | `InputIconProps`                                                   | No       | —        |                                                                                                                  |
| `submitButton`         | `ReactNode`                                                        | No       | —        |                                                                                                                  |
| `iconBefore`           | `InputIconProps`                                                   | No       | —        |                                                                                                                  |
| `iconClear`            | `InputIconProps`                                                   | No       | —        | Clear button. Use `props.hidden` to hide; focus returns after click.                                             |
| `showLoadingIndicator` | `boolean`                                                          | No       | `false`  |                                                                                                                  |
| `unit`                 | `string`                                                           | No       | —        | Unit label displayed right-aligned inside the field (e.g. `%`, `€`, `vuotta`). Announced via `aria-describedby`. |

### Type Definitions

```tsx
export type InputIconProps = {
  componentFn: (props: SVGProps<SVGSVGElement>) => JSX.Element;
  ariaLabel: string;
  onClick?: () => void;
  props?: ButtonHTMLAttributes<HTMLButtonElement>;
};

export type TextInputDSProps = {
  label: string;
  labelOptions?: FormElementLabelProps;
  id?: string;
  value?: string;
  onChange?: React.ChangeEventHandler<HTMLInputElement>;
  placeholder?: string;
  description?: string;
  errorMessage?: string;
  autocomplete?: string;
  type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'search';
  success?: boolean;
  isRequired?: boolean;
  isDisabled?: boolean;
  children?: ReactNode;
  icon?: InputIconProps;
  submitButton?: ReactNode;
  iconBefore?: InputIconProps;
  iconClear?: InputIconProps;
  showLoadingIndicator?: boolean;
  unit?: string;
};

export type TextInputProps = InputHTMLAttributes<HTMLInputElement> & TextInputDSProps;
```

## Related Components

- [TextArea](../TextArea/TextArea.md): For multi-line responses.
- [SearchInput](../SearchInput/SearchInput.md): For search functionality.
- [Select](../Select/Select.md): For single-select dropdowns.
- [ComboboxSingleSelect](../ComboboxSingleSelect/ComboboxSingleSelect.md): For searchable single-select dropdowns.
- [Slider](../Slider/Slider.md): For picking a numeric value from a bounded range by dragging.

# Toast Notification

A Toast Notification is a short-lived, floating message that appears above the content to confirm an action or display a temporary system status before dismissing automatically.

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=8113-1253)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/components-toastnotification--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/ToastNotification/ToastNotification.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

*[Live preview](https://design-system.yle.fi/docs/components/ToastNotification/)*

<details open>
<summary>Code example</summary>

```tsx
const toast = useToast();
toast({ level: 'success', duration: 3000, children: 'This is a toast notification' })}
```
</details>

## Why to use

Toast Notifications provide lightweight, unobtrusive feedback for brief, non-critical events. They confirm that an action has occurred without interrupting the user’s flow or requiring acknowledgment.

## When to use

Use a Toast Notification to communicate short-lived, non-critical feedback that does not require user action and should not block interaction.

> **Do**
> - Use Toasts for quick confirmations or acknowledgements (e.g., “Tallennettu”, “Kopioitu”, “Päivitetty”).
> - Use them for transient system events that users should notice but not focus on (e.g., “Yhteys palautettu”).
> - Use Toasts when the message can safely disappear without user interaction.

> **Don’t**
> - Don’t use Toasts for critical, blocking, or persistent information.
> - Don’t use Toasts when the user must read, understand, or act on the message.
> - Don’t use Toasts for validation errors or field-specific feedback.
> - Don’t use Toasts as a replacement for [Notifications](../Notification/Notification.md) or [BannerNotifications](../BannerNotification/BannerNotification.md).

### Differences between Notification Types

| Type | Purpose | Placement | Use case |
|------|---------|-----------|----------|
| **Banner Notification**| A notification covering the entire view or service (e.g., maintenance, error state).| Fixed, below the header. | “Maintenance in progress” |
| **Inline Notification** | A local notification within content or a form (e.g., field error). | Embedded in content. | “This field is required” |
| **Toast Notification** | A short-lived, automatically disappearing feedback message (e.g., save confirmation). | Floating near the bottom of the screen, sliding in and out smoothly. | “Saved successfully” |

## Content Guidelines

Toast content must be immediately understandable at a glance, as messages are displayed briefly and overlay the UI.

> **Do**
> - Keep messages to one short sentence or a few words.
> - Focus on the outcome, not the process (e.g., “Lähetetty”, “Kopioitu leikepöydälle”).
> - Use clear, neutral language.
> - Keep wording consistent for repeated events.
> - Use icons only to reinforce meaning, not to explain it.

> **Don’t**
> - Don’t include instructions, explanations, or multiple ideas.
> - Don’t combine multiple updates.
> - Don’t use vague phrasing (e.g., “Jotain tapahtui”).
> - Don’t add filler language or politeness.
> - Don’t rely on the toast alone to convey critical information.

## Anatomy

![TextArea anatomy](../../img/toast-notification-anatomy.svg)

1. **Icon** – Icon indicating the message level (info, success, warning, error).
2. **Body** – Main message content.
3. **Action** – Main action guiding the user’s next step.

## Key ToastNotification Props

Toasts are triggered with the `toast` function from `useToast()`. Pass a props object matching `ToastNotificationProps`.

### level
Sets semantic and visual styling (icon + colors).

| Value | Example | Description |
|-------|---------|-------------|
| `info` | <Toast level="info">General information</Toast>| Neutral informational context. |
| `success` | <Toast level="success">Changes saved</Toast> | Positive confirmation. |
| `warning` | <Toast level="warning">Unstable connection</Toast> | Caution, needs attention soon. |
| `error` | <Toast level="error">Upload failed</Toast> | Critical or blocking issue. |

<details>
<summary>Code example</summary>

```tsx
toast({ level: 'info', children: 'General information' });
toast({ level: 'success', children: 'Changes saved' });
toast({ level: 'warning', children: 'Unstable connection' });
toast({ level: 'error', children: 'Upload failed' });
```
</details>

### children (message)
Main textual content. Keep it short (typically one sentence).

| Type | Example | Description |
|------|---------|-------------|
| `ReactNode` | <Toast level="success">Profile updated</Toast> | Message body displayed inside toast. |

<details>
<summary>Code example</summary>

```tsx
toast({ level: 'success', children: 'Profile updated' });
```
</details>

### icon
Override default icon for a given level.

| Type | Example | Description |
|------|---------|-------------|
| `ReactNode` | <Toast level="info" icon={<Star />}>Favorited</Toast> | Replaces semantic default icon. |

<details>
<summary>Code example</summary>

```tsx
import { Star } from '@yleisradio/yds-icons-react';
toast({ level: 'info', icon: <Star />, children: 'Favorited' });
```
</details>

### hideIcon
Suppress level icon.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` |  <Toast level="info" hideIcon>Plain text toast</Toast> | Removes icon for minimal style. |

<details>
<summary>Code example</summary>

```tsx
toast({ level: 'info', hideIcon: true, children: 'Plain text toast' });
```
</details>

### hideCloseButton
Omits manual close button. When `hideCloseButton` is true and no `duration` is given, a default auto-dismiss of 3000ms is applied.

| Type | Example | Description |
|------|---------|-------------|
| `boolean` |  <Toast level="info" hideCloseButton>Saved successfully</Toast> | Auto-dismiss only; no manual close. |

<details>
<summary>Code example</summary>

```tsx
// Auto dismiss after default 3000ms
toast({ level: 'success', hideCloseButton: true, children: 'Saved successfully' });
```
</details>

### duration
Total visible time (ms). If provided AND `hideCloseButton` is false, a timer bar is shown. If `hideCloseButton` is true, duration overrides the default 3000ms but no timer bar appears.

| Type | Example | Description |
|------|---------|-------------|
| `number` |  <Toast level="info" duration="5000">Will hide after 5s</Toast> | Time before auto-dismiss. |

<details>
<summary>Code example</summary>

```tsx
// With timer bar (close button visible)
toast({ level: 'info', duration: 5000, children: 'Will hide after 5s' });

// Without close button (no timer bar)
toast({ level: 'info', hideCloseButton: true, duration: 6000, children: 'Auto hides after 6s' });
```
</details>

### closeText
Custom text label for the close button if no `closeIcon` is supplied. Defaults to "Sulje".

| Type | Example | Description |
|------|---------|-------------|
| `string` |  <Toast level="info" closeText="Dismiss">Message sent</Toast> | Localized close label. |

<details>
<summary>Code example</summary>

```tsx
toast({ level: 'info', closeText: 'Dismiss', children: 'Message sent' });
```
</details>

## Behavior

- Toasts appear floating above content, typically near the bottom of the viewport.
- They dismiss automatically after a short duration.
- Toasts do not take focus or interrupt the user’s ongoing task.
- A close button may be provided when the message needs more time to read.
- When a timer bar is shown, it reflects the remaining visible time; clicking the toast removes the timer and keeps it visible until manually closed.
- Each toast conveys one concise message, with an optional icon and Close button.
- Repeated toasts should not overwhelm the user or stack excessively.
- Critical or persistent information should be surfaced elsewhere (e.g. inline notification, banner, or message log).

## Animation behavior

- Toast notification appears from the bottom of viewport.
- Duration timer decreases from right to left.

| Action | Duration | Easing |
|--------|----------|--------|
| Appear | `m` / `250ms` |  `dec` / `cubic-bezier(0.17, 0.84, 0.44, 1)` |
| Timer bar | `duration` (default: 3000 ms) | `lin` / `linear` |
| Exit | `m` / `250ms` |  `dec` / `cubic-bezier(0.17, 0.84, 0.44, 1)` |

## Accessibility

- Uses a live region to be announced by assistive tech: `aria-live="polite"`.
- Ensures sufficient color contrast per WCAG 2.1 – 1.4.3 (AA) and avoids color-only meaning (1.3.1).
- Visible focus and full keyboard operability for the Close control (2.1.1 Keyboard, 2.4.7 Focus Visible).
- Shows long enough to read (at least 3 s); provide a Close control and/or a way to pause auto-dismiss when necessary (2.2.2 Pause, Stop, Hide).
- Critical information is also available elsewhere (e.g., inline error) so the message is not lost (4.1.3 Status Messages).

## Implementation examples

### Basic toast (manual close)
<div style={{ marginBottom: 16, width: '100%', justifyContent: 'center', border: '1px solid #eee', padding: 24 }}>
  <Toast level="success" buttonText="Show success toast">Changes saved</Toast>
</div>

<details open>
<summary>Code example</summary>

```tsx
const TriggerBasicToastInline = () => {
  const toast = useToast();
  return (
    <Button
      text="Show success toast"
      onClick={() => toast({ level: 'success', children: 'Changes saved' })}
    />
  );
};

<ToastProvider>
  <TriggerBasicToastInline />
  <ToastNotifications />
</ToastProvider>
```
</details>

### Auto dismiss (no close button)
<div style={{ marginBottom: 16, width: '100%', justifyContent: 'center', border: '1px solid #eee', padding: 24 }}>
  <Toast level="info" hideIcon hideCloseButton buttonText="Show auto toast">Copied to clipboard</Toast>
</div>

<details open>
<summary>Code example</summary>

```tsx
const TriggerAutoDismissToast = () => {
  const toast = useToast();
  return (
    <Button
      text="Show auto toast"
      onClick={() => toast({ level: 'info', hideIcon: true, hideCloseButton: true, children: 'Copied to clipboard' })}
    />
  );
};

<ToastProvider>
  <TriggerAutoDismissToast />
  <ToastNotifications />
</ToastProvider>
```
</details>

### With timer bar (duration + close)
<div style={{ marginBottom: 16, width: '100%', justifyContent: 'center', border: '1px solid #eee', padding: 24 }}>

  <Toast level="warning" duration="5000" buttonText="Show timed toast">Network unstable</Toast>

</div>

<details open>
<summary>Code example</summary>

```tsx
const TriggerTimedToast = () => {
  const toast = useToast();
  return (
    <Button
      text="Show timed toast"
      onClick={() => toast({ level: 'warning', duration: 5000, children: 'Network unstable' })}
    />
  );
};

<ToastProvider>
  <TriggerTimedToast />
  <ToastNotifications />
</ToastProvider>
```
</details>

## API Reference

### Props

The ToastNotification component accepts the following props when using the `toast` function from `useToast()`:

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `icon` | `ReactNode` | No | — | |
| `level` | `NotificationLevel` | Yes | — | |
| `duration` | `number` | No | — | |
| `hideCloseButton` | `boolean` | No | — | |
| `children` | `ReactNode` | No | — | |
| `hideIcon` | `boolean` | No | — | |

### Type Definitions

```tsx
export type NotificationLevel = 'info' | 'success' | 'warning' | 'error';

export type ToastNotificationProps = {
  icon?: ReactNode;
  level: NotificationLevel;
  duration?: number;
  hideCloseButton?: boolean;
  children?: ReactNode;
  hideIcon?: boolean;
};
```

## Related Components

- [Notification](../Notification/Notification.md) – Inline contextual messages that persist until state changes.
- [BannerNotification](../BannerNotification/BannerNotification.md) – Page/service-wide announcements below the header.

# YdsThemeProvider

`YdsThemeProvider` applies YDS color and shadow tokens as CSS custom properties to **a subtree**. It injects a `<style>` tag next to `children` and renders a wrapper `div` (`display: contents`) that carries the tokens. It never changes the document theme unless you ask it to.

Theming the whole document is CSS's job: [import the token files onto `:root`](../../using-yds/development/get-started-with-v3.md#3-put-tokens-on-root). Reach for the provider when a *section* needs a different theme, or when a theme has to change in React.

<Resources
  storybookUrl="https://ds-storybook.test.yle.fi/?path=/docs/design-tokens-custom-theme-components--docs"
  githubUrl="https://github.com/Yleisradio/yle-design-system/blob/main/docs/components/YdsThemeProvider/YdsThemeProvider.mdx"
/>

<details open>
<summary>Code example</summary>

```tsx
import { YdsThemeProvider, Button } from '@yleisradio/yds-components-react';

<YdsThemeProvider theme="dark">
  <Button text="Dark-themed button" />
</YdsThemeProvider>
```
</details>

## Breaking changes: version 3.0

Upgrading `YdsThemeProvider` from 2.x. Package-wide list: [Breaking changes in React package 3.0](../../using-yds/development/breaking-changes-in-v3.md).

| 2.x | 3.0 |
|---|---|
| Tokens via styled-components context (`theme.yds.*`) | CSS custom properties (`var(--yds-color-*)`) injected as a `<style>` tag |
| `theme` defaulted to `'light'` | `theme` defaults to `'default'` (follows `prefers-color-scheme`). Pass `theme="light"` to force light theme |
| `unit` and `baseUnit` converted font sizes at runtime | Props removed. Component CSS uses `rem` with a `1rem = 16px` baseline. Convert in the app with PostCSS (`postcss-rem-to-pixel`, `postcss-pxtorem`) if needed |
| Tokens reached every descendant through React context, including portals | Tokens are inherited through the DOM. The provider themes its own subtree, not the document. Use `render` to choose the element, or `scope` to target a selector |
| Required around the app for YDS components to have a theme | Optional, and no longer the recommended way to theme a document. Import token CSS onto `:root` and keep the provider for sections and React-driven switching |
| YDS theme tokens, such as `theme.yds.BACKGROUND` can be used in styled-components inside YdsThemeProvider | You need to provide JS theme from yds-core on app side or migrate to css custom properties (`var(--yds-color-background)`) |

`styled-components` is no longer a peer dependency of `@yleisradio/yds-components-react`. If the app keeps it, see [Using styled-components with YDS 3.0](../../using-yds/development/styled-components-to-css.md).

## Why to use

YDS components read colors from CSS custom properties (`var(--yds-color-*)`). Those variables are inherited, so they must exist on a DOM ancestor of every component.

`YdsThemeProvider` writes those variables for one subtree. Use it when you need to:

- Apply a different theme to a section — a dark sidebar on a light page, a branded widget — without touching the host page's CSS.
- Switch a theme in React (`light`, `dark`, `default`, or a custom `Theme` object) in response to state.
- Pass a theme generated by `@yleisradio/yds-theme-custom`.

You do **not** need it for the document theme.

## Document theming is CSS \{#document-theming-is-css\}

Import token CSS onto `:root` once — no provider, no extra DOM node, no runtime `<style>` tag. File lists and wrappers: [Get started](../../using-yds/development/get-started-with-v3.md#3-put-tokens-on-root).

This provider is the alternative when a **subtree** needs a different theme, the theme must change in React, or you pass a custom `Theme` object. `scope=":root"` exists as a migration step — see [below](#migrating-a-whole-app-provider).

## Theming a section

Wrap the section. The provider renders a `div` with `display: contents`, so it carries tokens without producing a box of its own.

```tsx
import { YdsThemeProvider, Button } from '@yleisradio/yds-components-react';

<YdsThemeProvider theme="dark">
  <Button text="Dark-themed button" />
</YdsThemeProvider>;
```

If you already render an element there, pass it as `render` and skip the extra node. The theme class is merged with the element's own `className`:

```tsx
<YdsThemeProvider theme="dark" render={<aside className="sidebar" />}>
  <Navigation />
</YdsThemeProvider>
```

`theme` defaults to `'default'`, which follows `prefers-color-scheme`. Use `'light'` or `'dark'` to force a palette.

Sibling providers are independent, so two themes can sit side by side on the same page without either winning.

## When to use

> **Do**
> - Use `YdsThemeProvider` for a section that needs a different theme (a dark sidebar, a custom-branded widget).
> - Use it when the theme has to change in React — a user toggle, a per-page override.
> - Use it for custom themes from `@yleisradio/yds-theme-custom` for a brand-specific palette.
> - Use `render` when you already have an element at that spot, so the theme class lands on it instead of on an extra `div`.

> **Don't**
> - Don't use it as the document theme. Import the token CSS onto `:root` instead — [Get started](../../using-yds/development/get-started-with-v3.md#3-put-tokens-on-root).
> - Don't wrap every individual component in its own provider.
> - Don't hardcode raw colors inside components instead of theme tokens.

## Migrating a whole-app provider

In 2.x, tokens flowed through React context, so a provider around the app reached everything. Tokens are now inherited through the DOM, and the provider only themes its own subtree.

**Preferred:** drop the root provider and [import the token CSS onto `:root`](#document-theming-is-css). Keep providers only where a section or a toggle needs one.

**Transitional:** if you cannot change the app's CSS setup yet, `scope=":root"` restores the old reach. It renders nothing and writes the tokens straight to the document.

```tsx
<YdsThemeProvider theme="dark" scope=":root">
  <App />
</YdsThemeProvider>
```

Treat this as a migration step, not a destination. It puts a runtime `<style>` in the body, it pins the document theme for anything else on the page, and only one provider on a page can sensibly own `:root`.

## Key YdsThemeProvider Props

### theme

Specifies the theme to apply.

| Value / Type | Description |
|---|---|
| `'light'` | Standard light theme. |
| `'dark'` | Standard dark theme. |
| `'default'` | Light tokens, plus dark tokens inside `prefers-color-scheme: dark`. This is the default. |
| `Theme` object | Custom palette. Obtain one from `customTheme()` in `@yleisradio/yds-theme-custom`. |

<details>
<summary>Code example</summary>

```tsx
import { YdsThemeProvider } from '@yleisradio/yds-components-react';
import customTheme from '@yleisradio/yds-theme-custom';
import { color } from '@yleisradio/yds-core';

<YdsThemeProvider theme="light"> ... </YdsThemeProvider>
<YdsThemeProvider theme="dark"> ... </YdsThemeProvider>
<YdsThemeProvider theme="default"> ... </YdsThemeProvider>

const theme = customTheme(color.GRAY_95, color.NEWS_VIOLET_30);
<YdsThemeProvider theme={theme}> ... </YdsThemeProvider>
```
</details>

### render

Element that receives the theme class instead of the default wrapper `div`. Its own `className` is kept, and `children` come from the provider.

Use it whenever the subtree already starts with an element of yours — one node instead of two, and the element keeps its own layout rather than the wrapper's `display: contents`.

<details>
<summary>Code example</summary>

```tsx
<YdsThemeProvider theme="dark" render={<aside className="sidebar" />}>
  <Navigation />
</YdsThemeProvider>

{/* Renders <aside class="sidebar yds-theme-dark"> */}
```
</details>

### scope

CSS selector to apply tokens to. Nothing is rendered around `children`, so the selector has to match an element you already own.

Use it for elements outside the provider's reach: `':root'` or `'body'` for a document theme, or a class on markup React does not render.

`scope` and `render` are mutually exclusive — the selector decides where tokens land, so there is nothing left for `render` to do.

<details>
<summary>Code example</summary>

```tsx
<YdsThemeProvider theme="dark" scope=".sidebar">
  {/* Put className="sidebar" on your own element */}
</YdsThemeProvider>

<YdsThemeProvider theme="dark" scope=":root">
  <App />
</YdsThemeProvider>
```
</details>

## Nesting providers

Each provider targets its own class, so an inner one overrides the outer theme for its subtree. Nesting needs no extra props.

<details>
<summary>Code example</summary>

```tsx
<YdsThemeProvider theme="light">
  <MainContent />

  <YdsThemeProvider theme="dark">
    <DarkSidebar />
  </YdsThemeProvider>
</YdsThemeProvider>
```
</details>

YDS overlays (`Modal`, `Dialog`, `BottomSheet`) use the native `<dialog>` element and stay where they are in the DOM, so they inherit the theme of the provider they sit inside. Content you portal elsewhere yourself does not. Read `useThemeContext().className` and put it on the portal container:

<details>
<summary>Code example</summary>

```tsx
import { useThemeContext } from '@yleisradio/yds-components-react';

const { className } = useThemeContext() ?? {};

createPortal(<div className={className}>{content}</div>, document.body);
```
</details>

## Custom themes with yds-theme-custom

Use `@yleisradio/yds-theme-custom` to generate a `Theme` object from any background and highlight color pair, then pass it to `YdsThemeProvider`. The palette stays on the widget, so it is safe on a host page that already has tokens.

```tsx
import { YdsThemeProvider } from '@yleisradio/yds-components-react';
import customTheme from '@yleisradio/yds-theme-custom';
import { color } from '@yleisradio/yds-core';

function PlusDeskiWidget() {
  const theme = customTheme(color.GRAY_95, color.NEWS_VIOLET_30);

  return (
    <YdsThemeProvider theme={theme}>
      {/* All YDS components here use the custom theme */}
    </YdsThemeProvider>
  );
}
```

For guaranteed WCAG compliance regardless of input colors, use `generateAccessibleCustomTheme` instead:

```tsx
import { generateAccessibleCustomTheme } from '@yleisradio/yds-theme-custom';
import { color } from '@yleisradio/yds-core';

const theme = generateAccessibleCustomTheme(color.GRAY_95, color.NEWS_VIOLET_30);
```

See the [`@yleisradio/yds-theme-custom` README](https://github.com/Yleisradio/yle-design-system/blob/main/packages/yds-theme-custom/README.md) for the full API.

## Light and dark custom themes

`customTheme()` accepts a `themeType` argument (`'light'`, `'dark'`, or `'auto'`). Generate two theme variants and switch between them — for example by responding to a user toggle, an OS preference, or a page-level configuration.

### React approach

```tsx
import { YdsThemeProvider } from '@yleisradio/yds-components-react';
import customTheme from '@yleisradio/yds-theme-custom';
import { color } from '@yleisradio/yds-core';

const lightTheme = customTheme(color.WHITE, color.NEWS_VIOLET_50, {}, 'light');
const darkTheme = customTheme(color.GRAY_95, color.NEWS_VIOLET_30, {}, 'dark');

function Widget({ prefersDark }: { prefersDark: boolean }) {
  return (
    <YdsThemeProvider theme={prefersDark ? darkTheme : lightTheme}>
      {/* Components respond to the active theme */}
    </YdsThemeProvider>
  );
}
```

### CSS approach (class-based or prefers-color-scheme)

When you are not inside a React tree, or when you need static CSS, generate **two** custom themes — one forced light, one forced dark — and emit both onto a selector you own.

Pass `'light'` / `'dark'` as `themeType` so each palette uses the matching contrast rules (light background + dark text vs dark background + light text), even if the raw colors would auto-detect the other way.

```tsx
import { themeToCss } from '@yleisradio/yds-components-react';
import customTheme from '@yleisradio/yds-theme-custom';
import { color } from '@yleisradio/yds-core';

const lightCustom = customTheme(color.WHITE, color.NEWS_VIOLET_50, {}, 'light');
const darkCustom = customTheme(color.GRAY_95, color.NEWS_VIOLET_30, {}, 'dark');
```

**Follow the OS** with `prefers-color-scheme`. Light is the default; dark overrides it when the user prefers dark:

```tsx
const css = `
  ${themeToCss('.my-widget', lightCustom)}

  @media (prefers-color-scheme: dark) {
    ${themeToCss('.my-widget', darkCustom)}
  }
`;
```

```html
<div class="my-widget">…</div>
```

**Follow a class** when the app (or the user) toggles theme independently of the OS. Keep the light rule as the default, then override with a dark class on the same node or an ancestor:

```tsx
const css = `
  ${themeToCss('.my-widget', lightCustom)}
  ${themeToCss('.my-widget.theme-dark', darkCustom)}
  ${themeToCss('.theme-dark .my-widget', darkCustom)}
`;
```

```html
<div class="my-widget">Light custom palette</div>
<div class="my-widget theme-dark">Dark custom palette</div>
```

`themeToCss` with a `Theme` object emits color variables only. Shadow and spacing tokens still come from the document token CSS (or from `'light'` / `'dark'` presets, which include shadows).

A single custom theme is the same helper without a media query or dark class:

```tsx
const css = themeToCss('.my-widget', darkCustom);
```

Or import the **preset** class-scoped files and put `yds-theme-dark` on a **descendant of `html`** (not on `<html>` itself — `:root` is `html`, so `:root .yds-theme-dark` would not match):

```css
@import '@yleisradio/yds-core/tokens/build/css/_theme-dark.css';
@import '@yleisradio/yds-core/tokens/build/css/_shadow-dark.css';
```

```html
<body class="yds-theme-dark">...</body>
```

### Outputting only changed tokens

When embedding a custom theme inside a page that already sets most base tokens, emit only the variables that differ. Pass `{ onlyChanged: true }` to `themeToCssFragment`:

```ts
import customTheme, { themeToCssFragment } from '@yleisradio/yds-theme-custom';
import { color } from '@yleisradio/yds-core';

const theme = customTheme(color.GRAY_95, color.NEWS_VIOLET_30, {}, 'dark');

const cssFragment = themeToCssFragment(theme, { onlyChanged: true, themeType: 'dark' });
```

This is useful for a lightweight embed (quiz, score widget) on a page that already loads the full YDS dark theme.

| Option | Type | Default | Description |
|---|---|---|---|
| `onlyChanged` | `boolean` | `false` | When `true`, omit tokens whose value matches the base theme. |
| `themeType` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Which base theme to diff against. Ignored when `baseTheme` is provided. |
| `baseTheme` | `Theme` | — | Explicit base theme object to diff against. |

## Behavior

- Every provider injects a `<style>` tag next to `children` and applies the tokens to a class: `yds-theme-light`, `yds-theme-dark`, `yds-theme-default`, or a generated `yds-theme-custom-*` for a `Theme` object. `scope` replaces that class with your selector.
- The default wrapper uses `display: contents`, so it produces no box. Flex and grid children inside it still lay out normally, but child selectors on the parent (`.parent > .item`, `:nth-child`) see the wrapper as the single child. Pass `render` when that matters.
- The innermost provider's variables win for DOM descendants of its element.
- Invalid custom theme objects from `yds-theme-custom` fall back to the dark base theme.

## Accessibility

- Theme tokens are tested for WCAG AA contrast ratios by default. Custom themes generated by `customTheme()` follow the accessibility rules described in [CUSTOM_THEME_GUIDELINES.md](https://github.com/Yleisradio/yle-design-system/blob/main/packages/yds-theme-custom/CUSTOM_THEME_GUIDELINES.md).
- For guaranteed WCAG compliance, use `generateAccessibleCustomTheme()` which adjusts colors automatically if needed.
- When writing only changed tokens via `onlyChanged: true`, ensure the base page theme already provides accessible contrast for the tokens you are not overriding.

## API Reference

### Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `theme` | `'light' \| 'dark' \| 'default' \| Theme` | No | `'default'` | Theme to apply to the subtree. |
| `render` | `ReactElement` | No | — | Element that receives the theme class instead of the default wrapper `div`. Not allowed with `scope`. |
| `scope` | `string` | No | — | CSS selector to apply tokens to, such as `':root'`. Renders nothing. Not allowed with `render`. |
| `children` | `ReactNode` | Yes | — | Content to render with the theme. |

### Type Definitions

```tsx
import type { Theme } from '@yleisradio/yds-core';
import type { ReactElement, ReactNode } from 'react';

type YdsThemeProviderProps = {
  theme?: 'light' | 'dark' | 'default' | Theme;
  children: ReactNode;
} & (
  | { render?: ReactElement; scope?: never }
  | { scope: string; render?: never }
);
```

### useThemeContext

Returns the nearest provider's scope, or `null` outside one. Use `className` to theme an element the provider cannot reach itself.

```tsx
interface ThemeScope {
  selector: string;
  theme: 'light' | 'dark' | 'default' | Theme;
  className: string | undefined;
}
```

## Related

- [Get started with yds-components-react 3.0](../../using-yds/development/get-started-with-v3.md) — Token CSS on `:root`.
- [Design Tokens — Theming](../../design-tokens/index.md) — Overview of the token system.

import {
  Accordion,
  AccordionItem,
  ActionMenu,
  Badge,
  BannerNotification,
  Button,
  ButtonGroup,
  BottomSheet,
  Checkbox,
  ChoiceBox,
  ChoiceButton,
  Dialog,
  DropdownMenu,
  DropdownMenuGroup,
  Link,
  LiveSearchInput,
  MenuItem,
  NavigationTab,
  NavigationTabList,
  Notification,
  PageIndicator,
  PageIndicatorContainer,
  ProgressBar,
  Radio,
  SearchInput,
  SearchSubmitButton,
  SectionTab,
  SectionTabList,
  SectionTabPanel,
  SectionTabs,
  Select,
  Slider,
  Spinner,
  Switch,
  Tag,
  TagFilter,
  TagLink,
  Textarea,
  TextInput,
} from '@yleisradio/yds-components-react';

import { ComponentPreviewCard } from 'yds-documentation/src/components/Card/Card';
import { GridContainer } from 'yds-documentation/src/components/GridContainer/GridContainer';

# Components

YDS provides UI components for web and mobile use.

## Form controls

Components for data entry, selection, and supporting form structures.

<GridContainer>
  <ComponentPreviewCard
    tags={['React', 'React Native']}
    title="Checkbox"
    href="/docs/components/Checkbox/"
    description="Lets users select one or more options."
    component={<Checkbox label="Checkbox" />}
  />
  <ComponentPreviewCard
    tags={['React']}
    title="ChoiceBox"
    href="/docs/components/ChoiceBox/"
    description="Checkbox wrapped in a card for answer selection."
    component={<ChoiceBox name="cb-1" label="ChoiceBox" />}
  />
  <ComponentPreviewCard
    tags={['React']}
    title="ChoiceButton"
    href="/docs/components/ChoiceButton/"
    description="Radio button wrapped in a card for answers."
    component={<ChoiceButton name="cbtn-1" label="ChoiceButton" />}
  />
  <ComponentPreviewCard
    tags={['React', 'React Native']}
    title="Radio"
    href="/docs/components/Radio/"
    description="Lets users select one option from a set."
    component={<Radio label="Radio" />}
  />
  <ComponentPreviewCard
    tags={['React']}
    title="Select"
    href="/docs/components/Select/"
    description="Predefined list for single selection in forms."
    component={
      <Select
        id="sel-1"
        name="sel1"
        label="Select"
        items={[
          { label: 'A', value: 'a' },
          { label: 'B', value: 'b' },
        ]}
        onChange={() => {}}
      />
    }
  />
  <ComponentPreviewCard
    tags={['React']}
    title="Slider"
    href="/docs/components/Slider/"
    description="Lets users pick a numeric value from a range."
    component={<Slider label="Slider" min={0} max={100} defaultValue={40} showValueBox={false} />}
  />
  <ComponentPreviewCard
    tags={['React', 'React Native']}
    title="TextArea"
    href="/docs/components/TextArea/"
    description="Multi-line input for longer free-form responses."
    component={<Textarea id="ta-1" label="Textarea" rows={2} />}
  />
  <ComponentPreviewCard
    tags={['React', 'React Native']}
    title="TextInput"
    href="/docs/components/TextInput/"
    description="Single-line field for short structured information."
    component={<TextInput label="TextInput" />}
  />
</GridContainer>

## Navigation

Components for moving through content, switching views, and finding destinations.

<GridContainer>
  <ComponentPreviewCard
    tags={['React']}
    title="LiveSearchInput"
    href="/docs/components/LiveSearchInput/"
    description="Filters results in real-time as the user types."
    component={
      <LiveSearchInput id="s1" label="LiveSearchInput" name="q" labelOptions={{ isHidden: true }} />
    }
  />
  <ComponentPreviewCard
    tags={['React']}
    title="NavigationTabs"
    href="/docs/components/NavigationTabs/"
    description="Switches between pages or top-level views."
    component={
      <NavigationTabList style={{ height: 48 }}>
        <NavigationTab id="t1" selected>
          Tab 1
        </NavigationTab>
        <NavigationTab id="t2">Tab 2</NavigationTab>
      </NavigationTabList>
    }
  />
  <ComponentPreviewCard
    tags={['React']}
    title="SearchInput"
    href="/docs/components/SearchInput/"
    description="Lets users find content by entering keywords."
    component={
      <SearchInput
        id="s1"
        label="SearchInput"
        name="q"
        submitButton={<SearchSubmitButton aria-label="Search" />}
      />
    }
  />
  <ComponentPreviewCard
    tags={['React']}
    title="SectionTabs"
    href="/docs/components/SectionTabs/"
    description="Switches between content sections within the same page."
    component={
      <SectionTabs>
        <SectionTabList>
          <SectionTab index={0}>1</SectionTab>
          <SectionTab index={1}>2</SectionTab>
        </SectionTabList>
        <SectionTabPanel index={0}>...</SectionTabPanel>
        <SectionTabPanel index={1}>...</SectionTabPanel>
      </SectionTabs>
    }
  />
  <ComponentPreviewCard
    tags={['React']}
    title="Link"
    href="/docs/components/Link/"
    description="Styled anchor with optional external link icon."
    component={<Link href="#">Link</Link>}
  />
</GridContainer>

## Indicators & Metadata

Components for displaying status, categorisation, and supporting information in the interface.

<GridContainer>
  <ComponentPreviewCard
    tags={['React']}
    title="PageIndicator"
    href="/docs/components/PageIndicator/"
    description="Dot-style indicators for current position in a set."
    component={
      <PageIndicatorContainer>
        <PageIndicator isActive aria-label="1" />
        <PageIndicator aria-label="2" />
        <PageIndicator aria-label="3" />
      </PageIndicatorContainer>
    }
  />
  <ComponentPreviewCard
    tags={['React', 'React Native']}
    title="Tag"
    href="/docs/components/Tag/"
    description="Displays a short keyword or status label."
    component={<Tag>Tag</Tag>}
  />
  <ComponentPreviewCard
    tags={['React', 'React Native']}
    title="TagLink"
    href="/docs/components/TagLink/"
    description="Interactive keyword link for navigational context."
    component={<TagLink href="#">TagLink</TagLink>}
  />
</GridContainer>

## Feedback & Status

Components for communicating feedback, notifications, and system status to the user.

<GridContainer>
  <ComponentPreviewCard
    tags={['React']}
    title="Badge"
    href="/docs/components/Badge/"
    description="Indicates notifications, item counts, or contextual information."
    component={
      <Badge variant="primary" size="xl">
        3
      </Badge>
    }
  />
  <ComponentPreviewCard
    tags={['React']}
    title="BannerNotification"
    href="/docs/components/BannerNotification/"
    description="Displays important temporary messages affecting the entire view."
    previewStyle={{ flexDirection: 'column', alignItems: 'stretch' }}
    component={<BannerNotification level="warning" title="BannerNotification" />}
  />
  <ComponentPreviewCard
    tags={['React', 'React Native']}
    title="Notification"
    href="/docs/components/Notification/"
    description="Highlights success, warning, error, or info messages."
    previewStyle={{ flexDirection: 'column', alignItems: 'stretch' }}
    component={<Notification level="info" variant="primary" title="Notification" />}
  />
  <ComponentPreviewCard
    tags={['React', 'React Native']}
    title="ProgressBar"
    href="/docs/components/ProgressBar/"
    description="Indicates task completion in determinate and indeterminate states."
    component={<ProgressBar value={60} />}
  />
  <ComponentPreviewCard
    tags={['React', 'React Native']}
    title="Spinner"
    href="/docs/components/Spinner/"
    description="Indicates an ongoing process while content loads."
    component={<Spinner />}
  />
  <ComponentPreviewCard
    tags={['React']}
    title="TagFilter"
    href="/docs/components/TagFilter/"
    description="Indicates active filters and allows their removal."
    component={<TagFilter text="TagFilter" size="md" onClose={() => {}} />}
  />
  <ComponentPreviewCard
    tags={['React']}
    title="ToastNotification"
    href="/docs/components/ToastNotification/"
    description="Short-lived floating message confirming an action."
  />
</GridContainer>

## Buttons & Actions

Components for triggering actions and making choices.

<GridContainer>
  <ComponentPreviewCard
    tags={['React']}
    title="ActionMenu"
    href="/docs/components/ActionMenu/"
    description="Button that opens a dropdown list of actions."
    previewStyle={{ flexDirection: 'column', alignItems: 'stretch' }}
    component={
      <ActionMenu text="ActionMenu" id="am-1" menuId="m-1">
        <MenuItem onSelect={() => {}}>A</MenuItem>
      </ActionMenu>
    }
  />
  <ComponentPreviewCard
    tags={['React', 'React Native']}
    title="Button"
    href="/docs/components/Button/"
    description="Triggers an action or confirms a choice."
    component={<Button text="Button" />}
  />
  <ComponentPreviewCard
    tags={['React']}
    title="ButtonGroup"
    href="/docs/components/ButtonGroup/"
    description="Groups buttons for selections, filters, or view toggles."
    component={
      <ButtonGroup>
        <ButtonGroup.Button id="bg-1">A</ButtonGroup.Button>
        <ButtonGroup.Button id="bg-2">B</ButtonGroup.Button>
      </ButtonGroup>
    }
  />
  <ComponentPreviewCard
    tags={['React']}
    title="DropdownMenu"
    href="/docs/components/DropdownMenu/"
    description="Selects a value from a list immediately."
    component={
      <DropdownMenu
        id="dm-1"
        menuId="dmenu-1"
        placeholder="DropdownMenu"
        options={[
          { text: 'A', value: 'a' },
          { text: 'B', value: 'b' },
        ]}
        value={undefined}
        onChange={() => {}}
      />
    }
  />
  <ComponentPreviewCard
    tags={['React']}
    title="DropdownMenuGroup"
    href="/docs/components/DropdownMenuGroup/"
    description="Groups multiple dropdown menus into one control area."
    component={
      <DropdownMenuGroup>
        <DropdownMenuGroup.DropdownMenu
          id="dmg-1"
          options={[
            { text: 'A', value: 'a' },
            { text: 'B', value: 'b' },
          ]}
          value={undefined}
          onChange={() => {}}
        >
          <span>1</span>
        </DropdownMenuGroup.DropdownMenu>
        <DropdownMenuGroup.DropdownMenu
          id="dmg-2"
          options={[
            { text: 'A', value: 'a' },
            { text: 'B', value: 'b' },
          ]}
          value={undefined}
          onChange={() => {}}
        >
          <span>2</span>
        </DropdownMenuGroup.DropdownMenu>
      </DropdownMenuGroup>
    }
  />
  <ComponentPreviewCard
    tags={['React']}
    title="Menu"
    href="/docs/components/Menu/"
    description="Positioned dropdown with keyboard navigation and focus management."
    component={
      <>
        <MenuItem onSelect={() => {}}>Menu item</MenuItem>
        <MenuItem onSelect={() => {}}>Menu item</MenuItem>
        <MenuItem onSelect={() => {}}>Menu item</MenuItem>
      </>
    }
  />
  <ComponentPreviewCard
    tags={['React']}
    title="Switch"
    href="/docs/components/Switch/"
    description="Toggles between two states, applied immediately."
    component={<Switch id="sw-1" name="sw-1" />}
  />
</GridContainer>

## Content display

Components for presenting, structuring, and highlighting content.

<GridContainer>
  <ComponentPreviewCard
    tags={['React', 'React Native']}
    title="Accordion"
    href="/docs/components/Accordion/"
    description="Hides and reveals sections of related content."
    previewStyle={{ flexDirection: 'column', alignItems: 'stretch' }}
    component={
      <Accordion>
        <AccordionItem title="Accordion">...</AccordionItem>
      </Accordion>
    }
  />
  <ComponentPreviewCard
    tags={['React']}
    title="BottomSheet"
    href="/docs/components/BottomSheet/"
    description="Panel that slides up from the bottom."
  />
  <ComponentPreviewCard
    tags={['React']}
    title="Dialog"
    href="/docs/components/Dialog/"
    description="Consistent layout for content inside Modal or BottomSheet."
  />
  <ComponentPreviewCard
    tags={['React']}
    title="Modal"
    href="/docs/components/Modal/"
    description="Centered overlay that blocks interaction until dismissed."
  />
</GridContainer>

## For installation and quickstart

- [Get started with yds-components-react 3.0](/docs/using-yds/development/get-started-with-v3)

---

# Patterns

# Patterns

A pattern describes how to solve a recurring user need across Yle's services: what to do, why, and how to build it with YDS components, tokens and content. Patterns capture design decisions that otherwise live only in designers' heads, and write them down so that designers, developers and AI agents apply them the same way.

## Patterns, principles and components

- **Design principles** describe how YDS designs in general, for example how motion guides and expresses. They apply everywhere and don't prescribe a solution.
- **Patterns** solve one recurring need, such as confirming a destructive action or showing an empty state. They often combine several components with content and behaviour across a flow.
- **Components** are the building blocks a pattern uses. A component page explains one element; a pattern explains how elements work together.

## What a pattern page contains

Every pattern follows the same structure, so it is quick to scan and easy for agents to apply:

- **Problem:** the situation and the user's need.
- **When to use, and when not to:** the conditions, with alternatives.
- **Rules:** the decisions, written as explicit *must*, *should* and *must not* statements.
- **Solution:** how the pattern works, with the YDS components and tokens it uses.
- **Behaviour and states:** loading, empty, error and success states, and responsive behaviour.
- **Content guidelines:** wording, with examples in Finnish where relevant.
- **Accessibility:** focus, keyboard and screen reader behaviour.
- **Examples:** live examples and services where the pattern is used.
- **Rationale:** why this is the shared solution.

## Available patterns

The first patterns are being defined. They will be listed here as they are published.

---

# Design Tokens

# Border Radius

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=88-1532)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/design-tokens-border-radius--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/design-tokens/border-radius.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

Border radius tokens for consistent corner rounding across components. Token values contain corresponding unit (px) except for `none`.

| CSS / JS     | Token  | Value   | Description                                                  |
| ----------- | ------ | ------- | ------------------------------------------------------------ |
| `--yds-border-radius-none`<br>`radius.NONE` | none   | `0`     | No rounding; sharp corners                                   |
| `--yds-border-radius-small`<br>`radius.SMALL` | small  | `2px`   | NavigationTab indicator; TagLink text variant                |
| `--yds-border-radius-medium`<br>`radius.MEDIUM` | medium | `4px`   | Tag, TagFilter, SectionTabs                                  |
| `--yds-border-radius-large`<br>`radius.LARGE` | large  | `8px`   | ButtonGroup Buttons, Modal, BottomSheet, DropdownMenuGroup   |
| `--yds-border-radius-full`<br>`radius.FULL` | full   | `400px` | Fully rounded pill shape; Buttons, Badge, PageIndicator dots |

# Border

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=88-2864)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/design-tokens-border--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/design-tokens/border.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

Border width tokens for consistent border sizing across components. Token values contain corresponding unit (px).

| CSS / JS     | Token | Value | Description                                             |
| ----------- | ----- | ----- | ------------------------------------------------------- |
| `--yds-border-sm`<br>`border.BORDER_SM` | sm    | `1px` | Separator borders; Accordion dividers                   |
| `--yds-border-md`<br>`border.BORDER_MD` | md    | `2px` | Standard component borders; inputs, buttons, checkboxes |
| `--yds-border-lg`<br>`border.BORDER_LG` | lg    | `3px` | Focus rings and outlines for interactive elements       |

# Global Colors

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=26-1922)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/design-tokens-colors--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/design-tokens/global-colors.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

[Theme Colors](/docs/design-tokens/theme-colors) are built on global colors. Global colors serves as the foundation of the color system, from which semantic theme tokens are derived.

Global colors are divided into groups that guide their usage:

- Black and white
- Neutrals
- Brand
- Complementary
- Notifications.

## Black and white

Black and white base colors are primarily used for text and backgrounds.

| CSS / JS     | Token | Value     |
| ----------- | ----- | --------- |
| `--yds-color-white`<br>`color.WHITE` | white | `#ffffff` |
| `--yds-color-black`<br>`color.BLACK` | black | `#000000` |

## Neutrals

Neutral colors **(grays and opacity values)** are the core colors of the user interface. They are used for:

- backgrounds
- surfaces
- borders
- separators
- subtle differences between states (hover, active, disabled).

Opacity tokens enable controlled use of the same shades across different backgrounds and themes.

### Gray

| CSS / JS     | Token   | Value     |
| ----------- | ------- | --------- |
| `--yds-color-gray-5`<br>`color.GRAY_5` | gray-5  | `#f8f9fa` |
| `--yds-color-gray-10`<br>`color.GRAY_10` | gray-10 | `#f1f2f4` |
| `--yds-color-gray-20`<br>`color.GRAY_20` | gray-20 | `#e8e9eb` |
| `--yds-color-gray-30`<br>`color.GRAY_30` | gray-30 | `#d8d9db` |
| `--yds-color-gray-40`<br>`color.GRAY_40` | gray-40 | `#b4b6b7` |
| `--yds-color-gray-50`<br>`color.GRAY_50` | gray-50 | `#878a8b` |
| `--yds-color-gray-60`<br>`color.GRAY_60` | gray-60 | `#4a4f54` |
| `--yds-color-gray-70`<br>`color.GRAY_70` | gray-70 | `#323639` |
| `--yds-color-gray-80`<br>`color.GRAY_80` | gray-80 | `#292b2d` |
| `--yds-color-gray-90`<br>`color.GRAY_90` | gray-90 | `#1f2123` |
| `--yds-color-gray-95`<br>`color.GRAY_95` | gray-95 | `#131415` |

### Black Opacity

| CSS / JS     | Token            | Value                 |
| ----------- | ---------------- | --------------------- |
| `--yds-color-black-opacity-5`<br>`color.BLACK_OPACITY_5` | black-opacity-5  | `rgba(0, 0, 0, 0.02)` |
| `--yds-color-black-opacity-10`<br>`color.BLACK_OPACITY_10` | black-opacity-10 | `rgba(0, 0, 0, 0.05)` |
| `--yds-color-black-opacity-20`<br>`color.BLACK_OPACITY_20` | black-opacity-20 | `rgba(0, 0, 0, 0.09)` |
| `--yds-color-black-opacity-30`<br>`color.BLACK_OPACITY_30` | black-opacity-30 | `rgba(0, 0, 0, 0.15)` |
| `--yds-color-black-opacity-40`<br>`color.BLACK_OPACITY_40` | black-opacity-40 | `rgba(0, 0, 0, 0.29)` |
| `--yds-color-black-opacity-50`<br>`color.BLACK_OPACITY_50` | black-opacity-50 | `rgba(0, 0, 0, 0.47)` |
| `--yds-color-black-opacity-60`<br>`color.BLACK_OPACITY_60` | black-opacity-60 | `rgba(0, 0, 0, 0.70)` |
| `--yds-color-black-opacity-70`<br>`color.BLACK_OPACITY_70` | black-opacity-70 | `rgba(0, 0, 0, 0.79)` |
| `--yds-color-black-opacity-80`<br>`color.BLACK_OPACITY_80` | black-opacity-80 | `rgba(0, 0, 0, 0.83)` |
| `--yds-color-black-opacity-90`<br>`color.BLACK_OPACITY_90` | black-opacity-90 | `rgba(0, 0, 0, 0.87)` |
| `--yds-color-black-opacity-95`<br>`color.BLACK_OPACITY_95` | black-opacity-95 | `rgba(0, 0, 0, 0.92)` |

### White Opacity

| CSS / JS     | Token            | Value                       |
| ----------- | ---------------- | --------------------------- |
| `--yds-color-white-opacity-5`<br>`color.WHITE_OPACITY_5` | white-opacity-5  | `rgba(255, 255, 255, 0.08)` |
| `--yds-color-white-opacity-10`<br>`color.WHITE_OPACITY_10` | white-opacity-10 | `rgba(255, 255, 255, 0.13)` |
| `--yds-color-white-opacity-20`<br>`color.WHITE_OPACITY_20` | white-opacity-20 | `rgba(255, 255, 255, 0.17)` |
| `--yds-color-white-opacity-30`<br>`color.WHITE_OPACITY_30` | white-opacity-30 | `rgba(255, 255, 255, 0.21)` |
| `--yds-color-white-opacity-40`<br>`color.WHITE_OPACITY_40` | white-opacity-40 | `rgba(255, 255, 255, 0.30)` |
| `--yds-color-white-opacity-50`<br>`color.WHITE_OPACITY_50` | white-opacity-50 | `rgba(255, 255, 255, 0.53)` |
| `--yds-color-white-opacity-60`<br>`color.WHITE_OPACITY_60` | white-opacity-60 | `rgba(255, 255, 255, 0.71)` |
| `--yds-color-white-opacity-70`<br>`color.WHITE_OPACITY_70` | white-opacity-70 | `rgba(255, 255, 255, 0.85)` |
| `--yds-color-white-opacity-80`<br>`color.WHITE_OPACITY_80` | white-opacity-80 | `rgba(255, 255, 255, 0.91)` |
| `--yds-color-white-opacity-90`<br>`color.WHITE_OPACITY_90` | white-opacity-90 | `rgba(255, 255, 255, 0.95)` |
| `--yds-color-white-opacity-95`<br>`color.WHITE_OPACITY_95` | white-opacity-95 | `rgba(255, 255, 255, 0.98)` |

## Brand

**Yle’s brand turquoise** is the primary user interface color in Yle services and is used to guide users in different interactions.

**The Yle News and Yle Sports colors**, are used in infographic base themes and other infographic content.

### Turquoise

| CSS / JS     | Token        | Value     |
| ----------- | ------------ | --------- |
| `--yds-color-turquoise-5`<br>`color.TURQUOISE_5` | turquoise-5  | `#e5fdff` |
| `--yds-color-turquoise-10`<br>`color.TURQUOISE_10` | turquoise-10 | `#c7f4fa` |
| `--yds-color-turquoise-20`<br>`color.TURQUOISE_20` | turquoise-20 | `#9cebf4` |
| `--yds-color-turquoise-30`<br>`color.TURQUOISE_30` | turquoise-30 | `#5ddbe9` |
| `--yds-color-turquoise-40`<br>`color.TURQUOISE_40` | turquoise-40 | `#29ccde` |
| `--yds-color-turquoise-50`<br>`color.TURQUOISE_50` | turquoise-50 | `#00b4c8` |
| `--yds-color-turquoise-60`<br>`color.TURQUOISE_60` | turquoise-60 | `#009cb5` |
| `--yds-color-turquoise-70`<br>`color.TURQUOISE_70` | turquoise-70 | `#00809c` |
| `--yds-color-turquoise-80`<br>`color.TURQUOISE_80` | turquoise-80 | `#00637d` |
| `--yds-color-turquoise-90`<br>`color.TURQUOISE_90` | turquoise-90 | `#00475e` |
| `--yds-color-turquoise-95`<br>`color.TURQUOISE_95` | turquoise-95 | `#0b3f4b` |

### News Violet

| CSS / JS     | Token          | Value     |
| ----------- | -------------- | --------- |
| `--yds-color-news-violet-5`<br>`color.NEWS_VIOLET_5` | news-violet-5  | `#e6e5ff` |
| `--yds-color-news-violet-10`<br>`color.NEWS_VIOLET_10` | news-violet-10 | `#d3cbfb` |
| `--yds-color-news-violet-20`<br>`color.NEWS_VIOLET_20` | news-violet-20 | `#b7a8fa` |
| `--yds-color-news-violet-30`<br>`color.NEWS_VIOLET_30` | news-violet-30 | `#9479fb` |
| `--yds-color-news-violet-40`<br>`color.NEWS_VIOLET_40` | news-violet-40 | `#7c59fa` |
| `--yds-color-news-violet-50`<br>`color.NEWS_VIOLET_50` | news-violet-50 | `#694bd7` |
| `--yds-color-news-violet-60`<br>`color.NEWS_VIOLET_60` | news-violet-60 | `#553db4` |
| `--yds-color-news-violet-70`<br>`color.NEWS_VIOLET_70` | news-violet-70 | `#413091` |
| `--yds-color-news-violet-80`<br>`color.NEWS_VIOLET_80` | news-violet-80 | `#2f2372` |
| `--yds-color-news-violet-90`<br>`color.NEWS_VIOLET_90` | news-violet-90 | `#1e1753` |
| `--yds-color-news-violet-95`<br>`color.NEWS_VIOLET_95` | news-violet-95 | `#120e3e` |

### News Orange

| CSS / JS     | Token          | Value     |
| ----------- | -------------- | --------- |
| `--yds-color-news-orange-5`<br>`color.NEWS_ORANGE_5` | news-orange-5  | `#fff2f2` |
| `--yds-color-news-orange-10`<br>`color.NEWS_ORANGE_10` | news-orange-10 | `#fdd6d3` |
| `--yds-color-news-orange-20`<br>`color.NEWS_ORANGE_20` | news-orange-20 | `#fab8b3` |
| `--yds-color-news-orange-30`<br>`color.NEWS_ORANGE_30` | news-orange-30 | `#f79c94` |
| `--yds-color-news-orange-40`<br>`color.NEWS_ORANGE_40` | news-orange-40 | `#f57f74` |
| `--yds-color-news-orange-50`<br>`color.NEWS_ORANGE_50` | news-orange-50 | `#f26659` |
| `--yds-color-news-orange-60`<br>`color.NEWS_ORANGE_60` | news-orange-60 | `#d24f45` |
| `--yds-color-news-orange-70`<br>`color.NEWS_ORANGE_70` | news-orange-70 | `#b83c35` |
| `--yds-color-news-orange-80`<br>`color.NEWS_ORANGE_80` | news-orange-80 | `#9b2823` |
| `--yds-color-news-orange-90`<br>`color.NEWS_ORANGE_90` | news-orange-90 | `#7f1412` |
| `--yds-color-news-orange-95`<br>`color.NEWS_ORANGE_95` | news-orange-95 | `#650101` |

### Sports Violet

| CSS / JS     | Token            | Value     |
| ----------- | ---------------- | --------- |
| `--yds-color-sports-violet-5`<br>`color.SPORTS_VIOLET_5` | sports-violet-5  | `#eeeeff` |
| `--yds-color-sports-violet-10`<br>`color.SPORTS_VIOLET_10` | sports-violet-10 | `#ddd9fc` |
| `--yds-color-sports-violet-20`<br>`color.SPORTS_VIOLET_20` | sports-violet-20 | `#b3abf7` |
| `--yds-color-sports-violet-30`<br>`color.SPORTS_VIOLET_30` | sports-violet-30 | `#8578f2` |
| `--yds-color-sports-violet-40`<br>`color.SPORTS_VIOLET_40` | sports-violet-40 | `#6553ef` |
| `--yds-color-sports-violet-50`<br>`color.SPORTS_VIOLET_50` | sports-violet-50 | `#5541ed` |
| `--yds-color-sports-violet-60`<br>`color.SPORTS_VIOLET_60` | sports-violet-60 | `#372bb1` |
| `--yds-color-sports-violet-70`<br>`color.SPORTS_VIOLET_70` | sports-violet-70 | `#292094` |
| `--yds-color-sports-violet-80`<br>`color.SPORTS_VIOLET_80` | sports-violet-80 | `#1a1476` |
| `--yds-color-sports-violet-90`<br>`color.SPORTS_VIOLET_90` | sports-violet-90 | `#0d0a5c` |
| `--yds-color-sports-violet-95`<br>`color.SPORTS_VIOLET_95` | sports-violet-95 | `#030349` |

### Sports Lime

| CSS / JS     | Token          | Value     |
| ----------- | -------------- | --------- |
| `--yds-color-sports-lime-5`<br>`color.SPORTS_LIME_5` | sports-lime-5  | `#fdfde7` |
| `--yds-color-sports-lime-10`<br>`color.SPORTS_LIME_10` | sports-lime-10 | `#f9ffc6` |
| `--yds-color-sports-lime-20`<br>`color.SPORTS_LIME_20` | sports-lime-20 | `#ebfe8d` |
| `--yds-color-sports-lime-30`<br>`color.SPORTS_LIME_30` | sports-lime-30 | `#d4ff42` |
| `--yds-color-sports-lime-40`<br>`color.SPORTS_LIME_40` | sports-lime-40 | `#caf53e` |
| `--yds-color-sports-lime-50`<br>`color.SPORTS_LIME_50` | sports-lime-50 | `#b0d934` |
| `--yds-color-sports-lime-60`<br>`color.SPORTS_LIME_60` | sports-lime-60 | `#91ae42` |
| `--yds-color-sports-lime-70`<br>`color.SPORTS_LIME_70` | sports-lime-70 | `#7a9a2c` |
| `--yds-color-sports-lime-80`<br>`color.SPORTS_LIME_80` | sports-lime-80 | `#618515` |
| `--yds-color-sports-lime-90`<br>`color.SPORTS_LIME_90` | sports-lime-90 | `#46690b` |
| `--yds-color-sports-lime-95`<br>`color.SPORTS_LIME_95` | sports-lime-95 | `#2c4d01` |

### Sports Pink

| CSS / JS     | Token          | Value     |
| ----------- | -------------- | --------- |
| `--yds-color-sports-pink-5`<br>`color.SPORTS_PINK_5` | sports-pink-5  | `#fff5f9` |
| `--yds-color-sports-pink-10`<br>`color.SPORTS_PINK_10` | sports-pink-10 | `#fcd9e8` |
| `--yds-color-sports-pink-20`<br>`color.SPORTS_PINK_20` | sports-pink-20 | `#f7abcb` |
| `--yds-color-sports-pink-30`<br>`color.SPORTS_PINK_30` | sports-pink-30 | `#f273a8` |
| `--yds-color-sports-pink-40`<br>`color.SPORTS_PINK_40` | sports-pink-40 | `#ea3e85` |
| `--yds-color-sports-pink-50`<br>`color.SPORTS_PINK_50` | sports-pink-50 | `#e60060` |
| `--yds-color-sports-pink-60`<br>`color.SPORTS_PINK_60` | sports-pink-60 | `#c50152` |
| `--yds-color-sports-pink-70`<br>`color.SPORTS_PINK_70` | sports-pink-70 | `#a70146` |
| `--yds-color-sports-pink-80`<br>`color.SPORTS_PINK_80` | sports-pink-80 | `#880139` |
| `--yds-color-sports-pink-90`<br>`color.SPORTS_PINK_90` | sports-pink-90 | `#6b012c` |
| `--yds-color-sports-pink-95`<br>`color.SPORTS_PINK_95` | sports-pink-95 | `#4d0120` |

## Complementary

In addition to brand colors, **complementary colors** are used in infographics and data visualizations, especially when a broader color scale is needed to improve clarity and distinction.

**These colors are not used in UI components.**

### Info Orange

| CSS / JS     | Token          | Value     |
| ----------- | -------------- | --------- |
| `--yds-color-info-orange-5`<br>`color.INFO_ORANGE_5` | info-orange-5  | `#fff3e2` |
| `--yds-color-info-orange-10`<br>`color.INFO_ORANGE_10` | info-orange-10 | `#ffe3bf` |
| `--yds-color-info-orange-20`<br>`color.INFO_ORANGE_20` | info-orange-20 | `#ffd199` |
| `--yds-color-info-orange-30`<br>`color.INFO_ORANGE_30` | info-orange-30 | `#fec075` |
| `--yds-color-info-orange-40`<br>`color.INFO_ORANGE_40` | info-orange-40 | `#feb054` |
| `--yds-color-info-orange-50`<br>`color.INFO_ORANGE_50` | info-orange-50 | `#ff8f33` |
| `--yds-color-info-orange-60`<br>`color.INFO_ORANGE_60` | info-orange-60 | `#f56a1b` |
| `--yds-color-info-orange-70`<br>`color.INFO_ORANGE_70` | info-orange-70 | `#e65a27` |
| `--yds-color-info-orange-80`<br>`color.INFO_ORANGE_80` | info-orange-80 | `#e04312` |
| `--yds-color-info-orange-90`<br>`color.INFO_ORANGE_90` | info-orange-90 | `#c93c11` |
| `--yds-color-info-orange-95`<br>`color.INFO_ORANGE_95` | info-orange-95 | `#9b2e0d` |

### Info Yellow

| CSS / JS     | Token          | Value     |
| ----------- | -------------- | --------- |
| `--yds-color-info-yellow-5`<br>`color.INFO_YELLOW_5` | info-yellow-5  | `#fff8e0` |
| `--yds-color-info-yellow-10`<br>`color.INFO_YELLOW_10` | info-yellow-10 | `#ffeeb2` |
| `--yds-color-info-yellow-20`<br>`color.INFO_YELLOW_20` | info-yellow-20 | `#ffe387` |
| `--yds-color-info-yellow-30`<br>`color.INFO_YELLOW_30` | info-yellow-30 | `#ffd959` |
| `--yds-color-info-yellow-40`<br>`color.INFO_YELLOW_40` | info-yellow-40 | `#ffcf2d` |
| `--yds-color-info-yellow-50`<br>`color.INFO_YELLOW_50` | info-yellow-50 | `#ffc400` |
| `--yds-color-info-yellow-60`<br>`color.INFO_YELLOW_60` | info-yellow-60 | `#f1b601` |
| `--yds-color-info-yellow-70`<br>`color.INFO_YELLOW_70` | info-yellow-70 | `#cc9601` |
| `--yds-color-info-yellow-80`<br>`color.INFO_YELLOW_80` | info-yellow-80 | `#ae7b01` |
| `--yds-color-info-yellow-90`<br>`color.INFO_YELLOW_90` | info-yellow-90 | `#926201` |
| `--yds-color-info-yellow-95`<br>`color.INFO_YELLOW_95` | info-yellow-95 | `#764901` |

### Info Green

| CSS / JS     | Token         | Value     |
| ----------- | ------------- | --------- |
| `--yds-color-info-green-5`<br>`color.INFO_GREEN_5` | info-green-5  | `#e0fff4` |
| `--yds-color-info-green-10`<br>`color.INFO_GREEN_10` | info-green-10 | `#b4f5de` |
| `--yds-color-info-green-20`<br>`color.INFO_GREEN_20` | info-green-20 | `#88eac7` |
| `--yds-color-info-green-30`<br>`color.INFO_GREEN_30` | info-green-30 | `#5fe0b2` |
| `--yds-color-info-green-40`<br>`color.INFO_GREEN_40` | info-green-40 | `#33d59b` |
| `--yds-color-info-green-50`<br>`color.INFO_GREEN_50` | info-green-50 | `#07ca84` |
| `--yds-color-info-green-60`<br>`color.INFO_GREEN_60` | info-green-60 | `#07b577` |
| `--yds-color-info-green-70`<br>`color.INFO_GREEN_70` | info-green-70 | `#06a26a` |
| `--yds-color-info-green-80`<br>`color.INFO_GREEN_80` | info-green-80 | `#068e5d` |
| `--yds-color-info-green-90`<br>`color.INFO_GREEN_90` | info-green-90 | `#05794f` |
| `--yds-color-info-green-95`<br>`color.INFO_GREEN_95` | info-green-95 | `#046542` |

### Info Orange

| CSS / JS     | Token          | Value     |
| ----------- | -------------- | --------- |
| `--yds-color-info-orange-5`<br>`color.INFO_ORANGE_5` | info-orange-5  | `#fff3e2` |
| `--yds-color-info-orange-10`<br>`color.INFO_ORANGE_10` | info-orange-10 | `#ffe3bf` |
| `--yds-color-info-orange-20`<br>`color.INFO_ORANGE_20` | info-orange-20 | `#ffd199` |
| `--yds-color-info-orange-30`<br>`color.INFO_ORANGE_30` | info-orange-30 | `#fec075` |
| `--yds-color-info-orange-40`<br>`color.INFO_ORANGE_40` | info-orange-40 | `#feb054` |
| `--yds-color-info-orange-50`<br>`color.INFO_ORANGE_50` | info-orange-50 | `#ff8f33` |
| `--yds-color-info-orange-60`<br>`color.INFO_ORANGE_60` | info-orange-60 | `#f56a1b` |
| `--yds-color-info-orange-70`<br>`color.INFO_ORANGE_70` | info-orange-70 | `#e65a27` |
| `--yds-color-info-orange-80`<br>`color.INFO_ORANGE_80` | info-orange-80 | `#e04312` |
| `--yds-color-info-orange-90`<br>`color.INFO_ORANGE_90` | info-orange-90 | `#c93c11` |
| `--yds-color-info-orange-95`<br>`color.INFO_ORANGE_95` | info-orange-95 | `#9b2e0d` |

### Info Yellow

| CSS / JS     | Token          | Value     |
| ----------- | -------------- | --------- |
| `--yds-color-info-yellow-5`<br>`color.INFO_YELLOW_5` | info-yellow-5  | `#fff8e0` |
| `--yds-color-info-yellow-10`<br>`color.INFO_YELLOW_10` | info-yellow-10 | `#ffeeb2` |
| `--yds-color-info-yellow-20`<br>`color.INFO_YELLOW_20` | info-yellow-20 | `#ffe387` |
| `--yds-color-info-yellow-30`<br>`color.INFO_YELLOW_30` | info-yellow-30 | `#ffd959` |
| `--yds-color-info-yellow-40`<br>`color.INFO_YELLOW_40` | info-yellow-40 | `#ffcf2d` |
| `--yds-color-info-yellow-50`<br>`color.INFO_YELLOW_50` | info-yellow-50 | `#ffc400` |
| `--yds-color-info-yellow-60`<br>`color.INFO_YELLOW_60` | info-yellow-60 | `#f1b601` |
| `--yds-color-info-yellow-70`<br>`color.INFO_YELLOW_70` | info-yellow-70 | `#cc9601` |
| `--yds-color-info-yellow-80`<br>`color.INFO_YELLOW_80` | info-yellow-80 | `#ae7b01` |
| `--yds-color-info-yellow-90`<br>`color.INFO_YELLOW_90` | info-yellow-90 | `#926201` |
| `--yds-color-info-yellow-95`<br>`color.INFO_YELLOW_95` | info-yellow-95 | `#764901` |

### Info Green

| CSS / JS     | Token         | Value     |
| ----------- | ------------- | --------- |
| `--yds-color-info-green-5`<br>`color.INFO_GREEN_5` | info-green-5  | `#e0fff4` |
| `--yds-color-info-green-10`<br>`color.INFO_GREEN_10` | info-green-10 | `#b4f5de` |
| `--yds-color-info-green-20`<br>`color.INFO_GREEN_20` | info-green-20 | `#88eac7` |
| `--yds-color-info-green-30`<br>`color.INFO_GREEN_30` | info-green-30 | `#5fe0b2` |
| `--yds-color-info-green-40`<br>`color.INFO_GREEN_40` | info-green-40 | `#33d59b` |
| `--yds-color-info-green-50`<br>`color.INFO_GREEN_50` | info-green-50 | `#07ca84` |
| `--yds-color-info-green-60`<br>`color.INFO_GREEN_60` | info-green-60 | `#07b577` |
| `--yds-color-info-green-70`<br>`color.INFO_GREEN_70` | info-green-70 | `#06a26a` |
| `--yds-color-info-green-80`<br>`color.INFO_GREEN_80` | info-green-80 | `#068e5d` |
| `--yds-color-info-green-90`<br>`color.INFO_GREEN_90` | info-green-90 | `#05794f` |
| `--yds-color-info-green-95`<br>`color.INFO_GREEN_95` | info-green-95 | `#046542` |

### Info Blue

| CSS / JS     | Token        | Value     |
| ----------- | ------------ | --------- |
| `--yds-color-info-blue-5`<br>`color.INFO_BLUE_5` | info-blue-5  | `#e0f2ff` |
| `--yds-color-info-blue-10`<br>`color.INFO_BLUE_10` | info-blue-10 | `#bbdcff` |
| `--yds-color-info-blue-20`<br>`color.INFO_BLUE_20` | info-blue-20 | `#95c6ff` |
| `--yds-color-info-blue-30`<br>`color.INFO_BLUE_30` | info-blue-30 | `#71b0ff` |
| `--yds-color-info-blue-40`<br>`color.INFO_BLUE_40` | info-blue-40 | `#4b9aff` |
| `--yds-color-info-blue-50`<br>`color.INFO_BLUE_50` | info-blue-50 | `#2684ff` |
| `--yds-color-info-blue-60`<br>`color.INFO_BLUE_60` | info-blue-60 | `#2078ed` |
| `--yds-color-info-blue-70`<br>`color.INFO_BLUE_70` | info-blue-70 | `#196dda` |
| `--yds-color-info-blue-80`<br>`color.INFO_BLUE_80` | info-blue-80 | `#1260c7` |
| `--yds-color-info-blue-90`<br>`color.INFO_BLUE_90` | info-blue-90 | `#0b54b4` |
| `--yds-color-info-blue-95`<br>`color.INFO_BLUE_95` | info-blue-95 | `#0448a1` |

### Info Deep Blue

| CSS / JS     | Token             | Value     |
| ----------- | ----------------- | --------- |
| `--yds-color-info-deep-blue-5`<br>`color.INFO_DEEP_BLUE_5` | info-deep-blue-5  | `#e3eaf3` |
| `--yds-color-info-deep-blue-10`<br>`color.INFO_DEEP_BLUE_10` | info-deep-blue-10 | `#c9d5e6` |
| `--yds-color-info-deep-blue-20`<br>`color.INFO_DEEP_BLUE_20` | info-deep-blue-20 | `#b0c1da` |
| `--yds-color-info-deep-blue-30`<br>`color.INFO_DEEP_BLUE_30` | info-deep-blue-30 | `#99aece` |
| `--yds-color-info-deep-blue-40`<br>`color.INFO_DEEP_BLUE_40` | info-deep-blue-40 | `#738ab5` |
| `--yds-color-info-deep-blue-50`<br>`color.INFO_DEEP_BLUE_50` | info-deep-blue-50 | `#546d9c` |
| `--yds-color-info-deep-blue-60`<br>`color.INFO_DEEP_BLUE_60` | info-deep-blue-60 | `#3d5483` |
| `--yds-color-info-deep-blue-70`<br>`color.INFO_DEEP_BLUE_70` | info-deep-blue-70 | `#1e2e52` |
| `--yds-color-info-deep-blue-80`<br>`color.INFO_DEEP_BLUE_80` | info-deep-blue-80 | `#131e39` |
| `--yds-color-info-deep-blue-90`<br>`color.INFO_DEEP_BLUE_90` | info-deep-blue-90 | `#131625` |
| `--yds-color-info-deep-blue-95`<br>`color.INFO_DEEP_BLUE_95` | info-deep-blue-95 | `#020408` |

### Info Purple

| CSS / JS     | Token          | Value     |
| ----------- | -------------- | --------- |
| `--yds-color-info-purple-5`<br>`color.INFO_PURPLE_5` | info-purple-5  | `#fcf5ff` |
| `--yds-color-info-purple-10`<br>`color.INFO_PURPLE_10` | info-purple-10 | `#e8d0f1` |
| `--yds-color-info-purple-20`<br>`color.INFO_PURPLE_20` | info-purple-20 | `#d9b0e8` |
| `--yds-color-info-purple-30`<br>`color.INFO_PURPLE_30` | info-purple-30 | `#ca91de` |
| `--yds-color-info-purple-40`<br>`color.INFO_PURPLE_40` | info-purple-40 | `#ba72d5` |
| `--yds-color-info-purple-50`<br>`color.INFO_PURPLE_50` | info-purple-50 | `#9436b5` |
| `--yds-color-info-purple-60`<br>`color.INFO_PURPLE_60` | info-purple-60 | `#80259f` |
| `--yds-color-info-purple-70`<br>`color.INFO_PURPLE_70` | info-purple-70 | `#620579` |
| `--yds-color-info-purple-80`<br>`color.INFO_PURPLE_80` | info-purple-80 | `#4b075b` |
| `--yds-color-info-purple-90`<br>`color.INFO_PURPLE_90` | info-purple-90 | `#30063a` |
| `--yds-color-info-purple-95`<br>`color.INFO_PURPLE_95` | info-purple-95 | `#1c0222` |

## Notifications

Notification colors are designed exclusively for feedback and status messaging (e.g., success, warning, error, information). They are primarily used for message surfaces, backgrounds, and status indicators. **These colors should not be used for other purposes**, to ensure consistent and logical use in the user interface.

### Red

| CSS / JS     | Token  | Value     |
| ----------- | ------ | --------- |
| `--yds-color-red-5`<br>`color.RED_5` | red-5  | `#fff5f8` |
| `--yds-color-red-10`<br>`color.RED_10` | red-10 | `#fcc5d3` |
| `--yds-color-red-20`<br>`color.RED_20` | red-20 | `#f99fb5` |
| `--yds-color-red-30`<br>`color.RED_30` | red-30 | `#f77898` |
| `--yds-color-red-40`<br>`color.RED_40` | red-40 | `#f5517a` |
| `--yds-color-red-50`<br>`color.RED_50` | red-50 | `#e90e43` |
| `--yds-color-red-60`<br>`color.RED_60` | red-60 | `#d10b3d` |
| `--yds-color-red-70`<br>`color.RED_70` | red-70 | `#9a092d` |
| `--yds-color-red-80`<br>`color.RED_80` | red-80 | `#740722` |
| `--yds-color-red-90`<br>`color.RED_90` | red-90 | `#4d0417` |

### Green

| CSS / JS     | Token    | Value     |
| ----------- | -------- | --------- |
| `--yds-color-green-5`<br>`color.GREEN_5` | green-5  | `#e5fff9` |
| `--yds-color-green-10`<br>`color.GREEN_10` | green-10 | `#a1f9dd` |
| `--yds-color-green-20`<br>`color.GREEN_20` | green-20 | `#62f9c2` |
| `--yds-color-green-30`<br>`color.GREEN_30` | green-30 | `#1ff0a4` |
| `--yds-color-green-40`<br>`color.GREEN_40` | green-40 | `#03e592` |
| `--yds-color-green-50`<br>`color.GREEN_50` | green-50 | `#07ca84` |
| `--yds-color-green-60`<br>`color.GREEN_60` | green-60 | `#06b173` |
| `--yds-color-green-70`<br>`color.GREEN_70` | green-70 | `#058657` |
| `--yds-color-green-80`<br>`color.GREEN_80` | green-80 | `#046240` |
| `--yds-color-green-90`<br>`color.GREEN_90` | green-90 | `#023b26` |

### Orange

| CSS / JS     | Token     | Value     |
| ----------- | --------- | --------- |
| `--yds-color-orange-5`<br>`color.ORANGE_5` | orange-5  | `#fff3e2` |
| `--yds-color-orange-10`<br>`color.ORANGE_10` | orange-10 | `#ffe1b8` |
| `--yds-color-orange-20`<br>`color.ORANGE_20` | orange-20 | `#ffce8b` |
| `--yds-color-orange-30`<br>`color.ORANGE_30` | orange-30 | `#ffb95f` |
| `--yds-color-orange-40`<br>`color.ORANGE_40` | orange-40 | `#ff9c31` |
| `--yds-color-orange-50`<br>`color.ORANGE_50` | orange-50 | `#ff8f33` |
| `--yds-color-orange-60`<br>`color.ORANGE_60` | orange-60 | `#f1722a` |
| `--yds-color-orange-70`<br>`color.ORANGE_70` | orange-70 | `#e65a27` |
| `--yds-color-orange-80`<br>`color.ORANGE_80` | orange-80 | `#e04312` |
| `--yds-color-orange-90`<br>`color.ORANGE_90` | orange-90 | `#c93c11` |

### Blue

| CSS / JS     | Token   | Value     |
| ----------- | ------- | --------- |
| `--yds-color-blue-5`<br>`color.BLUE_5` | blue-5  | `#e0f2ff` |
| `--yds-color-blue-10`<br>`color.BLUE_10` | blue-10 | `#ccdef5` |
| `--yds-color-blue-20`<br>`color.BLUE_20` | blue-20 | `#9fc8ee` |
| `--yds-color-blue-30`<br>`color.BLUE_30` | blue-30 | `#88b3e7` |
| `--yds-color-blue-40`<br>`color.BLUE_40` | blue-40 | `#669de1` |
| `--yds-color-blue-50`<br>`color.BLUE_50` | blue-50 | `#2975d0` |
| `--yds-color-blue-60`<br>`color.BLUE_60` | blue-60 | `#1163b0` |
| `--yds-color-blue-70`<br>`color.BLUE_70` | blue-70 | `#234c93` |
| `--yds-color-blue-80`<br>`color.BLUE_80` | blue-80 | `#0a3276` |
| `--yds-color-blue-90`<br>`color.BLUE_90` | blue-90 | `#00284e` |

# Design Tokens

Design tokens are the smallest building blocks of a design system. They represent design decisions as data, making it easy to maintain consistency across platforms and products.

Yle Design System’s design tokens are based on Yle’s parent brand in terms of user interface design. The parent brand’s visual identity is black and white, minimalist, and fresh, enabling clear presentation of diverse content across Yle’s main services, such as the Yle service and Areena.

## What are Design Tokens?

Design tokens capture the visual attributes of a design system—colors, typography, spacing, shadows, and more—as named entities. Instead of hardcoding values like `#00b4c8` or `16px`, we use semantic names like `--yds-color-yle-turquoise-50` or `--yds-spacing-16`.

- **Consistency**: Semantic names ensure uniform styling across all products
- **Maintainability**: Update a token value once, and it propagates everywhere
- **Theming**: Switch between light and dark themes by swapping token sets
- **Cross-platform**: Same design decisions, different platform implementations

## Token Categories

| Category                             | Description                                                         |
| ------------------------------------ | ------------------------------------------------------------------- |
| [Global Colors](./global-colors.md) | Base color swatches with neutrals, brand colors, and other palettes |
| [Theme Colors](./theme-colors.md)   | Semantic tokens for UI: backgrounds, text, actions, and feedback    |
| [Spacing](./spacing.md)             | Consistent spacing scale for margins, padding, and gaps             |
| [Border Radius](./border-radius.md) | Corner rounding values for UI elements                              |
| [Border](./border.md)               | Border widths for UI elements                                       |
| [Shadows](./shadows.md)             | Elevation and depth through box shadows                             |
| [Typography](./typography.md)       | Font sizes, weights, and line heights                               |
| [Transitions](./transitions.md)     | Animation duration and easing values                                |

## Using Tokens

### CSS Variables

All tokens are available as CSS custom properties:

```css
.button {
  background-color: var(--yds-color-yle-turquoise-50);
  padding: var(--yds-spacing-8) var(--yds-spacing-16);
  border-radius: var(--yds-border-radius-medium);
  transition: background-color var(--yds-transition-duration-s) var(--yds-transition-easing-default);
}
```

### JavaScript Constants

Import tokens directly in JavaScript/TypeScript:

```tsx
import { defaultTheme, spacing, radius } from '@yleisradio/yds-core';

const styles = {
  backgroundColor: defaultTheme.BACKGROUND, // var(--yds-color-background, #ffffff)
  padding: spacing.SPACING_16, // 16px
  borderRadius: radius.MEDIUM, // 4px
};
```

### Styled Components

Interpolate `defaultTheme` directly. Its values are custom property references, so the colors follow the active theme without any React context:

```tsx
import styled from 'styled-components';
import { defaultTheme } from '@yleisradio/yds-core';

const Card = styled.div`
  background-color: ${defaultTheme.BACKGROUND};
  color: ${defaultTheme.TEXT_DEFAULT};
  border: 1px solid ${defaultTheme.BORDER};
`;
```

Writing `var(--yds-color-background)` by hand works equally well. `defaultTheme` is typed, so it catches misspelled token names at compile time.

> **Warning**
> In 2.x these tokens came from `props.theme.yds` via `YdsThemeProvider`. That context was removed in 3.0. If the app keeps styled-components, see [Using styled-components with YDS 3.0](../using-yds/development/styled-components-to-css.md).

## Theming

The design system supports multiple themes. Semantic color tokens automatically adapt when the theme changes:

- **Light theme**: Light backgrounds and dark texts.
- **Dark theme**: Dark backgrounds with light texts.
- **Default theme**: Default theme with variable color-scheme support to utilise both Light and Dark themes according to user preference
- **Custom themes**: Tietäjä and other product-specific themes, utilising either light or dark theme as a foundation

### Using Theme Tokens

Use semantic theme tokens instead of base colors for UI elements. This ensures proper contrast and accessibility in both light and dark modes:

```css
.card {
  /* ✅ Do: Use theme tokens */
  background-color: var(--yds-color-background);
  color: var(--yds-color-default-text);

  /* ❌ Don't: Use base colors for themed elements */
  background-color: var(--yds-color-white);
}
```

### Applying Themes

Import the theme CSS file and its variables are applied to `:root` automatically — no classes, no React needed:

```css
/* Light theme applied to :root */
@import '@yleisradio/yds-core/tokens/build/css/_theme-default.css';
```

In React, use `YdsThemeProvider` from `@yleisradio/yds-components-react` for a **subtree** that needs a different theme than the document, or for a theme that changes in React:

```tsx
import { YdsThemeProvider } from '@yleisradio/yds-components-react';

<YdsThemeProvider theme="dark">
  <DarkSidebar />
</YdsThemeProvider>;
```

The `theme` prop accepts `'light'`, `'dark'`, `'default'`, or a custom theme object. Providers nest, so an inner one overrides the outer theme for its own subtree:

```tsx
<YdsThemeProvider theme="default">
  <MainContent />
  <YdsThemeProvider theme="dark">
    <DarkSidebar />
  </YdsThemeProvider>
</YdsThemeProvider>
```

To automatically switch to dark based on the user's OS preference, use the `prefers-color-scheme` variant alongside the default:

```css
@import '@yleisradio/yds-core/tokens/build/css/_theme-default.css';
@import '@yleisradio/yds-core/tokens/build/css/_theme-default-prefers-dark.css';
```

To force a specific theme on a subtree, import the themed variants and add the corresponding class:

```css
@import '@yleisradio/yds-core/tokens/build/css/_theme-light.css';
@import '@yleisradio/yds-core/tokens/build/css/_theme-dark.css';
```

```html
<div class="yds-theme-light">Light theme content</div>
<div class="yds-theme-dark">Dark theme content</div>
```

More information about theme setup can be found in the [yds-core](https://github.com/yleisradio/yds/blob/main/packages/yds-core/README.md#theming) documentation.

## Token Naming Convention

A design token is defined in the Figma Variables:

```
spacing/8: 8px
```

This gets converted to the following JSON:

```json
{ "spacing": { "8": { "value": "8px" } } }
```

Is available in each platform format as:

**CSS**

```css
var(--yds-spacing-8) // 8px
```

**SCSS**

```scss
$yds-spacing-8 // 8px
```

**JavaScript**

```ts
import { spacing } from '@yleisradio/yds-core';

spacing.SPACING_8; // 8px
```

For theme colors, token names are semantic (e.g., `background`, `default-text`) rather than descriptive of the color value itself, so they remain meaningful across themes.

# Shadows

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=101-1570)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/design-tokens-shadow--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/design-tokens/shadows.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

Shadow tokens add depth and elevation to UI elements. Dark theme shadows use higher opacity for visibility on dark backgrounds.

<Tabs groupId="theme">
  <TabItem value="light" label="Light" default>

| CSS / JS     | Token | Value                                  | Description                          |
| ----------- | ----- | -------------------------------------- | ------------------------------------ |
| `--yds-shadow-sm`<br>`SHADOW_SM` | sm    | `0px 0px 8px 0px rgba(0, 0, 0, 0.15)`  | Subtle elevation; tooltips, popovers |
| `--yds-shadow-md`<br>`SHADOW_MD` | md    | `0px 0px 16px 0px rgba(0, 0, 0, 0.15)` | Medium elevation; dropdown menus     |
| `--yds-shadow-lg`<br>`SHADOW_LG` | lg    | `0px 0px 24px 0px rgba(0, 0, 0, 0.41)` | High elevation; Modal, BottomSheet   |

  </TabItem>
  <TabItem value="dark" label="Dark">

| CSS / JS     | Token | Value                                  | Description                          |
| ----------- | ----- | -------------------------------------- | ------------------------------------ |
| `--yds-shadow-sm`<br>`SHADOW_SM` | sm    | `0px 0px 8px 0px rgba(0, 0, 0, 0.70)`  | Subtle elevation; tooltips, popovers |
| `--yds-shadow-md`<br>`SHADOW_MD` | md    | `0px 0px 16px 0px rgba(0, 0, 0, 0.70)` | Medium elevation; dropdown menus     |
| `--yds-shadow-lg`<br>`SHADOW_LG` | lg    | `0px 0px 24px 0px rgba(0, 0, 0, 0.87)` | High elevation; Modal, BottomSheet   |

  </TabItem>
</Tabs>

# Spacing

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=101-1311)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/design-tokens-spacing--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/design-tokens/spacing.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

Spacing tokens define consistent spacing values for margins, padding, and gaps throughout the UI. Based on a 4px/8px grid system. Token values contain corresponding unit (px).

| CSS / JS     | Token | Value  | Description                                         |
| ----------- | ----- | ------ | --------------------------------------------------- |
| `--yds-spacing-2`<br>`spacing.SPACING_2` | 2     | `2px`  | Fine-tune adjustments; Link inline padding          |
| `--yds-spacing-4`<br>`spacing.SPACING_4` | 4     | `4px`  | Tight gaps; ButtonGroup, Menu compact padding       |
| `--yds-spacing-8`<br>`spacing.SPACING_8` | 8     | `8px`  | Standard gap; SectionTabs, TagFilter, RadioGroup    |
| `--yds-spacing-12`<br>`spacing.SPACING_12` | 12    | `12px` | MenuItem padding; TagLink, Checkbox/Radio spacing   |
| `--yds-spacing-16`<br>`spacing.SPACING_16` | 16    | `16px` | Input padding; Modal, Button md size, NavigationTab |
| `--yds-spacing-24`<br>`spacing.SPACING_24` | 24    | `24px` | SectionTabs, Dialog, BottomSheet padding            |
| `--yds-spacing-32`<br>`spacing.SPACING_32` | 32    | `32px` | Dialog header padding; large section spacing        |
| `--yds-spacing-40`<br>`spacing.SPACING_40` | 40    | `40px` | Layout spacing; section margins                     |
| `--yds-spacing-48`<br>`spacing.SPACING_48` | 48    | `48px` | Layout spacing; content blocks                      |
| `--yds-spacing-56`<br>`spacing.SPACING_56` | 56    | `56px` | Layout spacing; major sections                      |
| `--yds-spacing-64`<br>`spacing.SPACING_64` | 64    | `64px` | Layout spacing; page-level sections                 |
| `--yds-spacing-72`<br>`spacing.SPACING_72` | 72    | `72px` | Layout spacing; large page-level gaps               |

# Theme Colors

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=26-1922)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/design-tokens-colors--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/design-tokens/theme-colors.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

Theme colors are semantic tokens that define the color language of UI elements. They reference global colors and adapt to different themes (light/dark). Yle services use both light and dark themes. Yle Areena uses only the dark theme. Tietäjä is built for Yle’s event betting games and is based on the YDS dark theme.

## Background

Background tokens define the main surfaces of the UI: page backgrounds, surface variants, and overlay surfaces such as dialogs and backdrops. Use these tokens to structure layouts, separate sections, and create elevation through subtle surface changes.

<Tabs groupId="theme">
  <TabItem value="light" label="Light" default>

| CSS / JS     | Token                          | Value                                      | Description                                                                        |
| ----------- | ------------------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------- |
| `--yds-color-background`<br>`BACKGROUND` | background                     | `#ffffff` / `white`                        | Primary page background.                                                           |
| `--yds-color-background-variant`<br>`BACKGROUND_VARIANT` | background-variant             | `#f8f9fa` / `gray-5`                       | Alternate background color for cards and sections. Elevates content blocks.        |
| `--yds-color-background-negative`<br>`BACKGROUND_NEGATIVE` | negative-background            | `#131415` / `gray-95`                      | Inverted background for high-priority contrasting elements.                        |
| `--yds-color-background-navigation`<br>`BACKGROUND_NAVIGATION` | navigation-background          | `#ffffff` / `white`                        | Navigation bar and header backgrounds (in Yle Areena).                             |
| `--yds-color-background-control`<br>`BACKGROUND_CONTROL` | control-background             | `rgba(0, 0, 0, 0.47)` / `black-opacity-50` | Unselected form control background (eg. Switch).                                   |
| `--yds-color-background-control-disabled`<br>`BACKGROUND_CONTROL_DISABLED` | control-background-disabled    | `rgba(0, 0, 0, 0.15)` / `black-opacity-30` | Disabled form control background (eg. Switch).                                     |
| `--yds-color-background-input`<br>`BACKGROUND_INPUT` | input-background               | `#ffffff` / `white`                        | Textual form field backgrounds (eg. TextInput, Textarea, Select).                  |
| `--yds-color-tag-highlight-background`<br>`TAG_HIGHLIGHT_BACKGROUND` | highlight-background           | `#e8e9eb` / `gray-20`                      | Subtle highlighted or selected content background (in Yle Areena).                 |
| `--yds-color-background-interactive`<br>`BACKGROUND_INTERACTIVE` | background-interactive         | `#f1f2f4` / `gray-10`                      | Selectable list item background (eg. ChoiceBox and ChoiceButton).                  |
| `--yds-color-background-dialog`<br>`BACKGROUND_DIALOG` | dialog-background              | `#ffffff` / `white`                        | Overlay content backgrounds (eg. Modal and BottomSheet).                           |
| `--yds-color-background-dialog-overlay`<br>`BACKGROUND_DIALOG_OVERLAY` | dialog-overlay                 | `rgba(0, 0, 0, 0.47)` / `black-opacity-50` | Backdrop of overlays, dimming rest of the page (eg. Modal and BottomSheet).        |
| `--yds-color-background-info-primary`<br>`BACKGROUND_INFO_PRIMARY` | info-primary-background        | `#9fc8ee` / `blue-20`                      | Notification information, primary variant.                                         |
| `--yds-color-background-info-secondary`<br>`BACKGROUND_INFO_SECONDARY` | info-secondary-background      | `#f1f2f4` / `gray-10`                      | Notification information, secondary variant.                                       |
| `--yds-color-background-success`<br>`BACKGROUND_SUCCESS` | success-background             | `#62f9c2` / `green-20`                     | Notification of success background.                                                |
| `--yds-color-background-warning`<br>`BACKGROUND_WARNING` | warning-background             | `#ffd199` / `info-orange-20`               | Notification of warning background.                                                |
| `--yds-color-background-error`<br>`BACKGROUND_ERROR` | error-background               | `#f99fb5` / `red-20`                       | Notification of error background.                                                  |
| `--yds-color-background-opinion-article`<br>`BACKGROUND_OPINION_ARTICLE` | opinion-article-background     | `#3d5483` / `info-deep-blue-60`            | Opinion content background (eg. opinion articles).                                 |
| `--yds-color-background-list`<br>`BACKGROUND_LIST` | background-list                | `#ffffff` / `background`                   | Used as the background for lists, link lists, and tables.                          |
| `--yds-color-background-dropdown`<br>`BACKGROUND_DROPDOWN` | background-dropdown            | `#f8f9fa` / `gray-5`                       | Overlaying menu and dropdown background.                                           |
| `--yds-color-background-variant-2`<br>`BACKGROUND_VARIANT_2` | background-variant-2           | `#f1f2f4` / `gray-10`                      | Additional alternate surface background for layered content blocks, such as cards. |
| `--yds-color-background-interactive-variant`<br>`BACKGROUND_INTERACTIVE_VARIANT` | background-interactive-variant | `#ffffff` / `background`                   | Alternative background for interactive items on variant backgrounds.               |
| `--yds-color-background-list-variant`<br>`BACKGROUND_LIST_VARIANT` | background-list-variant        | `rgba(0, 0, 0, 0.02)` / `black-opacity-5`  | Alternating row background within lists and tables.                                |
| `--yds-color-background-list-accent`<br>`BACKGROUND_LIST_ACCENT` | background-list-accent         | `#fff2f2` / `news-orange-5`                | Accent background for highlighted list items, such as selected row.                |

  </TabItem>
  <TabItem value="dark" label="Dark">

| CSS / JS     | Token                          | Value                                            | Description |
| ----------- | ------------------------------ | ------------------------------------------------ | ----------- |
| `--yds-color-background`<br>`BACKGROUND` | background                     | `#131415` / `gray-95`                            |             |
| `--yds-color-background-variant`<br>`BACKGROUND_VARIANT` | background-variant             | `#1f2123` / `gray-90`                            |             |
| `--yds-color-background-negative`<br>`BACKGROUND_NEGATIVE` | negative-background            | `#ffffff` / `white`                              |             |
| `--yds-color-background-navigation`<br>`BACKGROUND_NAVIGATION` | navigation-background          | `#000000` / `black`                              |             |
| `--yds-color-background-control`<br>`BACKGROUND_CONTROL` | control-background             | `rgba(255, 255, 255, 0.53)` / `white-opacity-50` |             |
| `--yds-color-background-control-disabled`<br>`BACKGROUND_CONTROL_DISABLED` | control-background-disabled    | `rgba(255, 255, 255, 0.21)` / `white-opacity-30` |             |
| `--yds-color-background-input`<br>`BACKGROUND_INPUT` | input-background               | `#131415` / `gray-95`                            |             |
| `--yds-color-tag-highlight-background`<br>`TAG_HIGHLIGHT_BACKGROUND` | highlight-background           | `#0b3f4b` / `turquoise-95`                       |             |
| `--yds-color-background-interactive`<br>`BACKGROUND_INTERACTIVE` | background-interactive         | `#292b2d` / `gray-80`                            |             |
| `--yds-color-background-dialog`<br>`BACKGROUND_DIALOG` | dialog-background              | `#1f2123` / `gray-90`                            |             |
| `--yds-color-background-dialog-overlay`<br>`BACKGROUND_DIALOG_OVERLAY` | dialog-overlay                 | `rgba(0, 0, 0, 0.70)` / `black-opacity-60`       |             |
| `--yds-color-background-info-primary`<br>`BACKGROUND_INFO_PRIMARY` | info-primary-background        | `#d8d9db` / `gray-30`                            |             |
| `--yds-color-background-info-secondary`<br>`BACKGROUND_INFO_SECONDARY` | info-secondary-background      | `#292b2d` / `gray-80`                            |             |
| `--yds-color-background-success`<br>`BACKGROUND_SUCCESS` | success-background             | `#33d59b` / `info-green-40`                      |             |
| `--yds-color-background-warning`<br>`BACKGROUND_WARNING` | warning-background             | `#feb054` / `info-orange-40`                     |             |
| `--yds-color-background-error`<br>`BACKGROUND_ERROR` | error-background               | `#f5517a` / `red-40`                             |             |
| `--yds-color-background-opinion-article`<br>`BACKGROUND_OPINION_ARTICLE` | opinion-article-background     | `#3d5483` / `info-deep-blue-60`                  |             |
| `--yds-color-background-list`<br>`BACKGROUND_LIST` | background-list                | `#131415` / `background`                         |             |
| `--yds-color-background-dropdown`<br>`BACKGROUND_DROPDOWN` | background-dropdown            | `#292b2d` / `gray-80`                            |             |
| `--yds-color-background-variant-2`<br>`BACKGROUND_VARIANT_2` | background-variant-2           | `#292b2d` / `gray-80`                            |             |
| `--yds-color-background-interactive-variant`<br>`BACKGROUND_INTERACTIVE_VARIANT` | background-interactive-variant | `#131415` / `background`                         |             |
| `--yds-color-background-list-variant`<br>`BACKGROUND_LIST_VARIANT` | background-list-variant        | `rgba(255, 255, 255, 0.08)` / `white-opacity-5`  |             |
| `--yds-color-background-list-accent`<br>`BACKGROUND_LIST_ACCENT` | background-list-accent         | `#650101` / `news-orange-95`                     |             |

  </TabItem>
</Tabs>

## Text

Text tokens define readable and consistent text colors across themes and surfaces. They cover default and inverted text, placeholder text, emphasis levels, and disabled states.

<Tabs groupId="theme">
  <TabItem value="light" label="Light" default>

| CSS / JS     | Token                    | Value                                      | Description                                                                                        |
| ----------- | ------------------------ | ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `--yds-color-text-default`<br>`TEXT_DEFAULT` | default-text             | `#131415` / `gray-95`                      | Primary text color; Link text; form field descriptions.                                            |
| `--yds-color-text-negative`<br>`TEXT_NEGATIVE` | negative-text            | `#f8f9fa` / `gray-5`                       | Text on inverted backgrounds (eg. Primary Button text).                                            |
| `--yds-color-text-input-placeholder`<br>`TEXT_INPUT_PLACEHOLDER` | input-placeholder-text   | `#4a4f54` / `gray-60`                      | Textual form field placeholder text color.                                                         |
| `--yds-color-text-high-emphasis`<br>`TEXT_HIGH_EMPHASIS` | high-emphasis-text       | `rgba(0, 0, 0, 0.79)` / `black-opacity-70` | Text color for important metadata.                                                                 |
| `--yds-color-text-medium-emphasis`<br>`TEXT_MEDIUM_EMPHASIS` | medium-emphasis-text     | `rgba(0, 0, 0, 0.70)` / `black-opacity-60` | Text color for secondary metadata.                                                                 |
| `--yds-color-text-disabled`<br>`TEXT_DISABLED` | disabled-text            | `rgba(0, 0, 0, 0.29)` / `black-opacity-40` | Disabled control text color (eg. Button, Input, Checkbox, Radio).                                  |
| `--yds-color-text-light`<br>`TEXT_LIGHT` | light-text               | `#f8f9fa` / `gray-5`                       | Theme-independent light text for dark backgrounds.                                                 |
| `--yds-color-text-dark`<br>`TEXT_DARK` | dark-text                | `#131415` / `gray-95`                      | Theme-independent dark text for light backgrounds.                                                 |
| `--yds-color-text-light-high-contrast`<br>`TEXT_LIGHT_HIGH_CONTRAST` | light-high-contrast-text | `#ffffff` / `white`                        | Theme-independent light text for colored backgrounds (eg. Opinion and Yle Corporate Tag variants). |
| `--yds-color-text-feedback-live`<br>`TEXT_FEEDBACK_LIVE` | feedback-live-text       | `#ffffff` / `light-high-contrast-text`     | Text color for feedback-live background (eg. Live Tag text).                                       |
| `--yds-color-text-link`<br>`TEXT_LINK` | link-text                | `#131415` / `default-text`                 | Text color for links.                                                                              |

  </TabItem>
  <TabItem value="dark" label="Dark">

| CSS / JS     | Token                    | Value                                            | Description |
| ----------- | ------------------------ | ------------------------------------------------ | ----------- |
| `--yds-color-text-default`<br>`TEXT_DEFAULT` | default-text             | `#f8f9fa` / `gray-5`                             |             |
| `--yds-color-text-negative`<br>`TEXT_NEGATIVE` | negative-text            | `#131415` / `gray-95`                            |             |
| `--yds-color-text-input-placeholder`<br>`TEXT_INPUT_PLACEHOLDER` | input-placeholder-text   | `#878a8b` / `gray-50`                            |             |
| `--yds-color-text-high-emphasis`<br>`TEXT_HIGH_EMPHASIS` | high-emphasis-text       | `rgba(255, 255, 255, 0.85)` / `white-opacity-70` |             |
| `--yds-color-text-medium-emphasis`<br>`TEXT_MEDIUM_EMPHASIS` | medium-emphasis-text     | `rgba(255, 255, 255, 0.71)` / `white-opacity-60` |             |
| `--yds-color-text-disabled`<br>`TEXT_DISABLED` | disabled-text            | `rgba(255, 255, 255, 0.30)` / `white-opacity-40` |             |
| `--yds-color-text-light`<br>`TEXT_LIGHT` | light-text               | `#f8f9fa` / `gray-5`                             |             |
| `--yds-color-text-dark`<br>`TEXT_DARK` | dark-text                | `#131415` / `gray-95`                            |             |
| `--yds-color-text-light-high-contrast`<br>`TEXT_LIGHT_HIGH_CONTRAST` | light-high-contrast-text | `#ffffff` / `white`                              |             |
| `--yds-color-text-feedback-live`<br>`TEXT_FEEDBACK_LIVE` | feedback-live-text       | `#ffffff` / `light-high-contrast-text`           |             |
| `--yds-color-text-link`<br>`TEXT_LINK` | link-text                | `#131415` / `default-text`                       |             |

  </TabItem>
</Tabs>

## Action

Action tokens are used for interactive elements and their states, such as buttons, checkboxes, radios, and selectable components. They define primary and secondary actions, hover/active variants, disabled states, and destructive actions.

<Tabs groupId="theme">
  <TabItem value="light" label="Light" default>

| CSS / JS     | Token                         | Value                                      | Description                                                                                   |
| ----------- | ----------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `--yds-color-action-primary`<br>`ACTION_PRIMARY` | primary-action                | `#131415` / `gray-95`                      | Primary action background color (eg. Primary Button background; Checkbox/Radio).              |
| `--yds-color-action-primary-variant`<br>`ACTION_PRIMARY_VARIANT` | primary-action-variant        | `rgba(0, 0, 0, 0.70)` / `black-opacity-60` | Primary action hover/active states background.                                                |
| `--yds-color-action-secondary`<br>`ACTION_SECONDARY` | secondary-action              | `rgba(0, 0, 0, 0.05)` / `black-opacity-10` | Secondary action alternative state (eg. Secondary Button hover background).                   |
| `--yds-color-action-secondary-variant`<br>`ACTION_SECONDARY_VARIANT` | secondary-action-variant      | `rgba(0, 0, 0, 0.09)` / `black-opacity-20` | Secondary hover/active states background (eg. MenuItem hover; Link hover; ButtonGroup hover). |
| `--yds-color-action-disabled`<br>`ACTION_DISABLED` | disabled-action               | `rgba(0, 0, 0, 0.15)` / `black-opacity-30` | Disabled action color (eg. Primary Button).                                                   |
| `--yds-color-action-danger-primary`<br>`ACTION_DANGER_PRIMARY` | danger-primary-action         | `#d10b3d` / `red-60`                       | Destructive action (eg. delete button background).                                            |
| `--yds-color-action-danger-primary-variant`<br>`ACTION_DANGER_PRIMARY_VARIANT` | danger-primary-action-variant | `#e90e43` / `red-50`                       | Destructive action (eg. delete button hover/active states).                                   |
| `--yds-color-action-selected`<br>`ACTION_SELECTED` | selected                      | `#131415` / `gray-95`                      | Togglable action selected state background (eg. ButtonGroup / SectionTab).                    |
| `--yds-color-action-unselected`<br>`ACTION_UNSELECTED` | unselected                    | `#e8e9eb` / `gray-20`                      | Togglable action unselected state background (eg. ButtonGroup / SectionTabs / TagFilter).     |

  </TabItem>
  <TabItem value="dark" label="Dark">

| CSS / JS     | Token                         | Value                                            | Description |
| ----------- | ----------------------------- | ------------------------------------------------ | ----------- |
| `--yds-color-action-primary`<br>`ACTION_PRIMARY` | primary-action                | `#f8f9fa` / `gray-5`                             |             |
| `--yds-color-action-primary-variant`<br>`ACTION_PRIMARY_VARIANT` | primary-action-variant        | `rgba(255, 255, 255, 0.71)` / `white-opacity-60` |             |
| `--yds-color-action-secondary`<br>`ACTION_SECONDARY` | secondary-action              | `rgba(255, 255, 255, 0.08)` / `white-opacity-5`  |             |
| `--yds-color-action-secondary-variant`<br>`ACTION_SECONDARY_VARIANT` | secondary-action-variant      | `rgba(255, 255, 255, 0.17)` / `white-opacity-20` |             |
| `--yds-color-action-disabled`<br>`ACTION_DISABLED` | disabled-action               | `rgba(255, 255, 255, 0.21)` / `white-opacity-30` |             |
| `--yds-color-action-danger-primary`<br>`ACTION_DANGER_PRIMARY` | danger-primary-action         | `#f77898` / `red-30`                             |             |
| `--yds-color-action-danger-primary-variant`<br>`ACTION_DANGER_PRIMARY_VARIANT` | danger-primary-action-variant | `#f5517a` / `red-40`                             |             |
| `--yds-color-action-selected`<br>`ACTION_SELECTED` | selected                      | `#f8f9fa` / `gray-5`                             |             |
| `--yds-color-action-unselected`<br>`ACTION_UNSELECTED` | unselected                    | `#323639` / `gray-70`                            |             |

  </TabItem>
</Tabs>

## Border

Border tokens define outlines and separators used to structure UI components. They cover default and disabled borders, focus rings, separators, and borders for inverted surfaces.

<Tabs groupId="theme">
  <TabItem value="light" label="Light" default>

| CSS / JS     | Token                  | Value                                      | Description                                  |
| ----------- | ---------------------- | ------------------------------------------ | -------------------------------------------- |
| `--yds-color-border`<br>`BORDER` | border                 | `#131415` / `gray-95`                      | Default Input, Textarea, Select border       |
| `--yds-color-border-disabled`<br>`BORDER_DISABLED` | disabled-border        | `rgba(0, 0, 0, 0.29)` / `black-opacity-40` | Disabled Input, Checkbox border              |
| `--yds-color-border-primary-focus`<br>`BORDER_PRIMARY_FOCUS` | primary-focus-border   | `#009cb5` / `turquoise-60`                 | Focus ring for interactive elements          |
| `--yds-color-border-secondary-focus`<br>`BORDER_SECONDARY_FOCUS` | secondary-focus-border | `#131415` / `gray-95`                      | Alternative focus ring color                 |
| `--yds-color-border-separator`<br>`BORDER_SEPARATOR` | separator              | `rgba(0, 0, 0, 0.09)` / `black-opacity-20` | Menu separator lines; Dialog content borders |
| `--yds-color-border-negative`<br>`BORDER_NEGATIVE` | negative-border        | `#ffffff` / `background`                   | Border for elements on inverted backgrounds  |

  </TabItem>
  <TabItem value="dark" label="Dark">

| CSS / JS     | Token                  | Value                                            | Description |
| ----------- | ---------------------- | ------------------------------------------------ | ----------- |
| `--yds-color-border`<br>`BORDER` | border                 | `#f8f9fa` / `gray-5`                             |             |
| `--yds-color-border-disabled`<br>`BORDER_DISABLED` | disabled-border        | `rgba(255, 255, 255, 0.30)` / `white-opacity-40` |             |
| `--yds-color-border-primary-focus`<br>`BORDER_PRIMARY_FOCUS` | primary-focus-border   | `#29ccde` / `turquoise-40`                       |             |
| `--yds-color-border-secondary-focus`<br>`BORDER_SECONDARY_FOCUS` | secondary-focus-border | `#f8f9fa` / `gray-5`                             |             |
| `--yds-color-border-separator`<br>`BORDER_SEPARATOR` | separator              | `rgba(255, 255, 255, 0.13)` / `white-opacity-10` |             |
| `--yds-color-border-negative`<br>`BORDER_NEGATIVE` | negative-border        | `#131415` / `background`                         |             |

  </TabItem>
</Tabs>

## Illustrative icons

Illustrative icon tokens define the primary and secondary colors used in illustrative iconography and illustrations. Use them to keep illustration accents consistent with the theme.

<Tabs groupId="theme">
  <TabItem value="light" label="Light" default>

| CSS / JS     | Token                       | Value                      | Description                                                                                                                    |
| ----------- | --------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `--yds-color-illustrative-icons-icon-primary`<br>`ILLUSTRATIVE_ICONS_ICON_PRIMARY` | illustrative-icon-primary   | `#131415` / `gray-95`      | Primary color for illustrative icons. Used as the background for illustrative icons.                                           |
| `--yds-color-illustrative-icons-icon-secondary`<br>`ILLUSTRATIVE_ICONS_ICON_SECONDARY` | illustrative-icon-secondary | `#5ddbe9` / `turquoise-30` | Secondary/accent color for illustrations. Used for the lines and other elements of illustrative icons, not for the background. |

  </TabItem>
  <TabItem value="dark" label="Dark">

| CSS / JS     | Token                       | Value                      | Description |
| ----------- | --------------------------- | -------------------------- | ----------- |
| `--yds-color-illustrative-icons-icon-primary`<br>`ILLUSTRATIVE_ICONS_ICON_PRIMARY` | illustrative-icon-primary   | `#f8f9fa` / `gray-5`       |             |
| `--yds-color-illustrative-icons-icon-secondary`<br>`ILLUSTRATIVE_ICONS_ICON_SECONDARY` | illustrative-icon-secondary | `#009cb5` / `turquoise-60` |             |

  </TabItem>
</Tabs>

## Player

Player tokens define colors used in media player UI elements, such as the progress track and the progress indicator.

<Tabs groupId="theme">
  <TabItem value="light" label="Light" default>

| CSS / JS     | Token                     | Value                                            | Description                                  |
| ----------- | ------------------------- | ------------------------------------------------ | -------------------------------------------- |
| `--yds-color-player-progress-bar`<br>`PLAYER_PROGRESS_BAR` | player-progress-bar       | `rgba(255, 255, 255, 0.30)` / `white-opacity-40` | Media player progress bar track background   |
| `--yds-color-player-progress-indicator`<br>`PLAYER_PROGRESS_INDICATOR` | player-progress-indicator | `#29ccde` / `turquoise-40`                       | Media player progress indicator/filled track |

  </TabItem>
  <TabItem value="dark" label="Dark">

| CSS / JS     | Token                     | Value                                            | Description |
| ----------- | ------------------------- | ------------------------------------------------ | ----------- |
| `--yds-color-player-progress-bar`<br>`PLAYER_PROGRESS_BAR` | player-progress-bar       | `rgba(255, 255, 255, 0.30)` / `white-opacity-40` |             |
| `--yds-color-player-progress-indicator`<br>`PLAYER_PROGRESS_INDICATOR` | player-progress-indicator | `#29ccde` / `turquoise-40`                       |             |

  </TabItem>
</Tabs>

## Spinner

Spinner tokens define spinner foreground and track colors across variants, including default, negative, and highlight variants. Use these tokens for loading indicators in different surface contexts.

<Tabs groupId="theme">
  <TabItem value="light" label="Light" default>

| CSS / JS     | Token               | Value                      | Description                                   |
| ----------- | ------------------- | -------------------------- | --------------------------------------------- |
| `--yds-color-spinner-default`<br>`SPINNER_DEFAULT` | default             | `#131415` / `gray-95`      | Spinner default variant foreground            |
| `--yds-color-spinner-negative`<br>`SPINNER_NEGATIVE` | negative            | `#ffffff` / `white`        | Spinner negative variant foreground           |
| `--yds-color-spinner-highlight-default`<br>`SPINNER_HIGHLIGHT_DEFAULT` | highlight-default   | `#009cb5` / `turquoise-60` | Spinner highlight variant foreground          |
| `--yds-color-spinner-highlight-negative`<br>`SPINNER_HIGHLIGHT_NEGATIVE` | highlight-negative  | `#29ccde` / `turquoise-40` | Spinner highlight-negative variant foreground |
| `--yds-color-spinner-background-default`<br>`SPINNER_BACKGROUND_DEFAULT` | background-default  | `#d8d9db` / `gray-30`      | Spinner default variant track background      |
| `--yds-color-spinner-background-negative`<br>`SPINNER_BACKGROUND_NEGATIVE` | background-negative | `#292b2d` / `gray-80`      | Spinner negative variant track background     |

  </TabItem>
  <TabItem value="dark" label="Dark">

| CSS / JS     | Token               | Value                      | Description |
| ----------- | ------------------- | -------------------------- | ----------- |
| `--yds-color-spinner-default`<br>`SPINNER_DEFAULT` | default             | `#ffffff` / `white`        |             |
| `--yds-color-spinner-negative`<br>`SPINNER_NEGATIVE` | negative            | `#131415` / `gray-95`      |             |
| `--yds-color-spinner-highlight-default`<br>`SPINNER_HIGHLIGHT_DEFAULT` | highlight-default   | `#29ccde` / `turquoise-40` |             |
| `--yds-color-spinner-highlight-negative`<br>`SPINNER_HIGHLIGHT_NEGATIVE` | highlight-negative  | `#009cb5` / `turquoise-60` |             |
| `--yds-color-spinner-background-default`<br>`SPINNER_BACKGROUND_DEFAULT` | background-default  | `#292b2d` / `gray-80`      |             |
| `--yds-color-spinner-background-negative`<br>`SPINNER_BACKGROUND_NEGATIVE` | background-negative | `#d8d9db` / `gray-30`      |             |

  </TabItem>
</Tabs>

## Feedback

Feedback tokens are used to communicate status and validation states in the UI. They cover highlight, error, warning, success, and live indicators for components and messages.

<Tabs groupId="theme">
  <TabItem value="light" label="Light" default>

| CSS / JS     | Token     | Value                        | Description                                                                                           |
| ----------- | --------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `--yds-color-feedback-highlight`<br>`FEEDBACK_HIGHLIGHT` | highlight | `#009cb5` / `turquoise-60`   | Accent color; NavigationTab indicator; Switch checked. Guides the user forward in the user interface. |
| `--yds-color-feedback-error`<br>`FEEDBACK_ERROR` | error     | `#d10b3d` / `red-60`         | Error state for form controls and messages                                                            |
| `--yds-color-feedback-warning`<br>`FEEDBACK_WARNING` | warning   | `#f1722a` / `orange-60`      | Warning state indicator                                                                               |
| `--yds-color-feedback-success`<br>`FEEDBACK_SUCCESS` | success   | `#058657` / `green-70`       | Success state for form controls                                                                       |
| `--yds-color-feedback-live`<br>`FEEDBACK_LIVE` | live      | `#e90e43` / `red-50`         | Live broadcast indicator                                                                              |
| `--yds-color-feedback-accent`<br>`FEEDBACK_ACCENT` | accent    | `#f26659` / `news-orange-50` | Accent color derived from infographic palette for simple data visualisation.                          |

  </TabItem>
  <TabItem value="dark" label="Dark">

| CSS / JS     | Token     | Value                        | Description |
| ----------- | --------- | ---------------------------- | ----------- |
| `--yds-color-feedback-highlight`<br>`FEEDBACK_HIGHLIGHT` | highlight | `#29ccde` / `turquoise-40`   |             |
| `--yds-color-feedback-error`<br>`FEEDBACK_ERROR` | error     | `#f5517a` / `red-40`         |             |
| `--yds-color-feedback-warning`<br>`FEEDBACK_WARNING` | warning   | `#ff9c31` / `orange-40`      |             |
| `--yds-color-feedback-success`<br>`FEEDBACK_SUCCESS` | success   | `#03e592` / `green-40`       |             |
| `--yds-color-feedback-live`<br>`FEEDBACK_LIVE` | live      | `#e90e43` / `red-50`         |             |
| `--yds-color-feedback-accent`<br>`FEEDBACK_ACCENT` | accent    | `#f57f74` / `news-orange-40` |             |

  </TabItem>
</Tabs>

## Logo

Logo tokens define colors used for Yle and channel logos, including background and text variants. Use these tokens for logo components and brand marks across themes.

<Tabs groupId="theme">
  <TabItem value="light" label="Light" default>

| CSS / JS     | Token                       | Value                         | Description                           |
| ----------- | --------------------------- | ----------------------------- | ------------------------------------- |
| `--yds-color-logo-yle-background-brand`<br>`LOGO_YLE_BACKGROUND_BRAND` | yle-logo-background-brand   | `#00b4c8` / `turquoise-50`    | Yle logo background (brand variant)   |
| `--yds-color-logo-tv1`<br>`LOGO_TV1` | tv1-logo                    | `#3311aa` / `yle-tv-1`        | Yle TV1 brand color                   |
| `--yds-color-logo-tv-2`<br>`LOGO_TV_2` | tv-2-logo                   | `#cb0fd0` / `yle-tv-2`        | Yle TV2 brand color                   |
| `--yds-color-logo-yle-teema`<br>`LOGO_YLE_TEEMA` | yle-teema-logo              | `#fe8300` / `yle-teema`       | Yle Teema brand color                 |
| `--yds-color-logo-yle-fem`<br>`LOGO_YLE_FEM` | yle-fem-logo                | `#a3bd2f` / `yle-fem`         | Yle Fem brand color                   |
| `--yds-color-logo-lastenareena`<br>`LOGO_LASTENAREENA` | lastenareena-logo           | `#feb500` / `lastenareena`    | Lasten Areena brand color             |
| `--yds-color-logo-yle-radio-1`<br>`LOGO_YLE_RADIO_1` | yle-radio-1-logo            | `#dc006a` / `yle-radio-1`     | Yle Radio 1 brand color               |
| `--yds-color-logo-yle-radio-suomi`<br>`LOGO_YLE_RADIO_SUOMI` | yle-radio-suomi-logo        | `#0000e6` / `yle-radio-suomi` | Yle Radio Suomi brand color           |
| `--yds-color-logo-yle-x`<br>`LOGO_YLE_X` | yle-x-logo                  | `#fd2b77` / `yle-x`           | Yle X brand color                     |
| `--yds-color-logo-yle-x3m`<br>`LOGO_YLE_X3M` | yle-x3m-logo                | `#ff4c20` / `yle-x3m`         | Yle X3M brand color                   |
| `--yds-color-logo-yle-vega`<br>`LOGO_YLE_VEGA` | yle-vega-logo               | `#169bd4` / `yle-vega`        | Yle Vega brand color                  |
| `--yds-color-logo-yle-klassinen`<br>`LOGO_YLE_KLASSINEN` | yle-klassinen-logo          | `#0f7b87` / `yle-klassinen`   | Yle Klassinen brand color             |
| `--yds-color-logo-yle-sami-radio`<br>`LOGO_YLE_SAMI_RADIO` | yle-sami-radio-logo         | `#0049bf` / `yle-sami-radio`  | Yle Sámi Radio brand color            |
| `--yds-color-logo-areena`<br>`LOGO_AREENA` | areena-logo                 | `#29ccde` / `turquoise-40`    | Yle Areena brand color                |
| `--yds-color-logo-yle-background-default`<br>`LOGO_YLE_BACKGROUND_DEFAULT` | yle-logo-background-default | `#131415` / `default-text`    | Yle logo background (default variant) |
| `--yds-color-logo-yle-text`<br>`LOGO_YLE_TEXT` | yle-logo-text               | `#f8f9fa` / `negative-text`   | Yle logo text color                   |
| `--yds-color-logo-background`<br>`LOGO_BACKGROUND` | logo-background             | `#000000` / `black`           | Generic logo background color         |
| `--yds-color-logo-nega`<br>`LOGO_NEGA` | logo-nega                   | `#ffffff` / `white`           | Logo negative/inverted variant        |
| `--yds-color-logo-text`<br>`LOGO_TEXT` | logo-text                   | `#ffffff` / `white`           | Logo text color                       |

  </TabItem>
  <TabItem value="dark" label="Dark">

| CSS / JS     | Token                       | Value                           | Description |
| ----------- | --------------------------- | ------------------------------- | ----------- |
| `--yds-color-logo-yle-background-brand`<br>`LOGO_YLE_BACKGROUND_BRAND` | yle-logo-background-brand   | `#f8f9fa` / `gray-5`            |             |
| `--yds-color-logo-tv1`<br>`LOGO_TV1` | tv1-logo                    | `#3311aa` / `yle-tv-1`          |             |
| `--yds-color-logo-tv-2`<br>`LOGO_TV_2` | tv-2-logo                   | `#cb0fd0` / `yle-tv-2`          |             |
| `--yds-color-logo-yle-teema`<br>`LOGO_YLE_TEEMA` | yle-teema-logo              | `#fe8300` / `yle-teema`         |             |
| `--yds-color-logo-yle-fem`<br>`LOGO_YLE_FEM` | yle-fem-logo                | `#a3bd2f` / `yle-fem`           |             |
| `--yds-color-logo-lastenareena`<br>`LOGO_LASTENAREENA` | lastenareena-logo           | `#feb500` / `lastenareena`      |             |
| `--yds-color-logo-yle-radio-1`<br>`LOGO_YLE_RADIO_1` | yle-radio-1-logo            | `#dc006a` / `yle-radio-1`       |             |
| `--yds-color-logo-yle-radio-suomi`<br>`LOGO_YLE_RADIO_SUOMI` | yle-radio-suomi-logo        | `#00b9eb` / `yle-radio-suomi-2` |             |
| `--yds-color-logo-yle-x`<br>`LOGO_YLE_X` | yle-x-logo                  | `#fd2b77` / `yle-x`             |             |
| `--yds-color-logo-yle-x3m`<br>`LOGO_YLE_X3M` | yle-x3m-logo                | `#ff4c20` / `yle-x3m`           |             |
| `--yds-color-logo-yle-vega`<br>`LOGO_YLE_VEGA` | yle-vega-logo               | `#169bd4` / `yle-vega`          |             |
| `--yds-color-logo-yle-klassinen`<br>`LOGO_YLE_KLASSINEN` | yle-klassinen-logo          | `#0f7b87` / `yle-klassinen`     |             |
| `--yds-color-logo-yle-sami-radio`<br>`LOGO_YLE_SAMI_RADIO` | yle-sami-radio-logo         | `#0049bf` / `yle-sami-radio`    |             |
| `--yds-color-logo-areena`<br>`LOGO_AREENA` | areena-logo                 | `#29ccde` / `turquoise-40`      |             |
| `--yds-color-logo-yle-background-default`<br>`LOGO_YLE_BACKGROUND_DEFAULT` | yle-logo-background-default | `#f8f9fa` / `default-text`      |             |
| `--yds-color-logo-yle-text`<br>`LOGO_YLE_TEXT` | yle-logo-text               | `#131415` / `negative-text`     |             |
| `--yds-color-logo-background`<br>`LOGO_BACKGROUND` | logo-background             | `#ffffff` / `white`             |             |
| `--yds-color-logo-nega`<br>`LOGO_NEGA` | logo-nega                   | `#ffffff` / `white`             |             |
| `--yds-color-logo-text`<br>`LOGO_TEXT` | logo-text                   | `#000000` / `black`             |             |

  </TabItem>
</Tabs>

## Brand

Yle’s brand color is used only in the logo and not in UI components. Turquoise is used in the user interface.

<Tabs groupId="theme">
  <TabItem value="light" label="Light" default>

| CSS / JS     | Token     | Value                      | Description                                                                      |
| ----------- | --------- | -------------------------- | -------------------------------------------------------------------------------- |
| `--yds-color-brand-yle`<br>`BRAND_YLE` | yle-brand | `#00b4c8` / `turquoise-50` | Used in the Yle logo and not as a user interface color. Primary Yle brand color. |

  </TabItem>
  <TabItem value="dark" label="Dark">

| CSS / JS     | Token     | Value                      | Description |
| ----------- | --------- | -------------------------- | ----------- |
| `--yds-color-brand-yle`<br>`BRAND_YLE` | yle-brand | `#00b4c8` / `turquoise-50` |             |

  </TabItem>
</Tabs>

## Tag

Tag tokens define background colors for different tag types and tag interaction variants. Use these tokens for tags such as live, default, opinion, corporate, neutral, and action-based tag styles.

<Tabs groupId="theme">
  <TabItem value="light" label="Light" default>

| CSS / JS     | Token                        | Value                                      | Description                                                                                                                                                                   |
| ----------- | ---------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--yds-color-tag-live`<br>`TAG_LIVE` | live-tag                     | `#e90e43` / `red-50`                       | Live Tag Tag background.Used for live, right now, online, and chat content. Highlights time-sensitive or currently active events and updates.                                 |
| `--yds-color-tag-default`<br>`TAG_DEFAULT` | default-tag                  | `#131415` / `gray-95`                      | Default Tag background. Used as the primary tag for content categorization, especially in editorial and Areena content such as new episodes, seasons, and curated highlights. |
| `--yds-color-tag-opinion`<br>`TAG_OPINION` | opinion-tag                  | `#3d5483` / `info-deep-blue-60`            | Opinion Tag background. Used to mark opinion-based conten                                                                                                                     |
| `--yds-color-tag-yle-corporate`<br>`TAG_YLE_CORPORATE` | yle-corporate-tag            | `#00809c` / `turquoise-70`                 | Yle Corporate Tag background. Used in Yle corporate and official communication content.                                                                                       |
| `--yds-color-tag-primary-action`<br>`TAG_PRIMARY_ACTION` | primary-action-tag           | `#131415` / `gray-95`                      | TagLink primary variant background. Background for interactive TagLink primary variants used for navigation and filtering.                                                    |
| `--yds-color-tag-primary-action-variant`<br>`TAG_PRIMARY_ACTION_VARIANT` | primary-action-variant-tag   | `rgba(0, 0, 0, 0.70)` / `black-opacity-60` | TagLink primary variant hover state. Hover and active state background for primary TagLink variants.                                                                          |
| `--yds-color-tag-secondary-action`<br>`TAG_SECONDARY_ACTION` | secondary-action-tag         | `rgba(0, 0, 0, 0.05)` / `black-opacity-10` | TagLink secondary variant background. Background for secondary or text-based TagLink variants used in less prominent interactions.                                            |
| `--yds-color-tag-secondary-action-variant`<br>`TAG_SECONDARY_ACTION_VARIANT` | secondary-action-variant-tag | `rgba(0, 0, 0, 0.02)` / `black-opacity-5`  | TagLink secondary/text variant hover state. Hover and active state background for secondary or text-based TagLink variants.                                                   |
| `--yds-color-tag-neutral`<br>`TAG_NEUTRAL` | neutral-tag                  | `#e8e9eb` / `gray-20`                      | Neutral Tag background. Used when the tag should not visually dominate, such as user-selected filters, preferences, or contextual metadata.                                   |

  </TabItem>
  <TabItem value="dark" label="Dark">

| CSS / JS     | Token                        | Value                                            | Description |
| ----------- | ---------------------------- | ------------------------------------------------ | ----------- |
| `--yds-color-tag-live`<br>`TAG_LIVE` | live-tag                     | `#e90e43` / `red-50`                             |             |
| `--yds-color-tag-default`<br>`TAG_DEFAULT` | default-tag                  | `#ffffff` / `white`                              |             |
| `--yds-color-tag-opinion`<br>`TAG_OPINION` | opinion-tag                  | `#3d5483` / `info-deep-blue-60`                  |             |
| `--yds-color-tag-yle-corporate`<br>`TAG_YLE_CORPORATE` | yle-corporate-tag            | `#00809c` / `turquoise-70`                       |             |
| `--yds-color-tag-primary-action`<br>`TAG_PRIMARY_ACTION` | primary-action-tag           | `#f8f9fa` / `gray-5`                             |             |
| `--yds-color-tag-primary-action-variant`<br>`TAG_PRIMARY_ACTION_VARIANT` | primary-action-variant-tag   | `rgba(255, 255, 255, 0.71)` / `white-opacity-60` |             |
| `--yds-color-tag-secondary-action`<br>`TAG_SECONDARY_ACTION` | secondary-action-tag         | `rgba(255, 255, 255, 0.13)` / `white-opacity-10` |             |
| `--yds-color-tag-secondary-action-variant`<br>`TAG_SECONDARY_ACTION_VARIANT` | secondary-action-variant-tag | `rgba(255, 255, 255, 0.08)` / `white-opacity-5`  |             |
| `--yds-color-tag-neutral`<br>`TAG_NEUTRAL` | neutral-tag                  | `#323639` / `gray-70`                            |             |

  </TabItem>
</Tabs>

## Shadow

Shadow tokens define elevation through shadow color values. Use these tokens for layered surfaces and components that require visual separation from the background.

<Tabs groupId="theme">
  <TabItem value="light" label="Light" default>

| CSS / JS     | Token | Value                 | Description                           |
| ----------- | ----- | --------------------- | ------------------------------------- |
| `--yds-color-shadow-s`<br>`SHADOW_S` | s     | `rgba(0, 0, 0, 0.15)` | Small shadow color, subtle elevation  |
| `--yds-color-shadow-m`<br>`SHADOW_M` | m     | `rgba(0, 0, 0, 0.15)` | Medium shadow color, medium elevation |
| `--yds-color-shadow-l`<br>`SHADOW_L` | l     | `rgba(0, 0, 0, 0.41)` | Large shadow color, high elevation    |

  </TabItem>
  <TabItem value="dark" label="Dark">

| CSS / JS     | Token | Value                 | Description |
| ----------- | ----- | --------------------- | ----------- |
| `--yds-color-shadow-s`<br>`SHADOW_S` | s     | `rgba(0, 0, 0, 0.70)` |             |
| `--yds-color-shadow-m`<br>`SHADOW_M` | m     | `rgba(0, 0, 0, 0.70)` |             |
| `--yds-color-shadow-l`<br>`SHADOW_L` | l     | `rgba(0, 0, 0, 0.87)` |             |

  </TabItem>
</Tabs>

## Tietaja

Tietäjä tokens define theme colors specific to the Tietäjä game UI, built on top of the YDS dark theme. Use these tokens for Tietäjä-specific components such as player cards and score-related highlights.

<Tabs groupId="theme">
  <TabItem value="light" label="Light" default>

| CSS / JS     | Token                  | Value                                      | Description                            |
| ----------- | ---------------------- | ------------------------------------------ | -------------------------------------- |
| `--yds-color-tietaja-background-player-card`<br>`TIETAJA_BACKGROUND_PLAYER_CARD` | background-player-card | `rgba(0, 0, 0, 0.15)` / `black-opacity-30` | Tietäjä game player card background.   |
| `--yds-color-tietaja-text-score`<br>`TIETAJA_TEXT_SCORE` | text-score             | `#009cb5` / `highlight`                    | Tietäjä game score text color.         |
| `--yds-color-tietaja-border-highlight`<br>`TIETAJA_BORDER_HIGHLIGHT` | border-highlight       | `#009cb5` / `highlight`                    | Tietäjä game highlighted border color. |

  </TabItem>
  <TabItem value="dark" label="Dark">

| CSS / JS     | Token                  | Value                                      | Description |
| ----------- | ---------------------- | ------------------------------------------ | ----------- |
| `--yds-color-tietaja-background-player-card`<br>`TIETAJA_BACKGROUND_PLAYER_CARD` | background-player-card | `rgba(0, 0, 0, 0.29)` / `black-opacity-40` |             |
| `--yds-color-tietaja-text-score`<br>`TIETAJA_TEXT_SCORE` | text-score             | `#29ccde` / `highlight`                    |             |
| `--yds-color-tietaja-border-highlight`<br>`TIETAJA_BORDER_HIGHLIGHT` | border-highlight       | `#29ccde` / `highlight`                    |             |

  </TabItem>
</Tabs>

# Transitions

<Resources
  storybookUrl="https://ds-storybook.test.yle.fi/?path=/docs/design-tokens-motion--docs"
  githubUrl="https://github.com/Yleisradio/yle-design-system/blob/main/docs/design-tokens/transitions.mdx"
/>

Transition tokens specify standardized movement related values. They provide a shared language for motion, ensuring consistency and predictability.

## Duration

Duration defines how long an animation takes. Consistent values create clear hierarchy and pacing, from short micro-interactions to longer full-screen transitions. Use duration to make motion feel smooth and appropriate for each context.

| CSS / JS     | Token            | Value    | Description                                                                                |
| ----------- | ---------------- | -------- | ------------------------------------------------------------------------------------------ |
| `--yds-transition-duration-instant`<br>`transition.DURATION_INSTANT` | duration/instant | `0ms`    | Immediate response with no visible animation.                                              |
| `--yds-transition-duration-xxs`<br>`transition.DURATION_XXS` | duration/xxs     | `70ms`   | Very short micro-transitions or immediate interactions, such as a button color change.     |
| `--yds-transition-duration-xs`<br>`transition.DURATION_XS` | duration/xs      | `150ms`  | Used in small interactions, such as hover effects.                                         |
| `--yds-transition-duration-s`<br>`transition.DURATION_S` | duration/s       | `250ms`  | Suitable for general transitions, such as card flips or button press feedback.             |
| `--yds-transition-duration-m`<br>`transition.DURATION_M` | duration/m       | `450ms`  | A good choice for medium-length transitions, such as opening a modal window.               |
| `--yds-transition-duration-l`<br>`transition.DURATION_L` | duration/l       | `750ms`  | For large or full-screen transitions.                                                      |
| `--yds-transition-duration-xl`<br>`transition.DURATION_XL` | duration/xl      | `1000ms` | Used in longer animations that should feel calm and unhurried.                             |
| `--yds-transition-duration-xxl`<br>`transition.DURATION_XXL` | duration/xxl     | `2000ms` | Very long animations, such as large loading animations or massive full-screen transitions. |

## Delay

Delay defines when an animation starts relative to a user action or another animation. Use it for rhythm and sequencing when multiple elements appear in order. Apply sparingly — delays can reduce responsiveness, so use only when they clearly improve clarity or visual continuity.

| CSS / JS     | Token         | Value    | Description                                        |
| ----------- | ------------- | -------- | -------------------------------------------------- |
| `--yds-transition-delay-xxs`<br>`transition.DELAY_XXS` | delay/xxs     | `70ms`   | Very short delay.                                  |
| `--yds-transition-delay-xs`<br>`transition.DELAY_XS` | delay/xs      | `150ms`  | Short delay for transitions.                       |
| `--yds-transition-delay-s`<br>`transition.DELAY_S` | delay/s       | `250ms`  | Small delays in transitions.                       |
| `--yds-transition-delay-m`<br>`transition.DELAY_M` | delay/m       | `450ms`  | Medium delays.                                     |
| `--yds-transition-delay-l`<br>`transition.DELAY_L` | delay/l       | `750ms`  | Larger delays, for example in modal presentations. |
| `--yds-transition-delay-xl`<br>`transition.DELAY_XL` | delay/xl      | `1000ms` | Long delays in complex animations.                 |
| `--yds-transition-delay-xxl`<br>`transition.DELAY_XXL` | delay/xxl     | `2000ms` | Very long delays in special cases.                 |
| `--yds-transition-delay-instant`<br>`transition.DELAY_INSTANT` | delay/instant | `0ms`    | No delay.                                          |

## Easing

Easing controls how motion accelerates and decelerates, affecting the rhythm and feel of transitions. Different curves — decelerate, accelerate, bounce — support different goals such as guiding attention, emphasizing feedback, or creating expressive moments.

| CSS / JS     | Token            | Value                                 | Description                                                                                |
| ----------- | ---------------- | ------------------------------------- | ------------------------------------------------------------------------------------------ |
| `--yds-transition-easing-dec`<br>`transition.EASING_DEC` | easing/dec       | `cubic-bezier(0.17, 0.84, 0.44, 1.0)` | Used for motions where a smooth stop is desired, for example in element entrances.         |
| `--yds-transition-easing-acc`<br>`transition.EASING_ACC` | easing/acc       | `cubic-bezier(0.84, 0.17, 1, 0.44)`   | Suitable for motions that start softly and end quickly, such as element exits.             |
| `--yds-transition-easing-default`<br>`transition.EASING_DEFAULT` | easing/default   | `cubic-bezier(0.65, 0.05, 0.35, 1.0)` | Base easing for natural animations.                                                        |
| `--yds-transition-easing-exp`<br>`transition.EASING_EXP` | easing/exp       | `cubic-bezier(0.75, 0, 0.17, 1.0)`    | Suitable for emphasized interactions where the motion should feel more lively and dynamic. |
| `--yds-transition-easing-bounce-sm`<br>`transition.EASING_BOUNCE_SM` | easing/bounce-sm | `cubic-bezier(0.6, 0.0, 0.1, 1.3)`    | A small bounce that adds playfulness or attention-grabbing motion to elements.             |
| `--yds-transition-easing-bounce-lg`<br>`transition.EASING_BOUNCE_LG` | easing/bounce-lg | `cubic-bezier(0.6, 0.0, 0.1, 3)`      | A larger bounce used especially in visually important moments, but with moderation.        |
| `--yds-transition-easing-linear`<br>`transition.EASING_LINEAR` | easing/linear    | `cubic-bezier(0, 0, 1, 1)`            | Used for motions where constant speed is required, such as opacity or color changes.       |

## Motion patterns

Read more on how to utilise these tokens in the [motion language principles](/docs/design-principles/motion-language-principles) page.

# Typography

- [Figma](https://www.figma.com/design/U1NzhzFpMpgaIDL7MbbrYE/YDS-Foundation?node-id=101-1729)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/docs/design-tokens-typography--docs)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/design-tokens/typography.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

Typography tokens define text styles including font size, weight, line height, and letter spacing. 

Yle’s primary typeface is **Yle Next**, and the typography scale is available both as a default set and as Yle Next–specific tokens for consistent use across Yle services.

## Default

| CSS / JS     | Token                       | Value               | Description                                                                         |
| ----------- | --------------------------- | ------------------- | ----------------------------------------------------------------------------------- |
| `--yds-typography-default-7xl-bold-*`<br>`typography.DEFAULT_7XL_BOLD_*` | default/7xl-bold            | `56px / 1.25 / 700` | Hero banners; Areena promotional titles                                             |
| `--yds-typography-default-7xl-heavy-*`<br>`typography.DEFAULT_7XL_HEAVY_*` | default/7xl-heavy           | `56px / 1.25 / 900` | Hero banners; maximum emphasis                                                      |
| `--yds-typography-default-7xl-condensed-heavy-*`<br>`typography.DEFAULT_7XL_CONDENSED_HEAVY_*` | default/7xl-condensed-heavy | `56px / 1.25 / 900` | Feature article headings only. |
| `--yds-typography-default-6xl-bold-*`<br>`typography.DEFAULT_6XL_BOLD_*` | default/6xl-bold            | `48px / 1.25 / 700` | Headings in Yle articles and stories; large promotional content; landing pages     |
| `--yds-typography-default-6xl-heavy-*`<br>`typography.DEFAULT_6XL_HEAVY_*` | default/6xl-heavy           | `48px / 1.25 / 900` | Headings in Yle articles and stories; feature article h1 desktop                   |
| `--yds-typography-default-6xl-condensed-heavy-*`<br>`typography.DEFAULT_6XL_CONDENSED_HEAVY_*` | default/6xl-condensed-heavy | `48px / 1.25 / 900` | Feature article headings only. |
| `--yds-typography-default-5xl-bold-*`<br>`typography.DEFAULT_5XL_BOLD_*` | default/5xl-bold            | `40px / 1.25 / 700` | Headings in Yle articles and stories; front page main headlines                    |
| `--yds-typography-default-5xl-heavy-*`<br>`typography.DEFAULT_5XL_HEAVY_*` | default/5xl-heavy           | `40px / 1.25 / 900` | Headings in Yle articles and stories; feature article h1 mobile                    |
| `--yds-typography-default-5xl-condensed-heavy-*`<br>`typography.DEFAULT_5XL_CONDENSED_HEAVY_*` | default/5xl-condensed-heavy | `40px / 1.25 / 900` | Feature article headings only. |
| `--yds-typography-default-4xl-bold-*`<br>`typography.DEFAULT_4XL_BOLD_*` | default/4xl-bold            | `32px / 1.35 / 700` | Headings in Yle articles and stories; ArticleHeading lg; front page card headlines  |
| `--yds-typography-default-4xl-heavy-*`<br>`typography.DEFAULT_4XL_HEAVY_*` | default/4xl-heavy           | `32px / 1.35 / 900` | Headings in Yle articles and stories; article h1 desktop                            |
| `--yds-typography-default-4xl-condensed-heavy-*`<br>`typography.DEFAULT_4XL_CONDENSED_HEAVY_*` | default/4xl-condensed-heavy | `32px / 1.35 / 900` | Feature article headings only. |
| `--yds-typography-default-3xl-bold-*`<br>`typography.DEFAULT_3XL_BOLD_*` | default/3xl-bold            | `28px / 1.35 / 700` | Headings in Yle articles and stories; article page headlines                         |
| `--yds-typography-default-3xl-heavy-*`<br>`typography.DEFAULT_3XL_HEAVY_*` | default/3xl-heavy           | `28px / 1.35 / 900` | Headings in Yle articles and stories; article headlines; strong emphasis            |
| `--yds-typography-default-3xl-condensed-heavy-*`<br>`typography.DEFAULT_3XL_CONDENSED_HEAVY_*` | default/3xl-condensed-heavy | `28px / 1.35 / 900` | Feature article headings only. |
| `--yds-typography-default-2xl-*`<br>`typography.DEFAULT_2XL_*` | default/2xl                 | `24px / 1.35 / 400` | Default weight for text content; section headings; card headlines                  |
| `--yds-typography-default-2xl-bold-*`<br>`typography.DEFAULT_2XL_BOLD_*` | default/2xl-bold            | `24px / 1.35 / 700` | Headings in Yle articles and stories; ArticleHeading lg; Dialog title md           |
| `--yds-typography-default-2xl-heavy-*`<br>`typography.DEFAULT_2XL_HEAVY_*` | default/2xl-heavy           | `24px / 1.35 / 900` | Headings in Yle articles and stories; article h1 mobile; Quote; List/Infobox        |
| `--yds-typography-default-2xl-condensed-bold-*`<br>`typography.DEFAULT_2XL_CONDENSED_BOLD_*` | default/2xl-condensed-bold  | `24px / 1.35 / 700` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-default-2xl-condensed-heavy-*`<br>`typography.DEFAULT_2XL_CONDENSED_HEAVY_*` | default/2xl-condensed-heavy | `24px / 1.35 / 900` | Feature article headings only. |
| `--yds-typography-default-xl-*`<br>`typography.DEFAULT_XL_*` | default/xl                  | `20px / 1.45 / 400` | Default weight for text content; article ingress/lead desktop                       |
| `--yds-typography-default-xl-italic-*`<br>`typography.DEFAULT_XL_ITALIC_*` | default/xl-italic           | `20px / 1.45 / 400` | Yle articles only; correction and update notes. Not used elsewhere.                 |
| `--yds-typography-default-xl-bold-*`<br>`typography.DEFAULT_XL_BOLD_*` | default/xl-bold             | `20px / 1.45 / 700` | Headings in Yle articles and stories; emphasis within body text; ArticleHeading md  |
| `--yds-typography-default-xl-heavy-*`<br>`typography.DEFAULT_XL_HEAVY_*` | default/xl-heavy            | `20px / 1.45 / 900` | Headings in Yle articles and stories; article h2/h3; Quote/List/Infobox              |
| `--yds-typography-default-xl-condensed-*`<br>`typography.DEFAULT_XL_CONDENSED_*` | default/xl-condensed        | `20px / 1.45 / 400` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-default-xl-condensed-bold-*`<br>`typography.DEFAULT_XL_CONDENSED_BOLD_*` | default/xl-condensed-bold   | `20px / 1.45 / 700` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-default-xl-condensed-heavy-*`<br>`typography.DEFAULT_XL_CONDENSED_HEAVY_*` | default/xl-condensed-heavy  | `20px / 1.45 / 900` | Feature article headings only. |
| `--yds-typography-default-l-*`<br>`typography.DEFAULT_L_*` | default/l                   | `18px / 1.45 / 400` | Default weight for text content; article body desktop; Accordion; lists             |
| `--yds-typography-default-l-italic-*`<br>`typography.DEFAULT_L_ITALIC_*` | default/l-italic            | `18px / 1.45 / 400` | Yle articles only; correction and update notes. Not used elsewhere.                  |
| `--yds-typography-default-l-bold-*`<br>`typography.DEFAULT_L_BOLD_*` | default/l-bold              | `18px / 1.45 / 700` | Headings in Yle articles and stories; emphasis within body text; Accordion; Button  |
| `--yds-typography-default-l-heavy-*`<br>`typography.DEFAULT_L_HEAVY_*` | default/l-heavy             | `18px / 1.45 / 900` | Headings in Yle articles and stories; article h3 mobile; manual promo headline       |
| `--yds-typography-default-l-condensed-*`<br>`typography.DEFAULT_L_CONDENSED_*` | default/l-condensed         | `18px / 1.45 / 400` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-default-l-condensed-bold-*`<br>`typography.DEFAULT_L_CONDENSED_BOLD_*` | default/l-condensed-bold    | `18px / 1.45 / 700` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-default-l-condensed-heavy-*`<br>`typography.DEFAULT_L_CONDENSED_HEAVY_*` | default/l-condensed-heavy   | `18px / 1.45 / 900` | Feature article headings only. |
| `--yds-typography-default-m-*`<br>`typography.DEFAULT_M_*` | default/m                   | `16px / 1.50 / 400` | Default weight for text content; TextInput; Accordion; Checkbox/Radio; article      |
| `--yds-typography-default-m-ac-*`<br>`typography.DEFAULT_M_AC_*` | default/m-ac                | `16px / 1.50 / 400` | Not currently used in Yle components.                                                |
| `--yds-typography-default-m-italic-*`<br>`typography.DEFAULT_M_ITALIC_*` | default/m-italic            | `16px / 1.50 / 400` | Yle articles only; correction and update notes. Not used elsewhere.                  |
| `--yds-typography-default-m-medium-*`<br>`typography.DEFAULT_M_MEDIUM_*` | default/m-medium            | `16px / 1.50 / 500` | Semi-bold emphasis; form labels                                                     |
| `--yds-typography-default-m-bold-*`<br>`typography.DEFAULT_M_BOLD_*` | default/m-bold              | `16px / 1.50 / 700` | Headings in Yle articles and stories; emphasis within body text; Accordion; Button  |
| `--yds-typography-default-m-bold-ac-*`<br>`typography.DEFAULT_M_BOLD_AC_*` | default/m-bold-ac           | `16px / 1.50 / 700` | Not currently used in Yle components. Tags and author information in articles.       |
| `--yds-typography-default-m-condensed-*`<br>`typography.DEFAULT_M_CONDENSED_*` | default/m-condensed         | `16px / 1.50 / 400` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-default-m-condensed-bold-*`<br>`typography.DEFAULT_M_CONDENSED_BOLD_*` | default/m-condensed-bold    | `16px / 1.50 / 700` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-default-s-*`<br>`typography.DEFAULT_S_*` | default/s                   | `14px / 1.50 / 400` | Default weight for text content; FormElementDescription; Notification; timestamps  |
| `--yds-typography-default-s-italic-*`<br>`typography.DEFAULT_S_ITALIC_*` | default/s-italic            | `14px / 1.50 / 400` | Yle articles only; correction and update notes. Not used elsewhere.                  |
| `--yds-typography-default-s-ac-*`<br>`typography.DEFAULT_S_AC_*` | default/s-ac                | `14px / 1.50 / 400` | Not currently used in Yle components.                                                |
| `--yds-typography-default-s-medium-*`<br>`typography.DEFAULT_S_MEDIUM_*` | default/s-medium            | `14px / 1.50 / 500` | Semi-bold secondary; form helpers                                                   |
| `--yds-typography-default-s-bold-*`<br>`typography.DEFAULT_S_BOLD_*` | default/s-bold              | `14px / 1.50 / 700` | Headings in Yle articles and stories; emphasis within body text; Accordion; Button  |
| `--yds-typography-default-s-bold-ac-*`<br>`typography.DEFAULT_S_BOLD_AC_*` | default/s-bold-ac           | `14px / 1.50 / 700` | Not currently used in Yle components. Tags and author information in articles.       |
| `--yds-typography-default-s-condensed-*`<br>`typography.DEFAULT_S_CONDENSED_*` | default/s-condensed         | `14px / 1.50 / 400` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-default-s-condensed-bold-*`<br>`typography.DEFAULT_S_CONDENSED_BOLD_*` | default/s-condensed-bold    | `14px / 1.50 / 700` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-default-xs-*`<br>`typography.DEFAULT_XS_*` | default/xs                  | `12px / 1.50 / 400` | Default weight for text content; caption; duration metadata; channel name         |
| `--yds-typography-default-xs-italic-*`<br>`typography.DEFAULT_XS_ITALIC_*` | default/xs-italic           | `12px / 1.50 / 400` | Yle articles only; correction and update notes. Not used elsewhere.                  |
| `--yds-typography-default-xs-ac-*`<br>`typography.DEFAULT_XS_AC_*` | default/xs-ac               | `12px / 1.50 / 400` | Not currently used in Yle components.                                                |
| `--yds-typography-default-xs-bold-*`<br>`typography.DEFAULT_XS_BOLD_*` | default/xs-bold             | `12px / 1.50 / 700` | Button xs; TagLink; video duration                                                  |
| `--yds-typography-default-xs-bold-ac-*`<br>`typography.DEFAULT_XS_BOLD_AC_*` | default/xs-bold-ac          | `12px / 1.50 / 700` | Not currently used in Yle components. Tags and author information in articles.       |
| `--yds-typography-default-xs-condensed-bold-*`<br>`typography.DEFAULT_XS_CONDENSED_BOLD_*` | default/xs-condensed-bold   | `12px / 1.50 / 700` | Yle infographics only; when fitting large amount of information in limited space. |

## Yle next

| CSS / JS     | Token                        | Value               | Description                                                                         |
| ----------- | ---------------------------- | ------------------- | ----------------------------------------------------------------------------------- |
| `--yds-typography-yle-next-7xl-bold-*`<br>`typography.YLE_NEXT_7XL_BOLD_*` | yle-next/7xl-bold            | `56px / 1.25 / 700` | Hero banners; Areena promotional titles                                             |
| `--yds-typography-yle-next-7xl-heavy-*`<br>`typography.YLE_NEXT_7XL_HEAVY_*` | yle-next/7xl-heavy           | `56px / 1.25 / 900` | Hero banners; maximum emphasis                                                      |
| `--yds-typography-yle-next-7xl-condensed-heavy-*`<br>`typography.YLE_NEXT_7XL_CONDENSED_HEAVY_*` | yle-next/7xl-condensed-heavy | `56px / 1.25 / 900` | Feature article headings only. |
| `--yds-typography-yle-next-6xl-bold-*`<br>`typography.YLE_NEXT_6XL_BOLD_*` | yle-next/6xl-bold            | `48px / 1.25 / 700` | Headings in Yle articles and stories; large promotional content; landing pages     |
| `--yds-typography-yle-next-6xl-heavy-*`<br>`typography.YLE_NEXT_6XL_HEAVY_*` | yle-next/6xl-heavy           | `48px / 1.25 / 900` | Headings in Yle articles and stories; feature article h1 desktop                   |
| `--yds-typography-yle-next-6xl-condensed-heavy-*`<br>`typography.YLE_NEXT_6XL_CONDENSED_HEAVY_*` | yle-next/6xl-condensed-heavy | `48px / 1.25 / 900` | Feature article headings only. |
| `--yds-typography-yle-next-5xl-bold-*`<br>`typography.YLE_NEXT_5XL_BOLD_*` | yle-next/5xl-bold            | `40px / 1.25 / 700` | Headings in Yle articles and stories; front page main headlines                    |
| `--yds-typography-yle-next-5xl-heavy-*`<br>`typography.YLE_NEXT_5XL_HEAVY_*` | yle-next/5xl-heavy           | `40px / 1.25 / 900` | Headings in Yle articles and stories; feature article h1 mobile                    |
| `--yds-typography-yle-next-5xl-condensed-heavy-*`<br>`typography.YLE_NEXT_5XL_CONDENSED_HEAVY_*` | yle-next/5xl-condensed-heavy | `40px / 1.25 / 900` | Feature article headings only. |
| `--yds-typography-yle-next-4xl-bold-*`<br>`typography.YLE_NEXT_4XL_BOLD_*` | yle-next/4xl-bold            | `32px / 1.35 / 700` | Headings in Yle articles and stories; ArticleHeading lg; front page card headlines |
| `--yds-typography-yle-next-4xl-heavy-*`<br>`typography.YLE_NEXT_4XL_HEAVY_*` | yle-next/4xl-heavy           | `32px / 1.35 / 900` | Headings in Yle articles and stories; article h1 desktop                            |
| `--yds-typography-yle-next-4xl-condensed-heavy-*`<br>`typography.YLE_NEXT_4XL_CONDENSED_HEAVY_*` | yle-next/4xl-condensed-heavy | `32px / 1.35 / 900` | Feature article headings only. |
| `--yds-typography-yle-next-3xl-bold-*`<br>`typography.YLE_NEXT_3XL_BOLD_*` | yle-next/3xl-bold            | `28px / 1.35 / 700` | Headings in Yle articles and stories; article page headlines                         |
| `--yds-typography-yle-next-3xl-heavy-*`<br>`typography.YLE_NEXT_3XL_HEAVY_*` | yle-next/3xl-heavy           | `28px / 1.35 / 900` | Headings in Yle articles and stories; article headlines; strong emphasis            |
| `--yds-typography-yle-next-3xl-condensed-heavy-*`<br>`typography.YLE_NEXT_3XL_CONDENSED_HEAVY_*` | yle-next/3xl-condensed-heavy | `28px / 1.35 / 900` | Feature article headings only. |
| `--yds-typography-yle-next-2xl-*`<br>`typography.YLE_NEXT_2XL_*` | yle-next/2xl                 | `24px / 1.35 / 400` | Default weight for text content; section headings; card headlines                  |
| `--yds-typography-yle-next-2xl-bold-*`<br>`typography.YLE_NEXT_2XL_BOLD_*` | yle-next/2xl-bold            | `24px / 1.35 / 700` | Headings in Yle articles and stories; ArticleHeading lg; Dialog title md           |
| `--yds-typography-yle-next-2xl-heavy-*`<br>`typography.YLE_NEXT_2XL_HEAVY_*` | yle-next/2xl-heavy           | `24px / 1.35 / 900` | Headings in Yle articles and stories; article h1 mobile; Quote; List/Infobox       |
| `--yds-typography-yle-next-2xl-condensed-bold-*`<br>`typography.YLE_NEXT_2XL_CONDENSED_BOLD_*` | yle-next/2xl-condensed-bold  | `24px / 1.35 / 700` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-yle-next-2xl-condensed-heavy-*`<br>`typography.YLE_NEXT_2XL_CONDENSED_HEAVY_*` | yle-next/2xl-condensed-heavy | `24px / 1.35 / 900` | Feature article headings only. |
| `--yds-typography-yle-next-xl-*`<br>`typography.YLE_NEXT_XL_*` | yle-next/xl                  | `20px / 1.45 / 400` | Default weight for text content; article ingress/lead desktop                       |
| `--yds-typography-yle-next-xl-italic-*`<br>`typography.YLE_NEXT_XL_ITALIC_*` | yle-next/xl-italic           | `20px / 1.45 / 400` | Yle articles only; correction and update notes. Not used elsewhere.                  |
| `--yds-typography-yle-next-xl-bold-*`<br>`typography.YLE_NEXT_XL_BOLD_*` | yle-next/xl-bold             | `20px / 1.45 / 700` | Headings in Yle articles and stories; emphasis within body text; ArticleHeading md  |
| `--yds-typography-yle-next-xl-heavy-*`<br>`typography.YLE_NEXT_XL_HEAVY_*` | yle-next/xl-heavy            | `20px / 1.45 / 900` | Headings in Yle articles and stories; article h2/h3; Quote/List/Infobox             |
| `--yds-typography-yle-next-xl-condensed-*`<br>`typography.YLE_NEXT_XL_CONDENSED_*` | yle-next/xl-condensed        | `20px / 1.45 / 400` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-yle-next-xl-condensed-bold-*`<br>`typography.YLE_NEXT_XL_CONDENSED_BOLD_*` | yle-next/xl-condensed-bold   | `20px / 1.45 / 700` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-yle-next-xl-condensed-heavy-*`<br>`typography.YLE_NEXT_XL_CONDENSED_HEAVY_*` | yle-next/xl-condensed-heavy  | `20px / 1.45 / 900` | Feature article headings only. |
| `--yds-typography-yle-next-l-*`<br>`typography.YLE_NEXT_L_*` | yle-next/l                   | `18px / 1.45 / 400` | Default weight for text content; article body desktop; Accordion; lists             |
| `--yds-typography-yle-next-l-italic-*`<br>`typography.YLE_NEXT_L_ITALIC_*` | yle-next/l-italic            | `18px / 1.45 / 400` | Yle articles only; correction and update notes. Not used elsewhere.                  |
| `--yds-typography-yle-next-l-bold-*`<br>`typography.YLE_NEXT_L_BOLD_*` | yle-next/l-bold              | `18px / 1.45 / 700` | Headings in Yle articles and stories; emphasis within body text; Accordion; Button |
| `--yds-typography-yle-next-l-heavy-*`<br>`typography.YLE_NEXT_L_HEAVY_*` | yle-next/l-heavy             | `18px / 1.45 / 900` | Headings in Yle articles and stories; article h3 mobile; manual promo headline     |
| `--yds-typography-yle-next-l-condensed-*`<br>`typography.YLE_NEXT_L_CONDENSED_*` | yle-next/l-condensed         | `18px / 1.45 / 400` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-yle-next-l-condensed-bold-*`<br>`typography.YLE_NEXT_L_CONDENSED_BOLD_*` | yle-next/l-condensed-bold    | `18px / 1.45 / 700` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-yle-next-l-condensed-heavy-*`<br>`typography.YLE_NEXT_L_CONDENSED_HEAVY_*` | yle-next/l-condensed-heavy   | `18px / 1.45 / 900` | Feature article headings only. |
| `--yds-typography-yle-next-m-*`<br>`typography.YLE_NEXT_M_*` | yle-next/m                   | `16px / 1.50 / 400` | Default weight for text content; TextInput; Accordion; Checkbox/Radio; article       |
| `--yds-typography-yle-next-m-ac-*`<br>`typography.YLE_NEXT_M_AC_*` | yle-next/m-ac                | `16px / 1.50 / 400` | Not currently used in Yle components.                                                |
| `--yds-typography-yle-next-m-italic-*`<br>`typography.YLE_NEXT_M_ITALIC_*` | yle-next/m-italic            | `16px / 1.50 / 400` | Yle articles only; correction and update notes. Not used elsewhere.                  |
| `--yds-typography-yle-next-m-medium-*`<br>`typography.YLE_NEXT_M_MEDIUM_*` | yle-next/m-medium            | `16px / 1.50 / 500` | Semi-bold emphasis; form labels                                                     |
| `--yds-typography-yle-next-m-bold-*`<br>`typography.YLE_NEXT_M_BOLD_*` | yle-next/m-bold              | `16px / 1.50 / 700` | Headings in Yle articles and stories; emphasis within body text; Accordion; Button  |
| `--yds-typography-yle-next-m-bold-ac-*`<br>`typography.YLE_NEXT_M_BOLD_AC_*` | yle-next/m-bold-ac           | `16px / 1.50 / 700` | Not currently used in Yle components. Tags and author information in articles.       |
| `--yds-typography-yle-next-m-condensed-*`<br>`typography.YLE_NEXT_M_CONDENSED_*` | yle-next/m-condensed         | `16px / 1.50 / 400` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-yle-next-m-condensed-bold-*`<br>`typography.YLE_NEXT_M_CONDENSED_BOLD_*` | yle-next/m-condensed-bold    | `16px / 1.50 / 700` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-yle-next-s-*`<br>`typography.YLE_NEXT_S_*` | yle-next/s                   | `14px / 1.50 / 400` | Default weight for text content; FormElementDescription; Notification; timestamps   |
| `--yds-typography-yle-next-s-italic-*`<br>`typography.YLE_NEXT_S_ITALIC_*` | yle-next/s-italic            | `14px / 1.50 / 400` | Yle articles only; correction and update notes. Not used elsewhere.                  |
| `--yds-typography-yle-next-s-ac-*`<br>`typography.YLE_NEXT_S_AC_*` | yle-next/s-ac                | `14px / 1.50 / 400` | Not currently used in Yle components.                                                |
| `--yds-typography-yle-next-s-medium-*`<br>`typography.YLE_NEXT_S_MEDIUM_*` | yle-next/s-medium            | `14px / 1.50 / 500` | Semi-bold secondary; form helpers                                                   |
| `--yds-typography-yle-next-s-bold-*`<br>`typography.YLE_NEXT_S_BOLD_*` | yle-next/s-bold              | `14px / 1.50 / 700` | Headings in Yle articles and stories; emphasis within body text; Accordion; Button  |
| `--yds-typography-yle-next-s-bold-ac-*`<br>`typography.YLE_NEXT_S_BOLD_AC_*` | yle-next/s-bold-ac           | `14px / 1.50 / 700` | Not currently used in Yle components. Tags and author information in articles.       |
| `--yds-typography-yle-next-s-condensed-*`<br>`typography.YLE_NEXT_S_CONDENSED_*` | yle-next/s-condensed         | `14px / 1.50 / 400` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-yle-next-s-condensed-bold-*`<br>`typography.YLE_NEXT_S_CONDENSED_BOLD_*` | yle-next/s-condensed-bold    | `14px / 1.50 / 700` | Yle infographics only; when fitting large amount of information in limited space. |
| `--yds-typography-yle-next-xs-*`<br>`typography.YLE_NEXT_XS_*` | yle-next/xs                  | `12px / 1.50 / 400` | Default weight for text content; caption; duration metadata; channel name            |
| `--yds-typography-yle-next-xs-italic-*`<br>`typography.YLE_NEXT_XS_ITALIC_*` | yle-next/xs-italic           | `12px / 1.50 / 400` | Yle articles only; correction and update notes. Not used elsewhere.                  |
| `--yds-typography-yle-next-xs-ac-*`<br>`typography.YLE_NEXT_XS_AC_*` | yle-next/xs-ac               | `12px / 1.50 / 400` | Not currently used in Yle components.                                                |
| `--yds-typography-yle-next-xs-bold-*`<br>`typography.YLE_NEXT_XS_BOLD_*` | yle-next/xs-bold             | `12px / 1.50 / 700` | Button xs; TagLink; video duration                                                  |
| `--yds-typography-yle-next-xs-bold-ac-*`<br>`typography.YLE_NEXT_XS_BOLD_AC_*` | yle-next/xs-bold-ac          | `12px / 1.50 / 700` | Not currently used in Yle components. Tags and author information in articles.       |
| `--yds-typography-yle-next-xs-condensed-bold-*`<br>`typography.YLE_NEXT_XS_CONDENSED_BOLD_*` | yle-next/xs-condensed-bold   | `12px / 1.50 / 700` | Yle infographics only; when fitting large amount of information in limited space. |

---

# Icons and Logos

# Graphical Assets

- [Figma](https://www.figma.com/design/lSboxfILj3Thr1o145POJv/YDS-Icons-and-Logos?m=auto&node-id=19-202&t=AV91DQjNCbOsTXcs-1)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/story/design-tokens-icons--graphical-assets)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/icons-and-logos/graphical-assets.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

Graphical assets include age & content rating badges and decorative elements.

| Preview                                                    | Component                   | Description                                          |
| ---------------------------------------------------------- | --------------------------- | ---------------------------------------------------- |
| | `AssetContainsDrugUse`      | Age rating badge: contains drug use.                 |
| | `AssetContainsViolence`     | Age rating badge: contains violence.                 |
| | `AssetForAllAgesFi`         | Age rating badge: suitable for all ages (Finnish).   |
| | `AssetForAllAgesSv`         | Age rating badge: suitable for all ages (Swedish).   |
| | `AssetMayCauseAnxiety`      | Age rating badge: may cause anxiety.                 |
| | `AssetNotForPersonsUnder7`  | Age rating badge: not suitable for persons under 7.  |
| | `AssetNotForPersonsUnder12` | Age rating badge: not suitable for persons under 12. |
| | `AssetNotForPersonsUnder16` | Age rating badge: not suitable for persons under 16. |
| | `AssetNotForPersonsUnder18` | Age rating badge: not suitable for persons under 18. |
| | `AssetQuote`                | Decorative quotation mark asset.                     |
| | `AssetSexualContent`        | Age rating badge: contains sexual content.           |

# Basic Icons

- [Figma](https://www.figma.com/design/lSboxfILj3Thr1o145POJv/YDS-Icons-and-Logos?m=auto&node-id=22-927&t=AV91DQjNCbOsTXcs-1)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/story/design-tokens-icons--yle-icon-list)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/icons-and-logos/icons.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

|                                | Name                      | Component              | Description                                                                                        |
| ------------------------------ | ------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
| | `4k`                      | `Icon4k`               | Used in Areena to indicate video broadcast quality.                                                |
| | `accessibility`           | `Accessibility`        | Represents service accessibility or accessibility settings.                                        |
| | `ai`                      | `Ai`                   | Indicates content generated or edited by AI.                                                       |
| | `airplay`                 | `Airplay`              | Airplay icon for video content.                                                                    |
| | `airplay-audio`           | `AirplayAudio`         | Airplay icon for audio content.                                                                    |
| | `alert-circle`            | `AlertCircle`          | Used in Warning notifications.                                                                     |
| | `alert-triangle`          | `AlertTriangle`        | Used in Error notifications. Also symbolises a dangerous action.                                   |
| | `archive`                 | `Archive`              | Communicates to the user that content can be moved to an archive for later use.                    |
| | `arrow-down`              | `ArrowDown`            | Guides the user to move downwards.                                                                 |
| | `arrow-left`              | `ArrowLeft`            | Guides the user to move left or to the previous page.                                              |
| | `arrow-right`             | `ArrowRight`           | Guides the user to move right or to the next page.                                                 |
| | `arrow-up`                | `ArrowUp`              | Guides the user to move upwards.                                                                   |
| | `autoplay`                | `Autoplay`             | Indicates the option to enable or disable automatic media playback.                                |
| | `beta-tester`             | `BetaTester`           | Guides the user to beta testing of the service.                                                    |
| | `bluetooth`               | `Bluetooth`            | Guides the user to connect audio playback to an external device using Bluetooth.                   |
| | `book-open`               | `BookOpen`             | Indicates the recently read articles section, e.g. in navigation menus.                            |
| | `bookmark`                | `Bookmark`             | Used to save articles to the 'My Articles' list.                                                   |
| | `bookmark-active`         | `BookmarkActive`       | Highlights an article saved to the 'My Articles' list.                                             |
| | `bug`                     | `Bug`                  | Indicates a bug or issue in the system.                                                            |
| | `camera`                  | `Camera`               | Guides the user to use their device camera.                                                        |
| | `caps-lock`               | `CapsLock`             | Communicates to the user that the "caps lock" function is active.                                  |
| | `cast`                    | `Cast`                 | Chromecast available.                                                                              |
| | `cast-connected`          | `CastConnected`        | Chromecast connected.                                                                              |
| | `check`                   | `Check`                | Highlights added items in the UI, e.g. in lists or queues. Also used in Success notifications.     |
| | `check-16`                | `Check16`              | —                                                                                                  |
| | `chevron-down`            | `ChevronDown`          | Used in a button that reveals more actions, selectable topics, or content.                         |
| | `chevron-down-16`         | `ChevronDown16`        | —                                                                                                  |
| | `chevron-left`            | `ChevronLeft`          | Guides the user backwards or to the previous view.                                                 |
| | `chevron-right`           | `ChevronRight`         | —                                                                                                  |
| | `chevron-up`              | `ChevronUp`            | Used in a button that hides actions, selectable topics, or content.                                |
| | `chevrons-left`           | `ChevronsLeft`         | Guides the user to the first page or the beginning of content in paginated navigation.             |
| | `chevrons-right`          | `ChevronsRight`        | Guides the user to the last page or the end of content in paginated navigation.                    |
| | `clock`                   | `Clock`                | Used to subscribe to a reminder for a programme or series in the Areena mobile app.                |
| | `close`                   | `Close`                | Used to dismiss an action or element from the UI.                                                  |
| | `close-circle`            | `CloseCircle`          | Used in a button when a simple close icon does not stand out enough in the UI.                     |
| | `close-small`             | `CloseSmall`           | Used in form components to remove an option from the UI.                                           |
| | `connected-devices`       | `ConnectedDevices`     | Guides the user to manage devices connected to their Yle account.                                  |
| | `connected-services`      | `ConnectedServices`    | Guides the user to manage services connected to their Yle account.                                 |
| | `console`                 | `Console`              | Communicates to the user which device they are signed in to the service on.                        |
| | `cookies`                 | `Cookies`              | Used in cookie settings and to navigate the user to cookie preferences.                            |
| | `corner-down-left`        | `CornerDownLeft`       | Enter key icon used in the Areena smart TV app keyboard.                                           |
| | `date`                    | `Date`                 | Used in the date picker button.                                                                    |
| | `delete`                  | `Delete`               | Delete icon used in the Areena smart TV app keyboard.                                              |
| | `delete-active`           | `DeleteActive`         | Active delete icon used in the Areena smart TV app keyboard to indicate an active state.           |
| | `dice`                    | `Dice`                 | Indicates randomness or a random/chance selection.                                                 |
| | `display-turn`            | `DisplayTurn`          | Communicates the option to manage portrait and landscape mode settings in the Yle app.             |
| | `download`                | `Download`             | Used in download buttons.                                                                          |
| | `drag-handle`             | `DragHandle`           | Guides the user to reorder items vertically using drag-and-drop, e.g. in lists.                    |
| | `edit`                    | `Edit`                 | Indicates that content is editable.                                                                |
| | `episodes`                | `Episodes`             | Guides the user to the episode list of a series in the Areena smart TV app.                        |
| | `external-link`           | `ExternalLink`         | An external link is a hyperlink pointing to any site other than the one the link is on.            |
| | `eye`                     | `Eye`                  | Used in the password input during sign-in. Reveals the typed password.                             |
| | `eye-off`                 | `EyeOff`               | Used in the password input during sign-in. Hides the typed password.                               |
| | `facebook`                | `Facebook`             | Used primarily with the share feature.                                                             |
| | `fast-forward-end`        | `FastForwardEnd`       | Jumps playback directly to the end of the media timeline.                                          |
| | `fast-rewind-start`       | `FastRewindStart`      | Jumps playback directly to the start of the media timeline.                                        |
| | `favorite`                | `Favorite`             | Guides mobile users to their favourite topics, articles, series, and programmes.                   |
| | `favorite-active`         | `FavoriteActive`       | Indicates the active 'My' view in mobile navigation.                                               |
| | `featured`                | `Featured`             | Indicates recommended topics or content. In Areena, navigates the user to the 'Recommended' view.  |
| | `featured-active`         | `FeaturedActive`       | Indicates that the recommendations view is active.                                                 |
| | `feedback`                | `Feedback`             | Used to report service issues to customer support.                                                 |
| | `file-text`               | `FileText`             | Represents attached files, e.g. PDFs.                                                              |
| | `filter`                  | `Filter`               | Indicates a filtering action in the UI.                                                            |
| | `filter-2`                | `Filter2`              | Indicates a filtering action in the UI.                                                            |
| | `flag`                    | `Flag`                 | Guides the user to report inappropriate content.                                                   |
| | `forward-10`              | `Forward10`            | —                                                                                                  |
| | `fullscreen`              | `Fullscreen`           | —                                                                                                  |
| | `fullscreen-exit`         | `FullscreenExit`       | —                                                                                                  |
| | `globe`                   | `Globe`                | Indicates language selection.                                                                      |
| | `grid`                    | `Grid`                 | Guides the user to the 'See more' card view (Smart TV).                                            |
| | `grid-active`             | `GridActive`           | Indicates the 'See more' card view is selected (Smart TV).                                         |
| | `hd`                      | `Hd`                   | Used in Areena to indicate HD video quality.                                                       |
| | `headphones`              | `Headphones`           | Used with audio content in podcast cards, live audio, and text-to-speech articles.                 |
| | `headphones-active`       | `HeadphonesActive`     | Indicates that the 'Podcasts' view is selected.                                                    |
| | `help-circle`             | `HelpCircle`           | Used in the tooltip trigger button. Also guides the user to service help documentation.            |
| | `help-circle-active`      | `HelpCircleActive`     | Indicates the active help documentation view.                                                      |
| | `history`                 | `History`              | Guides the user to their usage history.                                                            |
| | `home`                    | `Home`                 | Guides the user to the service home page or start view.                                            |
| | `home-active`             | `HomeActive`           | Indicates the selected home page or start view.                                                    |
| | `image`                   | `Image`                | Communicates images to the user, e.g. in a form.                                                   |
| | `import`                  | `Import`               | Indicates the option to import topic preferences to a new app.                                     |
| | `info`                    | `Info`                 | Used in Info notifications and additional information.                                             |
| | `instagram`               | `Instagram`            | Used primarily with the share feature.                                                             |
| | `laptop`                  | `Laptop`               | Laptop computer icon.                                                                              |
| | `latest`                  | `Latest`               | Guides the user to the 'Latest news' view.                                                         |
| | `latest-active`           | `LatestActive`         | Indicates the 'Latest news' view is active.                                                        |
| | `linear-scale`            | `LinearScale`          | Represents an element for selecting a value from a linear scale.                                   |
| | `link`                    | `Link`                 | Communicates to the user that an element is a link.                                                |
| | `link-2`                  | `Link2`                | Used for copying a link.                                                                           |
| | `linkedin`                | `Linkedin`             | Used primarily with the share feature.                                                             |
| | `list`                    | `List`                 | Used in Uutisvahtii navigation for the 'All news' button.                                          |
| | `live-streaming`          | `LiveStreaming`        | Guides the user to the 'Live broadcasts' view.                                                     |
| | `live-streaming-active`   | `LiveStreamingActive`  | Indicates the 'Live broadcasts' view is selected (active).                                         |
| | `location`                | `Location`             | Indicates location.                                                                                |
| | `location-active`         | `LocationActive`       | Marks a specific point of interest or place on the map.                                            |
| | `log-in`                  | `LogIn`                | Represents signing in to the service.                                                              |
| | `log-out`                 | `LogOut`               | Represents signing out of the service.                                                             |
| | `mail`                    | `Mail`                 | Guides the user to manage newsletters. Also a general email symbol.                                |
| | `menu`                    | `Menu`                 | Used with the main navigation menu in mobile services.                                             |
| | `message-circle`          | `MessageCircle`        | Used to give general feedback about the service.                                                   |
| | `message-square`          | `MessageSquare`        | Guides the user to comment on content. In Areena, guides the user to send a message to the studio. |
| | `message-square-active`   | `MessageSquareActive`  | Indicates an active state in the UI.                                                               |
| | `minus`                   | `Minus`                | Guides the user to remove items in the UI.                                                         |
| | `minus-circle`            | `MinusCircle`          | Used in a remove button when a simple minus icon does not stand out enough.                        |
| | `moon`                    | `Moon`                 | Guides the user to manage light and dark mode.                                                     |
| | `more-horizontal`         | `MoreHorizontal`       | Guides the user to open a menu with more actions (horizontal).                                     |
| | `more-vertical`           | `MoreVertical`         | Guides the user to open a menu with more actions (vertical).                                       |
| | `next`                    | `Next`                 | —                                                                                                  |
| | `notification`            | `Notification`         | Used to guide the user to notification settings or to communicate notification status.             |
| | `notification-active`     | `NotificationActive`   | Indicates the user has subscribed to notifications, e.g. for topics, programmes, or series.        |
| | `notification-off`        | `NotificationOff`      | Indicates to the user that notifications are disabled.                                             |
| | `notification-on`         | `NotificationOn`       | —                                                                                                  |
| | `pause`                   | `Pause`                | —                                                                                                  |
| | `phone`                   | `Phone`                | Used for the "Call the studio" action.                                                             |
| | `picture-in-picture`      | `PictureInPicture`     | —                                                                                                  |
| | `picture-in-picture-exit` | `PictureInPictureExit` | —                                                                                                  |
| | `pin`                     | `Pin`                  | Used by admin user to pin a message in the chat.                                                   |
| | `pin-active`              | `PinActive`            | Indicates a message is pinned in the chat.                                                         |
| | `pin-off`                 | `PinOff`               | Used by admin user to unpin a message in the chat.                                                 |
| | `play`                    | `Play`                 | Used to start media playback or to indicate video content, e.g. on top of a thumbnail.             |
| | `play-2`                  | `Play2`                | Can be used to resume playback outside of the video player context.                                |
| | `play-circle`             | `PlayCircle`           | Guides the user to video autoplay settings.                                                        |
| | `playlist`                | `Playlist`             | Guides the user to their personal play queue.                                                      |
| | `playlist-check`          | `PlaylistCheck`        | Used in Yle Areena to show that an episode has been successfully added to the playlist.            |
| | `playlist-plus`           | `PlaylistPlus`         | Used in Yle Areena to add individual episodes to the playlist.                                     |
| | `plus`                    | `Plus`                 | Guides the user to add items in the UI.                                                            |
| | `plus-16`                 | `Plus16`               | —                                                                                                  |
| | `plus-circle`             | `PlusCircle`           | Used in an add button when a simple plus icon does not stand out enough.                           |
| | `podcast`                 | `Podcast`              | Indicates the option to subscribe to audio content.                                                |
| | `previous`                | `Previous`             | —                                                                                                  |
| | `printer`                 | `Printer`              | Guides the user to print.                                                                          |
| | `privacy-policy`          | `PrivacyPolicy`        | Used with Yle's privacy policy statement.                                                          |
| | `privacy-policy-active`   | `PrivacyPolicyActive`  | Used with Yle's privacy policy to indicate an active state.                                        |
| | `refresh-cw`              | `RefreshCw`            | Used to load new content in the service.                                                           |
| | `replay`                  | `Replay`               | —                                                                                                  |
| | `replay-10`               | `Replay10`             | —                                                                                                  |
| | `reply`                   | `Reply`                | Communicates a reply or the option to reply to a message.                                          |
| | `rss`                     | `Rss`                  | Guides the user to subscribe to an RSS feed.                                                       |
| | `search`                  | `Search`               | Used in search-related buttons and input fields.                                                   |
| | `search-active`           | `SearchActive`         | Indicates the active search view.                                                                  |
| | `send`                    | `Send`                 | Represents the send message action, e.g. in a chat.                                                |
| | `settings`                | `Settings`             | Guides the user to service settings.                                                               |
| | `settings-active`         | `SettingsActive`       | Used with service settings to indicate an active state.                                            |
| | `share`                   | `Share`                | Used in web apps with the share action in a clickable share button.                                |
| | `share-android`           | `ShareAndroid`         | Android share icon used in the share button.                                                       |
| | `share-ios`               | `ShareIos`             | iOS share icon used in the share button.                                                           |
| | `slash`                   | `Slash`                | Communicates hidden or disabled items to the user.                                                 |
| | `sleep-timer`             | `SleepTimer`           | Used with the sleep timer in Areena.                                                               |
| | `sleep-timer-active`      | `SleepTimerActive`     | Indicates an active sleep timer in Areena.                                                         |
| | `smartphone`              | `Smartphone`           | Smartphone icon.                                                                                   |
| | `snapchat`                | `Snapchat`             | Used primarily with the share feature.                                                             |
| | `songlist`                | `Songlist`             | Guides the user to the track list of songs played in a radio programme.                            |
| | `sort`                    | `Sort`                 | Indicates the option to reorder content, e.g. in tables.                                           |
| | `sort-asc`                | `SortAsc`              | Indicates the selected sort order is ascending.                                                    |
| | `sort-desc`               | `SortDesc`             | Indicates the selected sort order is descending.                                                   |
| | `spacebar`                | `Spacebar`             | Communicates the spacebar key to the user.                                                         |
| | `sport`                   | `Sport`                | Guides the user to sports news.                                                                    |
| | `sport-active`            | `SportActive`          | Indicates the 'Sports' view is active.                                                             |
| | `stop`                    | `Stop`                 | —                                                                                                  |
| | `subtitles-multiaudio`    | `SubtitlesMultiaudio`  | —                                                                                                  |
| | `tablet`                  | `Tablet`               | Tablet icon.                                                                                       |
| | `thumbs-down`             | `ThumbsDown`           | Used in the default state of the 'dislike' button.                                                 |
| | `thumbs-down-active`      | `ThumbsDownActive`     | Used in the pressed state of the 'dislike' button.                                                 |
| | `thumbs-up`               | `ThumbsUp`             | Used in the default state of the 'like' button.                                                    |
| | `thumbs-up-active`        | `ThumbsUpActive`       | Used in the pressed state of the 'like' button.                                                    |
| | `tiktok`                  | `Tiktok`               | Used primarily with the share feature.                                                             |
| | `time`                    | `Time`                 | Indicates the publication time of an article in the Svenska Yle service.                           |
| | `trash`                   | `Trash`                | Communicates the option to delete a selected item or content, such as a file, message, or entry.   |
| | `tv`                      | `Tv`                   | Guides the user to the Areena video content home page.                                             |
| | `tv-active`               | `TvActive`             | Indicates the video content section is active.                                                     |
| | `twitter`                 | `Twitter`              | Used primarily with the share feature.                                                             |
| | `twitter-x`               | `TwitterX`             | Used primarily with the share feature.                                                             |
| | `type`                    | `Type`                 | Indicates text size selection in settings.                                                         |
| | `unarchive`               | `Unarchive`            | Communicates that archived content can be restored.                                                |
| | `user`                    | `User`                 | Primarily guides the user to sign in or to manage their profile and personal information.          |
| | `video`                   | `Video`                | Communicates video content to the user, e.g. in a form.                                            |
| | `video-feed`              | `VideoFeed`            | Guides the user to short videos.                                                                   |
| | `video-feed-active`       | `VideoFeedActive`      | Indicates the 'Short video' view is active.                                                        |
| | `volume`                  | `Volume`               | —                                                                                                  |
| | `volume-high`             | `VolumeHigh`           | —                                                                                                  |
| | `volume-low`              | `VolumeLow`            | —                                                                                                  |
| | `volume-off`              | `VolumeOff`            | —                                                                                                  |
| | `whatsapp`                | `Whatsapp`             | Used primarily with the share feature.                                                             |
| | `youtube`                 | `Youtube`              | Used primarily with the share feature.                                                             |

# Illustrative Icons

- [Figma](https://www.figma.com/design/lSboxfILj3Thr1o145POJv/YDS-Icons-and-Logos?m=auto&node-id=19-200&t=AV91DQjNCbOsTXcs-1)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/story/design-tokens-icons--illustrative-icons)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/icons-and-logos/illustrative-icons.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

Illustrative icons are large, expressive icons used for empty states, onboarding, confirmations, and other contextual moments in the UI. Most come in pairs: a default variant for light backgrounds and an `OnDark` variant for dark backgrounds.

## Light variants

|                                                                 | Name                               | Component                        | Description                                                                                                         |
| --------------------------------------------------------------- | ---------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| | `illustrative-areena-mobile-app`   | `IllustrativeAreenaMobileApp`    | Used in contexts related to downloading the Areena mobile app.                                                      |
| | `illustrative-areena-smart-tv`     | `IllustrativeAreenaSmartTv`      | Used in contexts related to the Areena smart TV app.                                                                |
| | `illustrative-celebrate`           | `IllustrativeCelebrate`          | Used for celebrations, successes, or important milestones.                                                          |
| | `illustrative-cookies`             | `IllustrativeCookies`            | Used in contexts related to cookies.                                                                                |
| | `illustrative-error-1`             | `IllustrativeError1`             | Visually confirms to the user that an action has failed. This is a neutral visual approach to error states.         |
| | `illustrative-error-2`             | `IllustrativeError2`             | Visually confirms to the user that an action has failed. This is a more expressive visual approach to error states. |
| | `illustrative-favourite`           | `IllustrativeFavourite`          | Used in contexts related to the user's favourites.                                                                  |
| | `illustrative-globe`               | `IllustrativeGlobe`              | Used in contexts related to language settings.                                                                      |
| | `illustrative-info-message`        | `IllustrativeInfoMessage`        | Used in contexts related to informing or reminding the user.                                                        |
| | `illustrative-information`         | `IllustrativeInformation`        | Used alongside service information.                                                                                 |
| | `illustrative-location`            | `IllustrativeLocation`           | Used in contexts related to location data.                                                                          |
| | `illustrative-mail`                | `IllustrativeMail`               | Used in contexts related to account creation.                                                                       |
| | `illustrative-message`             | `IllustrativeMessage`            | Used in contexts related to messaging.                                                                              |
| | `illustrative-notification`        | `IllustrativeNotification`       | Used in contexts related to notifications.                                                                          |
| | `illustrative-play`                | `IllustrativePlay`               | Used in contexts related to video autoplay.                                                                         |
| | `illustrative-profile`             | `IllustrativeProfile`            | Used in contexts related to signing in.                                                                             |
| | `illustrative-rating`              | `IllustrativeRating`             | Used in contexts related to user-submitted ratings.                                                                 |
| | `illustrative-success`             | `IllustrativeSuccess`            | Visually confirms to the user that an action was successful.                                                        |
| | `illustrative-theme`               | `IllustrativeTheme`              | Used in contexts related to managing the service theme.                                                             |
| | `illustrative-user-recommendation` | `IllustrativeUserRecommendation` | Used alongside user-given recommendations and weightings for the recommendation algorithm.                          |
| | `illustrative-yle-app`             | `IllustrativeYleApp`             | Used in contexts related to downloading the Yle app.                                                                |

---

## Dark variants (`OnDark`)

Use these on dark backgrounds. The name suffix `-on-dark` corresponds to an `OnDark` suffix on the component name.

|                                                                                                                                                                           | Name                                       | Component                              | Description                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| | `illustrative-areena-mobile-app-on-dark`   | `IllustrativeAreenaMobileAppOnDark`    | Used in contexts related to downloading the Areena mobile app.                                                      |
| | `illustrative-areena-smart-tv-on-dark`     | `IllustrativeAreenaSmartTvOnDark`      | Used in contexts related to the Areena smart TV app.                                                                |
| | `illustrative-celebrate-on-dark`           | `IllustrativeCelebrateOnDark`          | Used for celebrations, successes, or important milestones.                                                          |
| | `illustrative-cookies-on-dark`             | `IllustrativeCookiesOnDark`            | Used in contexts related to cookies.                                                                                |
| | `illustrative-error-1-on-dark`             | `IllustrativeError1OnDark`             | Visually confirms to the user that an action has failed. This is a neutral visual approach to error states.         |
| | `illustrative-error-2-on-dark`             | `IllustrativeError2OnDark`             | Visually confirms to the user that an action has failed. This is a more expressive visual approach to error states. |
| | `illustrative-favourite-on-dark`           | `IllustrativeFavouriteOnDark`          | Used in contexts related to the user's favourites.                                                                  |
| | `illustrative-globe-on-dark`               | `IllustrativeGlobeOnDark`              | Used in contexts related to language settings.                                                                      |
| | `illustrative-info-message-on-dark`        | `IllustrativeInfoMessageOnDark`        | Used in contexts related to informing or reminding the user.                                                        |
| | `illustrative-information-on-dark`         | `IllustrativeInformationOnDark`        | Used alongside service information.                                                                                 |
| | `illustrative-location-on-dark`            | `IllustrativeLocationOnDark`           | Used in contexts related to location data.                                                                          |
| | `illustrative-mail-on-dark`                | `IllustrativeMailOnDark`               | Used in contexts related to account creation.                                                                       |
| | `illustrative-message-on-dark`             | `IllustrativeMessageOnDark`            | Used in contexts related to messaging.                                                                              |
| | `illustrative-notification-on-dark`        | `IllustrativeNotificationOnDark`       | Used in contexts related to notifications.                                                                          |
| | `illustrative-play-on-dark`                | `IllustrativePlayOnDark`               | Used in contexts related to video autoplay.                                                                         |
| | `illustrative-profile-on-dark`             | `IllustrativeProfileOnDark`            | Used in contexts related to signing in.                                                                             |
| | `illustrative-rating-on-dark`              | `IllustrativeRatingOnDark`             | Used in contexts related to user-submitted ratings.                                                                 |
| | `illustrative-success-on-dark`             | `IllustrativeSuccessOnDark`            | Visually confirms to the user that an action was successful.                                                        |
| | `illustrative-theme-on-dark`               | `IllustrativeThemeOnDark`              | Used in contexts related to managing the service theme.                                                             |
| | `illustrative-user-recommendation-on-dark` | `IllustrativeUserRecommendationOnDark` | Used alongside user-given recommendations and weightings for the recommendation algorithm.                          |
| | `illustrative-yle-app-on-dark`             | `IllustrativeYleAppOnDark`             | Used in contexts related to downloading the Yle app.                                                                |

# Icons and Logos

Yle Design System icons and graphical assets are distributed across three packages depending on use case.

---

## What's available

- [Regular Icons](./icons.md) — icons for UI actions, navigation, media, and social platforms.
- [Illustrative Icons](./illustrative-icons.md) — large expressive icons for empty states, onboarding, and confirmation moments.
- [Logos](./logos.md) — Yle service logos.
- [Graphical Assets](./graphical-assets.md) — graphical assets such as age-rating badges.

---

| Package                              | Purpose                                        |
| ------------------------------------ | ---------------------------------------------- |
| `@yleisradio/yds-icons`              | TypeScript types for icon names and SVG icons. |
| `@yleisradio/yds-icons-react`        | React SVG components for web.                  |
| `@yleisradio/yds-icons-react-native` | React Native SVG components for mobile.        |

---

## Installation

### React (web)

```bash
npm install @yleisradio/yds-icons-react
```

Peer dependencies:

```bash
npm install react react-dom @yleisradio/yds-core
```

### React Native (mobile)

```bash
npm install @yleisradio/yds-icons-react-native
```

Peer dependencies:

```bash
npm install react react-native react-native-svg @yleisradio/yds-core
```

### Types only

```bash
npm install @yleisradio/yds-icons
```

---

## Usage

### React

Import icons by their component name directly from the package:

```tsx
import { Menu, Search, ArrowRight } from '@yleisradio/yds-icons-react';

<Menu />
<Search width={20} height={20} color="currentColor" />
<ArrowRight title="Go to next page" />
```

### React Native

The API is identical — swap the package name:

```tsx
import { Menu, Search, ArrowRight } from '@yleisradio/yds-icons-react-native';

<Menu />
<Search width={20} height={20} color="currentColor" />
```

### Icon name types

Use `@yleisradio/yds-icons` when you need to pass or store icon names as strings, for example in a generic icon component:

```tsx
import type { IconsIconName } from '@yleisradio/yds-icons';

interface Props {
  icon: IconsIconName;
}
```

Available type exports:

| Type                      | Description                                                             |
| ------------------------- | ----------------------------------------------------------------------- |
| `IconsIconName`           | All Yle icon names (e.g. `'menu'`, `'search'`, `'arrow-right'`).        |
| `PlayerIconName`          | Player-specific icon names (e.g. `'play'`, `'pause'`, `'volume-high'`). |
| `ExternalServiceIconName` | External service icon names (e.g. `'facebook'`, `'youtube'`).           |

---

## Props

### Regular icons (React)

All regular icon components extend the standard `SVGProps<SVGSVGElement>` interface with two additional props.

| Prop      | Type               | Default          | Description                                                                   |
| --------- | ------------------ | ---------------- | ----------------------------------------------------------------------------- |
| `width`   | `string \| number` | `'24'`           | Width of the icon.                                                            |
| `height`  | `string \| number` | `'24'`           | Height of the icon.                                                           |
| `color`   | `string`           | `'currentColor'` | Fill colour. Inherits from CSS by default.                                    |
| `title`   | `string`           | `undefined`      | Accessible label. When set, the icon is not hidden from assistive technology. |
| `titleId` | `string`           | `undefined`      | `id` applied to the `<title>` element, used with `aria-labelledby`.           |

Icons without a `title` are rendered with `aria-hidden="true"`. Provide a `title` when the icon carries meaning that is not conveyed by surrounding text.

### Regular icons (React Native)

All regular icon components accept `SvgProps` from `react-native-svg`.

| Prop     | Type               | Default          | Description         |
| -------- | ------------------ | ---------------- | ------------------- |
| `width`  | `string \| number` | `'24'`           | Width of the icon.  |
| `height` | `string \| number` | `'24'`           | Height of the icon. |
| `color`  | `string`           | `'currentColor'` | Fill colour.        |

### Illustrative icons (React Native only)

Illustrative icons extend `SvgProps` with two additional props for theming.

| Prop     | Type                                     | Default     | Description                                                                                                                                                  |
| -------- | ---------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `theme`  | `'light' \| 'dark' \| undefined`         | `undefined` | Force a specific colour theme. When `undefined`, the icon uses its built-in colours. Prefer using the `OnDark` variant over setting `theme="dark"` manually. |
| `colors` | `{ primary: string; secondary: string }` | `undefined` | Override the primary and secondary colours directly.                                                                                                         |

# Logos

- [Figma](https://www.figma.com/design/lSboxfILj3Thr1o145POJv/YDS-Icons-and-Logos?m=auto&node-id=19-201&t=AV91DQjNCbOsTXcs-1)
- [Storybook](https://ds-storybook.test.yle.fi/?path=/story/design-tokens-logos--logo-list)
- [Edit this page](https://github.com/Yleisradio/yle-design-system/blob/main/docs/icons-and-logos/logos.mdx)
- [Create a new issue](https://github.com/Yleisradio/yle-design-system/issues/new)

Each logo is available in several variants:

- **Standard** — default version for light backgrounds
- **Nega** — negative (reversed) version, typically white
- **OnDark** — optimised for dark backgrounds
- **Stripe** — horizontal stripe layout variant
- **Brand** — brand-colour version (where available)

### Areena

|                                                               | Component                    | Description                                       |
| ------------------------------------------------------------- | ---------------------------- | ------------------------------------------------- |
| | `LogoAreena`                 | Areena logo, standard.                            |
| | `LogoAreenaNega`             | Areena logo, negative.                            |
| | `LogoAreenaOnDark`           | Areena logo, for dark backgrounds.                |
| | `LogoAreenaNegaOnDark`       | Areena logo, negative on dark.                    |
| | `LogoAreenaStripe`           | Areena logo, stripe layout.                       |
| | `LogoAreenaStripeNega`       | Areena logo, stripe layout, negative.             |
| | `LogoAreenaStripeOnDark`     | Areena logo, stripe layout, for dark backgrounds. |
| | `LogoAreenaStripeNegaOnDark` | Areena logo, stripe layout, negative on dark.     |

### Arenan

|                                                               | Component                    | Description                                       |
| ------------------------------------------------------------- | ---------------------------- | ------------------------------------------------- |
| | `LogoArenan`                 | Arenan logo (Swedish), standard.                  |
| | `LogoArenanNega`             | Arenan logo, negative.                            |
| | `LogoArenanOnDark`           | Arenan logo, for dark backgrounds.                |
| | `LogoArenanNegaOnDark`       | Arenan logo, negative on dark.                    |
| | `LogoArenanStripe`           | Arenan logo, stripe layout.                       |
| | `LogoArenanStripeNega`       | Arenan logo, stripe layout, negative.             |
| | `LogoArenanStripeOnDark`     | Arenan logo, stripe layout, for dark backgrounds. |
| | `LogoArenanStripeNegaOnDark` | Arenan logo, stripe layout, negative on dark.     |

### Lasten Areena

|                                                                | Component                     | Description                                       |
| -------------------------------------------------------------- | ----------------------------- | ------------------------------------------------- |
| | `LogoLastenAreena`            | Lasten Areena logo, standard.                     |
| | `LogoLastenAreenaBrand`       | Lasten Areena logo, brand-colour version.         |
| | `LogoLastenAreenaBrandOnDark` | Lasten Areena logo, brand-colour version on dark. |
| | `LogoLastenAreenaOnDark`      | Lasten Areena logo, for dark backgrounds.         |

### Yle

|                                                       | Component            | Description                             |
| ----------------------------------------------------- | -------------------- | --------------------------------------- |
| | `LogoYle`            | Yle logo, standard.                     |
| | `LogoYleBrand`       | Yle logo, brand-colour version.         |
| | `LogoYleBrandOnDark` | Yle logo, brand-colour version on dark. |
| | `LogoYleNega`        | Yle logo, negative.                     |
| | `LogoYleNegaOnDark`  | Yle logo, negative on dark.             |
| | `LogoYleOnDark`      | Yle logo, for dark backgrounds.         |

---

# Design Principles

# Design principles

Design principles describe how YDS designs in general. They apply across all of Yle's services and every component, and they explain the intent behind design decisions rather than prescribing a specific solution.

## Principles, patterns and components

- **Design principles** set the direction, for example how motion guides the user and adds expression.
- **[Patterns](../patterns/index.md)** apply that direction to one recurring user need, such as choosing a location or giving feedback on an action.
- **[Components](/docs/components)** are the building blocks both of them are realised with.

When a pattern or a component makes a design decision, it should follow these principles. If a decision conflicts with a principle, raise it with the design system team instead of working around it.

## Available principles

- **[Motion language](./motion-language-principles.md):** how motion guides the user through content and enriches the experience with expressiveness.

# Motion language

The purpose of motion language is to improve interaction with users by providing **clear guidance** and **enriching the experience with expressiveness**.

## Guiding

Guiding motion helps direct the user in the desired direction. Its purpose is to guide the user, acting as a secondary UI element.

### Direction and sequence of motion

Guiding motion defines the order in which elements are presented and the direction of movement, helping the user proceed along their chosen path. Guiding motion uses movement along the X, Y, and Z axes to create clear and intuitive navigation between pieces of content.

### Axes

**Movement on the X and Y axes** indicates direction within the same page or content group.

<div
  style={{
    display: 'flex',
    flexDirection: 'row',
    justifyContent: 'center',
    gap: '1rem',
    alignItems: 'center',
    width: '100%',
    maxWidth: '100%',
    marginTop: '-0.5rem',
    marginBottom: '1.5rem',
  }}
>
  <img
    src={require('../img/liike-1.gif').default}
    alt="X and Y axis motion"
    style={{ maxWidth: '45%', height: 'auto', objectFit: 'contain' }}
  />
  <img
    src={require('../img/liike-2.gif').default}
    alt="X and Y axis motion 2"
    style={{ maxWidth: '45%', height: 'auto', objectFit: 'contain' }}
  />
</div>

X- and Y-axis motion helps the user stay in the same context, such as browsing content within a specific topic area or exploring similar elements within the same view.

**Z-axis motion** clearly guides the user to another page or a separate content group.

<div
  style={{
    display: 'flex',
    flexDirection: 'row',
    justifyContent: 'center',
    gap: '1rem',
    alignItems: 'center',
    width: '100%',
    maxWidth: '100%',
    marginTop: '-0.5rem',
    marginBottom: '1.5rem',
  }}
>
  <img
    src={require('../img/liike-3.gif').default}
    alt="Z axis motion"
    style={{ maxWidth: '45%', height: 'auto', objectFit: 'contain' }}
  />
  <img
    src={require('../img/liike-4.gif').default}
    alt="Z axis motion 2"
    style={{ maxWidth: '45%', height: 'auto', objectFit: 'contain' }}
  />
</div>

Z-axis motion takes the user, for example, from the homepage to an individual content page, from a content page to playback mode and back. This motion is suitable for situations where you want to emphasize a transition to an entirely new context or deeper into the content hierarchy.

## Expressive

Expressive motion complements guiding motion by adding depth and naturalness and by creating emotional connections that enrich the brand experience. It helps make the experience memorable and pleasant.

### User journey stages and expressiveness

#### Interest

At the beginning of the user journey, expressive motion focuses on presenting content and capturing the user’s attention. The motion is soft and considered, creating a strong first impression that encourages the user to explore the service further.

<div style={{ display: 'flex', justifyContent: 'center', marginTop: '2rem', marginBottom: '2rem' }}>
  <img
    src={require('../img/interest.png').default}
    alt="Interest stage"
    style={{ maxWidth: '85%', height: 'auto' }}
  />
</div>

#### Engagement

As the user journey progresses, expressive motion decreases and becomes more subtle, focusing on supporting the user’s actions without unnecessary interruptions. The motion maintains the service’s consistency and makes the user experience harmonious and pleasant.

<div style={{ display: 'flex', justifyContent: 'center', marginTop: '2rem', marginBottom: '2rem' }}>
  <img
    src={require('../img/engagement.png').default}
    alt="Engagement stage"
    style={{ maxWidth: '85%', height: 'auto' }}
  />
</div>

#### Decision

As the user approaches the decision stage, expressive motion becomes even more subtle, providing clarity and naturalness in interactions.

<div style={{ display: 'flex', justifyContent: 'center', marginTop: '2rem', marginBottom: '2rem' }}>
  <img
    src={require('../img/decision.png').default}
    alt="Decision stage"
    style={{ maxWidth: '85%', height: 'auto' }}
  />
</div>

When the user experience ends, expressive motion returns to supporting the presentation of the next content and encourages the user to continue the experience.

## Transition tokens

[Transition tokens](../design-tokens/transitions) define standardized animation values for the design system. They provide a shared language for motion, ensuring consistency and predictability across digital services.

### Easing

Easing controls how motion accelerates and decelerates, affecting the rhythm and feel of transitions. Different curves—decelerate, accelerate, bounce—support different goals such as guiding attention, emphasizing feedback, or creating expressive moments.

### Duration

Duration defines how long an animation takes. Consistent values create clear hierarchy and pacing, from short micro-interactions to longer full-screen transitions. Use duration to make motion feel smooth and appropriate for each context.

### Delay

Delay defines when an animation starts relative to a user action or another animation. Use it for rhythm and sequencing when multiple elements appear in order. Apply sparingly—delays can reduce responsiveness, so use only when they clearly improve clarity or visual continuity.

## Motion types

- **Real-time:** Animations that happen in direct, immediate interaction with the user.
- **Delayed:** Animations that occur after the user’s action and may include delays.
- **Autonomous:** Animations that do not require direct user action.

## Motion properties

### Time and speed

- **Easing (smoothness of motion):** Controls acceleration and deceleration.
- **Duration:** Defines how long the motion lasts.
- **Delay:** Defines when the motion starts.

### Position and movement

- **Move:** Defines an element’s movement on the X, Y, and Z axes.
- **Anchor point:** Defines the point around which motion such as rotation and scaling occurs.
- **Rotation:** An element’s rotation around a defined axis and anchor point.
- **Path:** Defines the route an element follows during motion.

### Visual appearance

- **Opacity:** Changes an element’s visibility.
- **Morph:** Changes an element’s shape between states.
- **Scale:** Changes an element’s size.
- **Color:** Changes an element’s color.
- **Blur:** Softens an element, making it less sharp.

## Motion patterns

[Motion patterns](/docs/design-tokens/transitions#motion-patterns) define reusable animation solutions for different interaction contexts. They help ensure consistency, usability, and clarity across services by guiding how motion supports feedback, navigation, and user understanding. Motion patterns connect the motion language, design tokens, and interaction principles into practical and scalable implementations.

---

## Micro-interactions

A micro-interaction is a small, tightly scoped interaction detail that happens within a single UI element or action. It typically responds to just one user action, such as pressing a button.

### Principles

- **Clarity and simplicity:** Micro-interactions support UI logic without unnecessary complexity. Even a small motion is enough to communicate meaning.
- **Consistency:** Keep micro-interactions consistent with the service’s motion language and other UI parts so users can predict interactions.
- **Fast and smooth motion:** Micro-interactions are short and fluid. Feedback duration is typically 70–250 ms, and guiding micro-interactions 250–450 ms.
- **Surprise and delight:** Add joy through small, thoughtful details that make the experience more pleasant without distracting from use.

**Goal**  
Micro-interactions improve the user experience by providing feedback, guiding attention, and bringing quality and delight to the service. When well designed, they make the UI intuitive and memorable without disrupting the user’s focus.

### Examples of microinteractions

**Buttons**  
Button motion focuses on clear feedback and confirming the user’s action. Each state (hover, down, release) communicates the button state and action feedback. Subtle scaling and text movement create a sense of physicality, making interactions feel natural and understandable. In loading states, motion continuity connects different phases and reinforces progress. Clear focus movement between buttons supports navigation.

**Toggle switch**  
Motion clearly communicates the change of state. A visual and dynamic transition reinforces that the state has changed. Clear color and movement improve visual differentiation and accessibility.

**Loading indicator**  
Continuous motion creates a sense of progress and keeps the user’s attention during waiting states. A clear and familiar animation ensures the user understands that the system is active.

**Tab indicator**  
Smooth motion under the selected tab guides attention and reinforces the active state. Simple and precise movement improves clarity and navigation.

---

## Interactions

Interactions cover broader user–UI flows and often include multiple steps and micro-interactions. Well-designed interactions make even complex processes clear and user-friendly.

### Key principles

- **Clarity and logic:** The user should easily understand the process steps and next actions.
- **Guidance and feedback:** Provide direction and reinforce actions with feedback.
- **Fast and intuitive motion:** Motion should be simple and focus on what matters.
- **Multi-step processes:** Each step should be highlighted clearly and logically through motion.

**Goal**  
The goal of interactions is to connect elements into a seamless experience that is intuitive, smooth, and aligned with the service’s motion language. A well-designed interaction makes the service pleasant to use in all situations.

### Examples of interactions

**Modal dialog**  
Modal motion emphasizes importance and hierarchy. Background content scales and dims to create depth and indicate that the user remains in the same context. Soft scaling and fading guide attention to the modal while maintaining a visual connection to the background.

**ADD MORE EXAMPLES HERE**

---

## Transitions

Transitions are motion and animation patterns that help users move between states, views, or hierarchy levels. They provide spatial and visual continuity and support understanding of structure and navigation.

### Use of axes

- **Z axis:** Used when moving to a new content group or to a hierarchically higher or lower level. This creates depth and a clear separation between content.
- **X and Y axes:** Used within the same content group or between content on the same hierarchy level.

Transitions should primarily use one axis at a time to keep motion clear and easy to follow.

### Key principles

- **Clarity and hierarchy:** Motion direction and spatiality should communicate how views relate to each other.
- **Consistency:** The same axis and direction should always represent the same logic.
- **Guiding focus:** Primary content moves first, and secondary elements follow.
- **Visual continuity:** Motion should connect old and new views through position, scale, or shape.
- **Forward and backward rhythm:** Forward transitions are slower, backward transitions faster to support hierarchy and efficient navigation.

Example speeds:  
Forward 750 ms → Back 450 ms  
Forward 450 ms → Back 250 ms  
Forward 250 ms → Back 150 ms

### Examples of transitions

**Content transitions**  
Elements visually transform while preserving continuity. Smooth motion emphasizes relationships between content and reinforces structure. Z-axis movement supports spatial understanding.

**Forward and backward navigation**  
Used within the same hierarchy level. Motion should be clear, smooth, and consistent. X-axis movement reinforces continuity and spatial logic.

**Top-level navigation**  
Transitions between main sections should be clear and consistent. Content should load through an empty state, avoiding crossfades. Direction should follow platform navigation patterns.

**Loading transitions**  
Loading indicators communicate progress and prevent layout shifts.

- **Skeleton loader:** Motion reflects content structure and hierarchy. Movement progresses top-to-bottom and left-to-right. It should remain smooth, subtle, and simple.
- **Spinner:** Provides reassurance that the system is active and working.

### Applying transitions

- **Consistency:** All transitions should follow the same logic throughout the UI.
- **Stable layouts:** Use loading indicators (e.g., skeleton loader) to avoid layout shifts or jumps.
- **No abrupt transitions (jump cuts):** Transitions should be seamless and natural.
- **Logical state model:** Element motion should tell the user what state they are in, where they came from, and where they are going.
- **Unified direction:** Motion direction must be consistent and support UI navigation.
- **Clear fades:** Ensure elements disappear or appear clearly without disturbances. Elements should not be visible on top of each other (cross-fade).
- **Simple style:** Motion should be simple and intuitive, without unnecessary emphasis.

## Naming convention

Token naming in the Yle Design System (YDS) follows a clear and structured pattern to ensure consistency, clarity, and reuse across all digital services. The goal is to create names that are easy to understand for both designers and developers. Each token is unique and identifiable, communicates its purpose and context, follows a consistent hierarchy and structure, and avoids conflicts with commonly used terminology and code libraries.

---

# Using YDS

# Breaking changes in React package 3.0

`@yleisradio/yds-components-react` 3.0 drops `styled-components`, ships styles as CSS Modules, and applies color themes (and other design tokens) through CSS custom properties instead of React context.

**Component props are unchanged.** What breaks is theming, bundler setup, and anything that read the old theme object. Behaviorally and visually components themselves are virtually unchanged besides some small bugs that were found in re-implementation phase.

## TL;DR migration plan

The app bundler must process `*.module.css` from this package (including under `node_modules`). Confirm YDS tokens are still on the application root as CSS custom properties — they were required in 2.x as well; file lists: [Get started](./get-started-with-v3.md#3-put-tokens-on-root). If `styled-components` was only a YDS peer, you can remove it.

If the app **keeps** styled-components as its own styling library, convert `props.theme.yds` reads with [Using styled-components with YDS 3.0](./styled-components-to-css.md). That work can land on 2.x first: `defaultTheme` and the token CSS already ship in `@yleisradio/yds-core` 2.x.

## At a glance

| 2.x | 3.0 |
| --- | --- |
| `styled-components` is a peer dependency | Not a peer. YDS does not render a styled-components `ThemeProvider` |
| `YdsThemeProvider` put tokens on React context (`props.theme.yds`) | Theme tokens are used as CSS custom properties. `YdsThemeProvider` now pushes CSS variables in a `<style>` block targeting a wrapper. |
| `YdsThemeProvider` `theme` defaulted to `'light'` | `theme` defaults to `'default'` (follows `prefers-color-scheme`) |
| `unit` / `baseUnit` converted px/rem sizes at runtime | Props removed. Component CSS uses `rem` at `1rem = 16px` baseline |
| A root provider themed the whole app, including portals | Import token CSS onto `:root`. The provider themes only its subtree |
| Styles were styled-components output (unlayered) | Unprocessed `.module.css` in `@layer yds`. The app bundler must process them |
| `yds-core` `defaultShadow` held literal light `box-shadow` strings | `defaultShadow` holds `var(--yds-shadow-*, <light fallback>)` |

## Styled-components is no longer a peer

YDS does not depend on `styled-components`. You can keep it in the app, or drop it if it was only there for YDS.

2.x rendered styled-components' `ThemeProvider` inside `YdsThemeProvider` and replaced the theme with `{ ydsThemeName, yds, ydsThemeProps }`. 3.0 renders no such provider:

- `props.theme.yds`, `props.theme.ydsThemeName`, and `props.theme.ydsThemeProps` are gone.
- If `YdsThemeProvider` was the only styled-components provider in the tree, `props.theme` is now `{}` and **every** `props.theme.*` read breaks, not only the YDS ones. Render your own `<ThemeProvider>` if the app still needs one.
- If your provider sat *outside* `YdsThemeProvider`, 2.x was shadowing it inside that subtree. Those keys become visible again.

The packaged `styled-components` `DefaultTheme` augmentation is gone. If the app keeps its own `styled.d.ts` with `yds` / `ydsThemeName` / `ydsThemeProps`, those reads still type-check and fail at runtime. Delete the YDS fields before upgrading.

If the app keeps styled-components, convert `theme.yds` usage with [Using styled-components with YDS 3.0](./styled-components-to-css.md).

## `YdsThemeProvider` themes a subtree, not the document

YDS component styles now uses design tokens as CSS custom properties. `yds-core` tokens belong on application root as CSS. File lists: [Get started](./get-started-with-v3.md#3-put-tokens-on-root). [YdsThemeProvider](../../components/YdsThemeProvider/YdsThemeProvider.md) is an alternative for a subtree or a React-driven `theme`. It does not write to `:root` unless you pass `scope=":root"` as a transitional step.

`theme` now defaults to `'default'`, which follows `prefers-color-scheme`. Pass `theme="light"` to keep 2.x behavior.

Tokens inherit through the DOM. Content you portal out of the subtree does not get them. Apply `useThemeContext().className` to the portal container, or put tokens on `:root`.

## `unit` and `baseUnit` are removed

Component CSS uses `rem` on a `1rem = 16px` baseline. There is no runtime conversion. Make sure your `:root` font size is not a fixed/percentage-based value for accessibility.

If you used `ydsThemeUnit` for font sizing, it's still exported. 2.x read `unit` / `baseUnit` from `props.theme.ydsThemeProps`. Pass the values yourself, or delete the call: a 2.x provider defaulted to `rem` at 16px, which is what 3.0 already emits.

> **Warning**
> `ydsThemeUnit(value)` defaults to `'px'`, not to the `'rem'` the 2.x provider defaulted to. Pass `'rem'` explicitly or remove the helper.

If the app used `unit="px"` or a custom `baseUnit`, convert once in PostCSS (`postcss-rem-to-pixel`, `postcss-pxtorem`) instead of at every call site.

## Bundler must process CSS Modules from this package

Styles ship as unprocessed `*.module.css` next to the compiled JavaScript, with `"sideEffects": ["*.css"]` so they are not tree-shaken away. The app bundler has to compile those files **including under `node_modules`**. Token files from `@yleisradio/yds-core` must stay **global** CSS (not hashed).

What each setup needs:

- **Vite** — works out of the box. Add [`vite-css-modules`](https://github.com/privatenumber/vite-css-modules) so shared `composes` rules are not duplicated into every module. Do not enable `localsConvention`.
- **Webpack 5** — `css-loader` must include `@yleisradio/yds-components-react` and `@yleisradio/yds-core`. Drop any `exclude: /node_modules/` on the CSS rule. On `css-loader` 7+, set `namedExport: false` and `exportLocalsConvention: 'as-is'`.
- **Next.js** — add the package to `transpilePackages`, along with every dependency that uses YDS 3 components (shared component libraries, for example). Next.js cannot load CSS Modules from untranspiled `node_modules` code at runtime. Import token CSS from a root layout or global stylesheet.
- **Jest** — map `\.css$` to `identity-obj-proxy`.
- **Vitest** — set `css: false` and inline `/@yleisradio\/yds-/` under `server.deps.inline`.

Config snippets: [Bundler setup in the package README](https://github.com/Yleisradio/yle-design-system/blob/main/packages/yds-components-react/README.md#bundler-setup).

An optional bundled `all.css` with stable class names exists for CDN and prototypes without React. Importing it together with the React components duplicates styles: the components still use hashed CSS Module names. Class grammar: [CSS class naming conventions](./css-conventions.md).

## Global resets beat `@layer yds` \{#global-resets\}

Library styles live in `@layer yds`. Layer order is resolved **before** specificity, so an unlayered `* { margin: 0; padding: 0 }` strips padding and margins from every component.

Put the reset in a layer below `yds`, and declare `@layer reset, yds, app;` in the first stylesheet the app loads — before any component CSS is imported:

```css
@layer reset, yds, app;

@layer reset {
  *,
  *::before,
  *::after {
    box-sizing: border-box;
  }

  * {
    margin: 0;
    padding: 0;
  }
}
```

`box-sizing: border-box` on `*` is what YDS is built against; leave it. It is `margin: 0` and `padding: 0` that collide.

If the reset cannot be layered (a host page, a shared bundle), unwrap `@layer yds` in the app build. Apps that inject the reset through styled-components' `createGlobalStyle` have extra constraints: [Using styled-components with YDS 3.0 — Global CSS resets](./styled-components-to-css.md#resets).

## `defaultShadow` follows the active theme

In `@yleisradio/yds-core`, `defaultShadow` now exports `var(--yds-shadow-*, <light value>)` references, matching `defaultTheme`. Shadows read through it follow the document theme instead of staying light.

The literal fallback keeps CSS usage rendering when the shadow token CSS is absent. Values read **outside a CSS context** (string comparison, canvas, native APIs) no longer resolve to a finished `box-shadow`. Use `lightShadow` to pin the previous literals.

## What does not change

- Public component props.
- Component visual identity and functionality.
- JS token imports from `@yleisradio/yds-core`: `spacing`, `radius`, `typography`, `border`, `transition`, `color`, and the theme objects. Interpolating `spacing.SPACING_16` into styled-components is still valid.
- `ydsThemeUnit` remains exported (although you probably shouldn't need it).
- You do not have to leave styled-components. It is just no longer required by YDS.

## Related

- [Get started with yds-components-react 3.0](./get-started-with-v3.md) — Install, tokens, first component.
- [Using styled-components with YDS 3.0](./styled-components-to-css.md) — If the app keeps styled-components.
- [CSS class naming conventions](./css-conventions.md) — Local names and `all.css` mapping.
- [YdsThemeProvider](../../components/YdsThemeProvider/YdsThemeProvider.md) — Alternative to token CSS for a subtree or React-driven theme.

# CSS class naming conventions

> There are only two hard things in Computer Science: cache invalidation and naming things.
>
> — Phil Karlton

This page describes how YDS names classes in CSS Modules and in the bundled `all.css`. Follow this when you add or change styles in `@yleisradio/yds-components-react`.

There are three distributions from the **same** `.module.css` source:

| Distribution      | Class names               | Who uses it                                      |
| ----------------- | ------------------------- | ------------------------------------------------ |
| As-is CSS Modules | Hashed by the app bundler | React apps                                       |
| CSS Modules export | Hashed by the app bundler | Non-React web apps with a bundler step            |
| Bundled `all.css` | Stable, readable          | CDN, prototypes, HTML without a bundler          |

The hashed and bundled distributions share one source. To emit `all.css` names from CSS Modules instead of hashes, set the bundler’s `generateScopedName` — see [Get started — Matching `all.css` class names](./get-started-with-v3.md#matching-allcss-class-names-from-css-modules). A regression test asserts the published `all.css` contains every selector of the unpublished rollup bundle.

Local names in the module are the contract. `all.css` only prefixes them.

CSS Modules outside React use the same local names as React. Import from `@yleisradio/yds-components-react/Button.module.css` (short) or `@yleisradio/yds-components-react/styles/components/Button/Button.module.css` (deep). See [Get started — Without React](./get-started-with-v3.md#without-react).

## Grammar

`--` modifiers are not used: they are awkward as JavaScript identifiers (`styles['variant--primary']`). The separator is a single underscore.

`yds-[Component]` is added only when bundling `all.css`. Do not write that prefix in `.module.css`.

| Situation                | Local class           | `all.css`                         |
| ------------------------ | --------------------- | --------------------------------- |
| Root                     | `root`                | `yds-Button`                      |
| Element                  | `TextWrapper`         | `yds-Button__TextWrapper`         |
| Boolean prop when `true` | `isDisabled`          | `yds-Button__isDisabled`          |
| Named prop value         | `variant_primary`     | `yds-Button__variant_primary`     |
| Element + prop           | `TextWrapper_size_xs` | `yds-Button__TextWrapper_size_xs` |

**Elements are PascalCase** (initial capital). **Props are camelCase** (initial lowercase). A consumer — or a small helper — can tell them apart without a lookup table:

- starts with `A–Z` → element; anything after the first `_` is a modifier
- otherwise → prop on the root

In `all.css`:

```
yds-Button
yds-Button__variant_primary
yds-Button__isDisabled
yds-Button__TextWrapper
yds-Button__TextWrapper_size_xs
```

`generateScopedName` maps `root` to `yds-[Component]` with **no** `__root` suffix. Every other local name becomes `yds-[Component]__[local]`.

### Module name vs component name

`[Component]` is the module's basename for almost every module, but not all of them: some slots are styled in an internal base component while consumers know them by the name they import. Those are resolved through a map, so **do not** hand-write `yds-[basename]`:

| Module | `all.css` prefix |
| ------ | ---------------- |
| `BaseCheckbox.module.css` | `yds-Checkbox` |
| `BaseRadio.module.css` | `yds-Radio` |
| `BaseNotification.module.css` | `yds-Notification` |

Modules with no public component of their own (`CheckableLabel`, `ChoiceContainer`, `Message`, `SliderRange`) keep their own name — they are internal chrome, not a slot you are meant to target. `Combobox.module.css` also keeps `yds-Combobox` even though the React export is `ComboboxSingleSelect`: the single/multi distinction is React-side, and a future `ComboboxMultiSelect` shares this styling.

The map ships with the package as `@yleisradio/yds-components-react/scoped-name`. Import it rather than reimplementing it — see [Get started — Matching `all.css` class names](./get-started-with-v3.md#matching-allcss-class-names-from-css-modules).

Do not camelCase a prop into the element name. `Title_size_md`, never `titleSize_md`.

## Building names from props

For `all.css` consumers the public React prop names are the vocabulary.

| Prop                             | Class                                                                  |
| -------------------------------- | ---------------------------------------------------------------------- |
| `variant="primary"`              | `variant_primary`                                                      |
| `size="md"`                      | `size_md`                                                              |
| `isDisabled={true}`              | `isDisabled`                                                           |
| `disabled` (html attribute)      | `root[disabled]` (in addition to a possible prop class)                |

Boolean classes are omitted when the value is `false`. Derived internals (`hasIconBefore`) should be avoided: prefer a sibling selector (`.IconWrapper + .TextWrapper`) so HTML consumers do not have to reconstruct React-only state. Button does this — `.root:not(:has(.IconWrapper ~ .TextWrapper))` replaced its `hasIconBefore`.

`TextInput` is the documented exception. Its leading and trailing slots are not distinguishable from markup: `iconClear` and `icon` both render an `IconWrapper_after`, and `submitButton` is a slotted child whose classes come from another module. `hasIcon`, `hasIconBefore`, `hasIconAfter` and `hasUnit` therefore stay on `.root`. Reach for a derived class only when the structure genuinely cannot express the state, and say why in the module.

A helper is optional DX, not a second source of truth. If you add one, generate it from the same local names.

## Root

`root` is the public node: the element that receives `className`, `ref`, and native props.

- **Select:** `root` is `<select>`, not the fieldset. The fieldset is `Fieldset`; the chrome around the select is `Wrapper`.
- **CheckboxGroup:** the group component’s outermost node is `root`, not `Container`. `Container` is only a grouping slot _inside_ another component.

Every component module should define `.root`.

### Modules without `.root`

These modules intentionally omit `.root` because the styled public node lives in another module:

| Module | Reason |
| ------ | ------ |
| `SearchInput.module.css` | Only styles `SubmitButton`; the input root is `TextInput.module.css`. |
| `Slider.module.css` | Only styles fieldset chrome; the control root is `SliderRange.module.css`. |

### Two exports, one module

| Module | `root` maps to | Other outer slot |
| ------ | -------------- | ---------------- |
| `Accordion.module.css` | `AccordionItem` (the expandable panel) | `List` on the `Accordion` list wrapper |
| `PageIndicator.module.css` | `PageIndicator` (the dot button) | `Container` on `PageIndicatorContainer` |
| `ToastNotification.module.css` | `ToastNotification` (single toast wrapper) | `Container` on `ToastNotifications` |
| `SectionTabs.module.css` | `SectionTabs` (the positioning wrapper) | `List` on `SectionTabList`, `Tab` on `SectionTab` |

`NavigationTab` and `NavigationTabList` used to share a module, which left the tab button — the node that receives `className` — without a `root`. They now have one module each. Prefer that split over a shared module whenever both exports render a public node.

## Prop classes live on `.root`

Boolean and named prop classes (`isDisabled`, `size_md`, `variant_primary`, `type_banner`, `isOpen`) belong on **`.root`** in TSX. In CSS, style descendants with a **cascade selector**; use **`Element_prop_modifier`** only when the element is not a `.root` descendant or when the class is passed to another component’s root.

| Situation | CSS pattern | TSX |
| --------- | ----------- | --- |
| Root prop, element is a descendant | `.isDisabled .Title { … }` | `isDisabled && styles.isDisabled` on `.root` only |
| Chrome that **wraps** `.root` (parent, not descendant) | `.Wrapper:has(.error) { … }` | prop class on `.root` only |
| Per-item state on a repeating row | `.MenuItem_isSelected { … }` | only when the prop varies per row and cannot live on `.root` |
| Class passed via `appearanceClassName` onto Button | `.GroupButton_isSelected { … }` | prefix with the slot name — never bare `isSelected` |
| Element needs a shared primitive per prop value | `.Title_size_md { composes: typography_md_bold from … }` | `` styles[`Title_size_${size}`] `` on the element |

Prefer **`.prop .Element`** over **`.Element_prop`** whenever the prop applies to the whole component instance. When the chrome **contains** `.root` (a `Wrapper` around an `<input>`), cascade cannot reach it — use **`:has()`** from the wrapper (`.Wrapper:has(.error)`), not a second copy of the prop class on the wrapper or the fieldset. Use `.Element_prop` only for per-row state (Combobox menu items), when the styled node is outside the component subtree, or when the rule needs `composes`.

`composes` is a class-to-class link, so it is only valid on a rule whose selector is a **single local class**. `.size_md .Title { composes: … }` fails the build with `composition is only allowed when selector is single :local class name`. Split the rule: keep layout in the cascade selector and put the composition on `Element_prop`.

```css
/* Accordion.module.css */
.Title_size_md {
  composes: typography_md_bold from '../../internal/styles/typography.module.css';
  padding: 0.75rem 1rem;
}
```

In CSS Modules, `composes` puts the composed class on the element next to `Title_size_md`. `all.css` has no such mechanism, so its build copies the composed declarations into the composing rule instead: `.yds-Accordion__Title_size_md` carries the typography itself. The copies come first, so the component's own declarations still win. Selectors that target the composed class (pseudo-classes, descendants) are rewritten onto the composing class too.

Do **not** write `.Title.isDisabled` or `.Menu.isOpen`: in `all.css` that produces `yds-Accordion__isDisabled` on a non-root node, which breaks the grammar.

```css
/* Accordion.module.css — cascade from item root */
.isDisabled .Title {
  color: var(--yds-color-text-disabled);
}

.iconAlign_start .Title {
  justify-content: flex-start;
}
```

```tsx
<div className={cx(styles.root, styles[`size_${size}`], isDisabled && styles.isDisabled)}>
  <button className={cx(styles.Title, styles[`Title_size_${size}`])} aria-disabled={isDisabled} />
</div>
```

Regression tests in `packages/yds-components-react/src/cssConventions.spec.ts` enforce these rules against a parsed selector tree, so `:not()` and `:has()` cannot hide a compound. They also check that prop classes only land on the node carrying `.root`, that no prop class is copied onto a second node, that every `styles[...]` reference resolves to a declared local, and that each `Element_prop` family has a matching prop class on `.root`.

That last rule has an allowlist, because three cases legitimately have no root counterpart:

- the class is handed to **another component's root** (`GroupButton_*` via `appearanceClassName`);
- it is **per-row state** that varies within one instance (`MenuItem_isSelected`, `Tab_isActive`);
- the styled node sits **outside the root subtree** (`Description_direction_horizontal` is a sibling of `.root` inside the fieldset).

A composes-only family is the fourth: `Dialog`'s `Title_size_*` exists solely to attach typography, and size changes nothing else on the dialog, so no cascade rule declares a root `size_*`. Where a dimension needs *both* a composition and other declarations, write the cascade rule too — `.menuSize_md .Menu` declares the root class that `MenuItem_menuSize_md` then satisfies. Add an allowlist entry only when there is genuinely nothing to put on the root.

Use these names when the slot matches. Component-specific PascalCase names are allowed when nothing below fits. Do **not** invent synonyms (`Box`, `Inner`, `Holder`, `Shell`).

### Shells

| Local            | Meaning                                                                               |
| ---------------- | ------------------------------------------------------------------------------------- |
| `Wrapper`        | Chrome around a **single** control, not the root. Example: a `div` around `<select>`. |
| `Container`      | Chrome around **several similar** elements, inside another component. Example: Checkbox group with multiple Checkbox components. |
| `IconWrapper`    | Shell around an SVG or icon component.                                                |
| `SpinnerWrapper` | Shell around `<Spinner>`.                                                             |
| `[Slot]Wrapper`  | Other inner shell that may hold another component (`TextWrapper`, `LabelWrapper`).    |

### Form

| Local          | Meaning                                             |
| -------------- | --------------------------------------------------- |
| `Fieldset`     | `<fieldset>`                                        |
| `Legend`       | `<legend>` — not `Label`                            |
| `Label`        | `<label>` or the node targeted by `aria-labelledby` |
| `Description`  | Longer helper text                                  |
| `ErrorMessage` | Error text                                          |
| `Input`        | `<input>` when it is not `root`                     |
| `Option`       | `<option>` — `Item` is an `<li>` or selectable repeating row   |
| `Unit`         | Suffix such as `€` or `%`                           |
| `Counter`      | Character counter                                   |

If `Label` is a separate `FormElementLabel` component, its classes are `yds-FormElementLabel`, not `yds-Select__Label`.

### Structure

| Local     | Meaning                                                         |
| --------- | --------------------------------------------------------------- |
| `Header`  | Top region                                                      |
| `Footer`  | Bottom region (chrome, not the button list)                     |
| `Title`   | Heading text                                                    |
| `Content` | Main slot                                                       |
| `Actions` | Action slot. `Footer` is the region; `Actions` is its contents. |

### Overlay and disclosure

| Local         | Meaning                                                                          |
| ------------- | -------------------------------------------------------------------------------- |
| `Dialog`      | Inner `<dialog>` chrome when it is **not** `root`. Modal and BottomSheet use `root` on `<dialog>`. |
| `Handle`      | Drag handle                                                                      |
| `CloseButton` | Close control — allowed because the slot is universal                            |
| `Trigger`     | Opening control when it is not `Title`                                           |
| `Panel`       | Revealed region (tab / accordion) when you need to distinguish it from `Content` |
| `Menu`        | Popup list, not necessarily a `<ul>`                                             |

### Collections

| Local       | Meaning                       |
| ----------- | ----------------------------- |
| `List`      | `<ul>` / `<ol>`               |
| `Item`      | `<li>` or repeating row       |
| `Separator` | Divider                       |
| `Nav`       | `<nav>` when it is not `root` |

### Meters

| Local       | Meaning                                           |
| ----------- | ------------------------------------------------- |
| `Track`     | Track (progress, slider)                          |
| `Fill`      | Fill of the track                                 |
| `Thumb`     | Slider knob, if it is its own node                |
| `Indicator` | One-of-N mark (page dots). Not the progress fill. |

### Other recurring slots

| Local      | Meaning                                                                        |
| ---------- | ------------------------------------------------------------------------------ |
| `Icon`     | The icon itself, usually SVG. The shell is `IconWrapper`.                      |
| `Badge`    | Decoration on another component                                                |
| `Underlay` | Hit area behind a control                                                      |
| `Button`   | Nested button that is not the root. Use `SubmitButton` when the slot is fixed. |

### Not element names

- **VisuallyHidden** — the internal `VisuallyHidden` module (`yds-VisuallyHidden` in `all.css`), not `yds-Select__VisuallyHidden`. `.yds-visually-hidden` in `utilities.css` is the same treatment for markup outside YDS.
- **Backdrop** — only if it is a real DOM node. `::backdrop` is not a class.
- **Spinner / Select / Checkbox** as a child class — that is another component, not a local name on the parent.

## Authoring

```css
/* Button.module.css */
.root {
  /* … */
}
.variant_primary {
  background-color: var(--yds-color-action-primary);
}
.isDisabled {
  cursor: not-allowed;
}
.TextWrapper {
  display: block;
}
.TextWrapper_size_xs {
  padding-left: 0.25rem;
}
.IconWrapper {
  display: inline-block;
}
```

```tsx
className={cx(
  styles.root,
  styles[`variant_${variant}`],
  isDisabled && styles.isDisabled
)}
```

Shared primitives live in `src/internal/styles/` (`typography.module.css`). Compose those; do not copy token values. Focus rings are written in the component module, not composed.

## Cross-component styling

Do not add a second, kebab-case global BEM name (`yds-Button__TextWrapper`) next to the module class. This risks getting all.css to spread in micro-frontend architecture, where an app uses no hashes.

A parent must not select another component’s hashed internals. Instead:

1. **Put the style where the markup is.** ButtonGroup applies Button’s own `inGroup` class from `Button.module.css` onto the Button root (via `className` or `appearanceClassName`). Button then styles `.inGroup .TextWrapper`. That is not a public React prop.
2. **Pass color through a custom property.** Parents set `--yds-spinner-stroke-color`; Spinner’s wheel reads it with a token fallback. No `:global(.yds-spinner)` pierce.

Theme classes are a **different** contract: `yds-theme-light`, `yds-theme-dark`. They are global, kebab-case, and stable across every distribution — they are not component slots, so they carry no `yds-[Component]__` prefix.

`yds-use-focus`, `yds-focus`, `yds-focus-ring` and `yds-visually-hidden` are the same kind of name, for elements **outside** YDS. YDS components do not use them.

### Focus on YDS components

Each component states its focus ring in its own `.module.css`. Repeat the standard declaration, including the `var()` fallbacks, so the ring is visible without `utilities.css`:

```css
.root:focus-visible {
  outline: var(--yds-focus-outline-width, 3px) var(--yds-focus-outline-style, solid)
    var(--yds-focus-outline-color, var(--yds-color-border-primary-focus));
  outline-offset: var(--yds-focus-outline-offset, 2px);
}
```

A control with its own colour, offset, or extra declarations uses those in the same kind of rule. Do not select `:global(.yds-focus)` from a component module. That class is only for non-YDS elements.

### Global utilities are an app import

Declare those classes in `src/utilities.css`, a plain stylesheet at the package root, **not** under `internal/` and **not** in a `.module.css`. The file is only for app markup. Its rules are in `@layer yds`, same as the components. Left unlayered, they would beat every component focus ring and `:where()` would not protect those rings.

Next.js hardcodes `mode: 'pure'` for CSS Modules, and pure mode rejects any selector that contains no local class. It also rejects a global `.css` import whose importer lives inside `node_modules`. Importing `utilities.css` from the package barrel fails a Next.js build on every `import` from `@yleisradio/yds-components-react`.

Apps that need the classes import the file from their own entry, where global CSS is allowed (`pages/_app` or the root `layout`):

```ts
import '@yleisradio/yds-components-react/utilities.css';
```

`all.css` already appends the same file.

`yds-use-focus` on a wrapper (`body`, a layout root) draws the ring for `:focus-visible` in that subtree. `yds-focus` is the same ring on one element. `yds-focus-ring` shows it without `:focus-visible`. The subtree selector is `:where(.yds-use-focus, .yds-use-focus *)`, so its specificity stays below a component's own `:focus-visible` rule.

`internal/styles/disableBodyScroll.css` stays a side-effect import from Modal and BottomSheet, because it targets `body`.

Pairing a global **with** a local in the same selector stays pure and is still fine inside a module:

```css
:global(.yds-theme-dark) .root {
}
```

`cssConventions.spec.ts` asserts every selector in every module contains a local class, and that no component module targets `:global(.yds-focus)`.

### Restyling the focus ring

The ring is two properties — `outline-offset` is not part of the `outline` shorthand — so it cannot be a single value. The shorthand is composed from sub-tokens, so an app or a custom theme can change one part without restating the rest:

| Custom property | Default |
| --- | --- |
| `--yds-focus-outline-width` | `3px` |
| `--yds-focus-outline-style` | `solid` |
| `--yds-focus-outline-color` | unset — falls back to `--yds-color-border-primary-focus` |
| `--yds-focus-outline-offset` | `2px` |

`--yds-focus-outline-color` is deliberately **not** declared on `:root`, and there is no composed `--yds-focus-outline` shorthand token. A custom property substitutes its `var()` at the element that declares it, so resolving the colour on `:root` would freeze the root theme's value and inherit it into every `.yds-theme-light` / `.yds-theme-dark` subtree — scoped themes would draw the wrong focus colour. Reading the token at the use site instead keeps a consumer override working *and* follows a scoped theme. The same rule applies to any future token that references a theme-dependent value.

```css
/* Thicker ring everywhere, colour and offset untouched */
:root {
  --yds-focus-outline-width: 4px;
}
```

Any rule that draws the ring must apply **both** `outline` and `outline-offset`, and repeat the defaults as `var()` fallbacks, so the ring still shows when the app has not imported `utilities.css`. Importing that file is what publishes the custom properties on `:root`, which is how an app changes the ring everywhere.

## What to avoid

- kebab-case locals or `--` modifiers
- `__element` / `_modifier` prefixes in the module (they would triple-underscore after `generateScopedName`)
- Combinatorial classes that encode several props (`grid_banner_icon_actions_close`) — use separate modifiers. Notification layout templates in `BaseNotification` are a known exception: they are mutually exclusive `grid-template-areas` maps, not independent props.
- Using the component name as the root class (`checkboxGroup`, `spinner`, `RadioBase`, `Dialog`) — use `root`
- Chaining a prop class onto a non-root element (`.Menu.isOpen`, `.Grid.type_banner`) — put the prop on `.root` and cascade (`.isOpen .Menu`) or use `Element_prop` (`.MenuItem_isSelected`)
- Documenting a parallel kebab namespace for `all.css`
- A rule in a `.module.css` whose selector has no local class (`:global(.yds-focus) { … }`) — it fails Next.js's pure mode. External classes belong in `src/utilities.css`, which the app imports itself
- `:global(.yds-focus)` on a component selector — YDS focus is written in the component module

### `all.css` class renames (3.1.0 convention fix)

`all.css` and direct CSS Module imports are not part of the versioned package API, so these renames ship in a minor release. If you referenced `all.css` names before this cleanup, update as follows:

| Component | Old local / `all.css` fragment | New |
| --------- | ------------------------------ | --- |
| BaseRadio | `RadioBase` / `yds-Radio__RadioBase` | `root` / `yds-Radio` |
| Modal, BottomSheet | `Dialog` / `yds-Modal__Dialog` | `root` / `yds-Modal` |
| SectionTabs | `TabContainer` | `root` |
| ChoiceContainer | `Container` | `root` |
| Combobox | `Wrapper` (with `isDisabled`), `isOpen` on `Menu` | `root` (with `isDisabled`), `isOpen` on `root` |
| ToastNotification | `Motion` | `root` |
| PageIndicator | `Indicator` | `root` |
| NavigationTabList | `Navigation` | `root` |
| ButtonGroup | `isSelected`, `isDisabled`, `size_*` on Button | `GroupButton_isSelected`, `GroupButton_isDisabled`, `GroupButton_size_*` |
| DropdownMenuGroup | `variant_*`, `size_*`, `isDisabled` on Button | `GroupButton_variant_*`, `GroupButton_size_*`, `GroupButton_isDisabled` |
| Combobox (menu items) | `isSelected`, `isHighlighted`, `isDisabled` on `MenuItem` | `MenuItem_isSelected`, `MenuItem_isHighlighted`, `MenuItem_isDisabled` |
| Combobox (custom items) | `isSelected`, `isHighlighted` | `CustomMenuItem_isSelected`, `CustomMenuItem_isHighlighted` |
| Modal | `contentScroll_body`, `contentScroll_content` | removed — use `scrollBehavior_body .Content` |
| BaseCheckbox, BaseRadio, Message | `isError` | `error` (matches the `error` prop) |
| Button | `hasIconBefore`, `hasIconAfter` | removed — the rules match sibling order instead |
| Button | `IconWrapper_size_*`, `IconWrapper_loading`, `TextWrapper_loading` | removed — `size_*` and `loading` on `root` + cascade |
| Accordion | `Title_iconAlign_*`, `Content_padding_*` | `iconAlign_*`, `padding_*` on `root` + cascade |
| Combobox | `Menu_size_*`, `MenuItem_size_*` | `menuSize_*` on `root`, `MenuItem_menuSize_*` |
| Dialog | `showTopBorder`, `showBottomBorder` on `Content` | on `root`; `FooterContainer`/`Footer` → `Footer`/`Actions` |
| Dialog | `Title_hasIllustrativeIcon`, `Footer_isResponsive` | `hasIllustrativeIcon` on `root` + cascade |
| BottomSheet | `SheetContent`, `DragHandle` | `Content`, `Handle` |
| BottomSheet | `Title_dragToClose`, `Title_noDragToClose` | `dragToClose` on `root` |
| BaseNotification | `Title_inline`, `Title_multiline`, `Text_inline`, `Text_multiline`, `Title_inlineWithChildren`, `CloseContainer` | `isMultiline` on `root` + cascade; `CloseWrapper` |
| ChoiceContainer | `IconContainer`, `size_sm` | `IconWrapper`, `containerSize_sm` |
| DropdownMenuGroup | `ButtonIcon` | `IconWrapper` |
| Link | `IconBefore` | `IconWrapper` (it was used for both positions) |
| MenuItem | `highlight` | `iconHighlight` (matches the prop) |
| NavigationTab | `TabItem`, `TabListItem`, `TabContent`, `BadgeContainer` | `root`, `Item`, `Content`, `Badge` |
| NavigationTab | `TabItem_selected`, `TabItem_removePadding`, `BadgeContainer_removePadding` | `selected`, `removePadding` on `root` |
| NavigationTabList | `TabList`, `TabList_align_center` | `List`, `align_center` on `root` (own module) |
| ProgressBar | `Track_status_*`, `Fill_status_*`, `Icon_status_*`, `Description_status_*`, `Fill_determinate`, `Fill_indeterminate` | `status_*` and `variant_*` on `root` + cascade |
| RadioGroup | `HorizontalRadioWrapper`, `HorizontalRadioLabelsWrapper`, `NumericScaleLabel`, `NumericScaleStartLabel`, `NumericScaleEndLabel` | `RadioWrapper`, `LabelsWrapper`, `ScaleLabel`, `StartLabel`, `EndLabel` |
| SectionTabs | `TabList`, `TabButton`, `TabButton_active` | `List`, `Tab`, `Tab_isActive` |
| Select | `isDisabled` on `Wrapper` | on `root` (the `<select>`) |
| Spinner | `background_variant_*`, `Wheel_size_*`, `Wheel_variant_*` | `Background`/`Arc` elements; `size_*`/`variant_*` on `root` |
| TagFilter | `Button_size_*` | removed — `size_*` on `root` + cascade |
| TagLink | `lineClamp`, `lineClampSingle`, `unlimitedLines` | `numberOfLines_single`, `numberOfLines_multiple`, `numberOfLines_unlimited` |
| Textarea | `CharacterCounter` | `Counter` |
| TextInput | `Wrapper_isDisabled`, `Wrapper_error`, `Wrapper_success`, `Wrapper_hasUnit`, `IconWrapper_isDisabled`, `Button_isDisabled`, `SpinnerWrapper_isDisabled`, `Unit_isDisabled` | `isDisabled`, `error`, `success`, `hasUnit` on `root`; chrome uses `:has()` |
| ToastNotification | `Notification`, `ProgressContainer`, `Notification_hasTimer`, `Notification_hasAction` | `Content`, `ProgressWrapper`, `showTimer`, `hideCloseButton` on `root` (inverted: set when there is no close button) |
| CheckableLabel | `visuallyHidden` | `yds-VisuallyHidden` (internal module). `.yds-visually-hidden` remains in `utilities.css` for app markup |

## See also

- [Get started with yds-components-react 3.0](./get-started-with-v3.md)
- [Breaking changes in React package 3.0](./breaking-changes-in-v3.md)
- [Using styled-components with YDS 3.0](./styled-components-to-css.md)

# Get started with yds-components-react 3.0

Install the packages, put design tokens on `:root`, and render a component. `styled-components` is not required. This page is for applications that consume `@yleisradio/yds-components-react`. Component APIs, tokens, and usage examples elsewhere on this site do not require installing the package.

Coming from 2.x? [Breaking changes in React package 3.0](./breaking-changes-in-v3.md) is the upgrade guide. If the app **keeps** styled-components as its own styling library, also see [Using styled-components with YDS 3.0](./styled-components-to-css.md).

## 1. Install

```bash
npm install @yleisradio/yds-core @yleisradio/yds-icons-react @yleisradio/yds-components-react
```

## 2. Load Yle Next

Components expect the **Yle Next** variable font. Simplest way to get it is to add the design-system CDN stylesheet in `<head>`:

```html
<link rel="stylesheet" href="https://design-system.cdn.yle.fi/fonts/fonts.css" />
```

That file is the supported entry point for every font family the design system ships. It can grow as more styles are added.

To write your own `@font-face` rules, the variable files are:

- [`YleNextVar.woff2`](https://design-system.cdn.yle.fi/fonts/yle-next/1.0.0/YleNextVar.woff2)
- [`YleNextVar-Italic.woff2`](https://design-system.cdn.yle.fi/fonts/yle-next/1.0.0/YleNextVar-Italic.woff2)

To host the fonts locally in the app instead of loading it from the CDN, install `@yleisradio/yds-fonts` and import the necessary files from the package:

```bash
npm install @yleisradio/yds-fonts
```

## 3. Put tokens on `:root`

Components read `var(--yds-color-*)`, spacing, radius, typography and shadow variables. Those must exist on a DOM ancestor — for the whole app, import them once as global CSS.

```css
/* yds-tokens.css */
@import '@yleisradio/yds-core/tokens/build/css/_border-radius.css';
@import '@yleisradio/yds-core/tokens/build/css/_spacing.css';
@import '@yleisradio/yds-core/tokens/build/css/_typography.css';
@import '@yleisradio/yds-core/tokens/build/css/_shadow-default.css';
@import '@yleisradio/yds-core/tokens/build/css/_shadow-default-prefers-dark.css';
@import '@yleisradio/yds-core/tokens/build/css/_theme-default.css';
@import '@yleisradio/yds-core/tokens/build/css/_theme-default-prefers-dark.css';
```

```ts
import './yds-tokens.css';
```

Import this file at the **top of the app entry**, before any component that pulls in YDS CSS. Missing a token file shows up as unstyled components, not a JavaScript error.

Alternatively, [YdsThemeProvider](../../components/YdsThemeProvider/YdsThemeProvider.md) can wrap a subtree (or, as a migration step, `:root`) instead of importing these files.

| App theme | Token files |
| --- | --- |
| Light, following the OS | The list above |
| Always light | Omit the two `*-prefers-dark` files |
| Always dark | `_shadow-default-dark.css` and `_theme-default-dark.css` instead of the light default + prefers-dark pair |
| Switch between light and dark | `_theme-light.css` / `_theme-dark.css` and `_shadow-light.css` / `_shadow-dark.css` — use `.yds-theme-light` and `.yds-theme-dark` on the application root |

### Wrappers: development vs production

If a parent page already loads the same files, do not import them again.

Yle apps often sit inside a **wrapper**. Who owns `:root` then depends on the environment:

| Environment | Who sets tokens |
| --- | --- |
| Production | The wrapper usually already delivers the page theme. Skip the `:root` imports so the same variables are not defined twice. |
| Development | There is often no wrapper. Import the token CSS yourself (the list above) so components are not unstyled. |

If the app needs **its own** color or shadow tokens while the wrapper still owns the rest of the page, do not write them to `:root` — that would override the host. Inject a `*CssFragment` from `@yleisradio/yds-core` and scope it to the **application ID** the wrapper puts on your root:

```ts
import { darkThemeCssFragment, darkShadowCssFragment } from '@yleisradio/yds-core';

const applicationId = 'your-application-id';

const style = document.createElement('style');
style.textContent = `#${applicationId} {
  ${darkThemeCssFragment}
  ${darkShadowCssFragment}
}`;
document.head.appendChild(style);
```

Preset fragments: `lightThemeCssFragment`, `darkThemeCssFragment`, `lightShadowCssFragment`, `darkShadowCssFragment`. For a generated `Theme`, use `themeToCssFragment`. `themeToCss` from `@yleisradio/yds-components-react` wraps the same fragments in a selector if you prefer not to concatenate them by hand.

### What about YdsThemeProvider?

You no longer *need* `YdsThemeProvider` around the app if the theme is served by the methods above. It *can* still be used as an alternative way to set up a theme wrapper. Details: [YdsThemeProvider](../../components/YdsThemeProvider/YdsThemeProvider.md).

## 4. Let the bundler compile CSS Modules

Components import their own `*.module.css` files. Process those as CSS Modules (including under `node_modules`). Process every other `.css` file from this package and from `@yleisradio/yds-core` as **global** CSS — token files must not be hashed.

Keep the default key convention. The compiled JavaScript uses a default import (`import styles from './Button.module.css'`) and reads keys such as `styles.variant_primary`, so do not enable camelCase or other `localsConvention` transforms.

### Vite

Vite compiles CSS Modules from `node_modules` without configuration. Add [`vite-css-modules`](https://github.com/privatenumber/vite-css-modules) as well: YDS shares styles such as typography through `composes`, and plain Vite inlines each composed rule into every module that uses it (about 44% more CSS). The plugin puts CSS Modules into Vite's module graph, so each rule is emitted once. YDS Storybook uses the same setup.

```bash
npm install --save-dev vite-css-modules
```

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { patchCssModules } from 'vite-css-modules';

export default defineConfig({
  plugins: [patchCssModules(), react()],
  // Only if component styles go missing after dependency pre-bundling:
  optimizeDeps: {
    exclude: ['@yleisradio/yds-components-react'],
  },
});
```

### Webpack 5

`css-loader` must run on this package's CSS. The usual failure is `exclude: /node_modules/` on the CSS rule, which drops both the component modules and the token files. On `css-loader` 7+, set `namedExport: false` and `exportLocalsConvention: 'as-is'`.

```js
// webpack.config.js
const path = require('path');

const ydsCss = /node_modules\/@yleisradio\/yds-(components-react|core)/;

module.exports = {
  module: {
    rules: [
      {
        test: /\.module\.css$/,
        include: [path.resolve(__dirname, 'src'), ydsCss],
        use: [
          'style-loader', // or MiniCssExtractPlugin.loader
          {
            loader: 'css-loader',
            options: {
              modules: {
                namedExport: false,
                exportLocalsConvention: 'as-is',
              },
            },
          },
        ],
      },
      {
        // Token files and other global CSS.
        test: /\.css$/,
        exclude: /\.module\.css$/,
        include: [path.resolve(__dirname, 'src'), ydsCss],
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
};
```

If you already have equivalent rules for your own `src` tree, extend their `include` (or stop excluding `node_modules`) so both `@yleisradio` packages match.

### Next.js

```js
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@yleisradio/yds-components-react'],
};

module.exports = nextConfig;
```

Also list every dependency that renders YDS 3 components, such as a shared component library. Next.js cannot resolve CSS Modules from untranspiled `node_modules` code. Import token CSS and `utilities.css` from `pages/_app` or the root `layout`, not from a CSS Module.

### Test runners

Components import stylesheets, so the test runner has to handle CSS.

Jest:

```js
// jest.config.js
moduleNameMapper: {
  '\\.css$': 'identity-obj-proxy',
},
```

Vitest — Node's ESM loader cannot process CSS Modules, so inline the YDS packages and skip CSS:

```ts
// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    css: false,
    server: {
      deps: {
        inline: [/@yleisradio\/yds-/],
      },
    },
  },
});
```

### Cascade layer and utilities

Component styles live in `@layer yds`. An unlayered global reset (`* { margin: 0; padding: 0 }`) wins over that layer and strips spacing. [Breaking changes — Global resets](./breaking-changes-in-v3.md#global-resets) has the layer recipe.

## 5. Render a component

```tsx
import { Button } from '@yleisradio/yds-components-react';

<Button variant="primary" text="Click me" />;
```

If the button has no color or padding, the bundler is not compiling CSS Modules from `node_modules`, or the token CSS is not on `:root`. Check DevTools: `html` should list `--yds-color-*` variables, and the button's padding should come from a rule labelled `@layer yds`.

## 6. Use tokens in your own styles

```css
.card {
  background: var(--yds-color-background-variant);
  color: var(--yds-color-text-default);
  padding: var(--yds-spacing-16);
  border-radius: var(--yds-border-radius-medium);
  box-shadow: var(--yds-shadow-md);
}
```

In JavaScript, `defaultTheme` from `@yleisradio/yds-core` is the same values, typed, with a light fallback:

```ts
import { defaultTheme } from '@yleisradio/yds-core';

defaultTheme.BACKGROUND; // 'var(--yds-color-background, #ffffff)'
```

Token catalogue: [Design tokens](../../design-tokens/index.md).

YDS components include their own focus ring. For your own components, import the `utilities.css` from the app entry – it contains shared styles for global use.

```ts
import '@yleisradio/yds-components-react/utilities.css';
```

Put `yds-use-focus` on `body` (or any wrapper) to draw the ring on `:focus-visible` inside that subtree. `yds-focus` does the same for one element.

## Without React

React is the primary distribution. Two other ways reuse the same `.module.css` source. Pick **one** for a given page — mixing them with each other or with the React components duplicates every rule.

### CSS Modules (Vue, Svelte, webpack, Vite, …)

Import individual stylesheets. The bundler hashes class names locally — same contract as React (`styles.root`, `styles.variant_primary`).

```ts
import styles from '@yleisradio/yds-components-react/Button.module.css';
```

Deep paths for internals and composite markup:

```ts
import styles from '@yleisradio/yds-components-react/styles/components/Button/Button.module.css';
import labelStyles from '@yleisradio/yds-components-react/styles/internal/components/CheckableLabel/CheckableLabel.module.css';
```

Requirements:

- Design tokens from `@yleisradio/yds-core` on `:root` (see step 3 above).
- Process `*.module.css` as CSS Modules from `node_modules`; keep token CSS global.
- Markup and class keys are your responsibility — copy structure from the React component (e.g. Button: `root` + `size_*` + `variant_*` on the host, `TextWrapper` / `IconWrapper` on children).
- Class names and component markup are not part of the versioned package API and can change in a minor or patch release. Pin the package version and add guardrails on the application side.
- Composite components may need **multiple** modules (Checkbox = `Checkbox.module.css` plus `CheckableLabel.module.css` under `styles/internal/…`).
- Use the imported `styles` object rather than reconstructing class strings. `composes` (typography, shared slots) is resolved into the exported map, so `styles.root` may already be several class names.
- Do not import `all.css` together with CSS Modules.

Naming: [CSS class naming conventions](./css-conventions.md).

### Matching `all.css` class names from CSS Modules

The default setup hashes locals. If you want the same stable names as `all.css` (`yds-Button`, `yds-Button__variant_primary`) but only the components you import, keep using CSS Modules and point the bundler’s `generateScopedName` at YDS files. Do **not** also import `all.css`.

This is the right path when you have a bundler and want readable class names in HTML. Unlike `all.css`, `composes` is not merged into one class here: it lands on the element as extra class names through the `styles` export.

The helper ships with the package, as ESM and CJS. **Import it — do not retype it.** A few modules publish under a different name than their file (`BaseRadio.module.css` → `yds-Radio`), and a hand-written `yds-${basename}` gets those wrong. See [Module name vs component name](./css-conventions.md#module-name-vs-component-name).

**Vite** — `generateScopedName` is global. Pass the helper; Vite’s default hash pattern (`'[name]__[local]__[hash:base64:5]'`) is a string interpolator and cannot be mixed with a function:

```ts
import { defineConfig } from 'vite';
import { generateScopedName } from '@yleisradio/yds-components-react/scoped-name';

export default defineConfig({
  css: {
    modules: { generateScopedName },
  },
});
```

That replaces hashing for **every** CSS Module in the app. Keep Vite’s default if your own modules should stay hashed (the React path). There is no per-package switch.

**Webpack 5** — a dedicated rule is cleaner than branching inside `getLocalIdent`. Keep the hashed rule for your `src` tree, and add:

```js
const { generateScopedName } = require('@yleisradio/yds-components-react/scoped-name');

{
  test: /\.module\.css$/,
  include: /node_modules\/@yleisradio\/yds-components-react/,
  use: [
    'style-loader',
    {
      loader: 'css-loader',
      options: {
        modules: {
          namedExport: false,
          exportLocalsConvention: 'as-is',
          getLocalIdent(context, _localIdentName, localName) {
            return generateScopedName(localName, context.resourcePath);
          },
        },
      },
    },
  ],
}
```

Exclude this package from the hashed `*.module.css` rule (`exclude: /@yleisradio\/yds-components-react/`) so the two do not both match.

React apps that need microfrontend isolation should **keep the default hash**. Readable names share the global `yds-*` namespace, so two YDS versions on one page will clash.

### Bundled `all.css` (CDN, HTML, no bundler)

One global stylesheet with every component's styles under readable class names, for CDN delivery or prototypes.

```js
import '@yleisradio/yds-components-react/styles/all.css';
```

Load the font and the design tokens first (steps 2 and 3). `all.css` does not contain tokens.

Write the classes for each prop and element you render, copying the structure from the React component:

```html
<button class="yds-Button yds-Button__size_md yds-Button__variant_primary">
  <span class="yds-Button__TextWrapper">Click me</span>
</button>
```

Shared styles are already part of the component class. `yds-Accordion__Title_size_md` carries its typography, so there is no separate typography class to add.

What else is in the file:

- Every rule is in a single `@layer yds`, same as the React components. See [Breaking changes — Global resets](./breaking-changes-in-v3.md#global-resets) if the page has a reset.
- The contents of `utilities.css` (`yds-use-focus`, `yds-focus`, `yds-focus-ring`, `yds-visually-hidden`). Do not import `utilities.css` separately.
- The body scroll lock used by Modal and BottomSheet.

`all.css` is not part of the versioned package API. Class names and markup can change in a minor or patch release, so pin the package version and check the [class renames](./css-conventions.md#allcss-class-renames-310-convention-fix) when you upgrade.

There is no per-component stylesheet. If the full bundle is too much, use CSS Modules with the `generateScopedName` config above. Do not import `all.css` together with CSS Modules or React components — that duplicates styles.

Naming: [CSS class naming conventions](./css-conventions.md).

## Related

- [Breaking changes in React package 3.0](./breaking-changes-in-v3.md) — What 2.x apps must change.
- [Using styled-components with YDS 3.0](./styled-components-to-css.md) — If the app keeps styled-components.
- [YdsThemeProvider](../../components/YdsThemeProvider/YdsThemeProvider.md) — Alternative to token CSS for a subtree or React-driven theme.

# Using styled-components with YDS 3.0

This guide is for apps that **keep styled-components** as their own styling library and need YDS design tokens to work with it after `@yleisradio/yds-components-react` 3.0.

If you are dropping styled-components, or never used it outside YDS, stop here: [Breaking changes in React package 3.0](./breaking-changes-in-v3.md) is enough.

In 2.x, `YdsThemeProvider` passed a theme object through React context. Styled components read colors from `props.theme.yds`:

```tsx
const Card = styled.div`
  background: ${(props) => props.theme.yds.BACKGROUND_VARIANT};
  color: ${(props) => props.theme.yds.TEXT_DEFAULT};
`;
```

In 3.0 that context is gone. Colors are CSS custom properties, inherited through the DOM. The smallest change that gets you there is to import the same tokens directly, since `defaultTheme` from `@yleisradio/yds-core` already holds custom property references:

```tsx
import { defaultTheme } from '@yleisradio/yds-core';

const Card = styled.div`
  background: ${defaultTheme.BACKGROUND_VARIANT};
  color: ${defaultTheme.TEXT_DEFAULT};
`;
```

> **The important part**
> **Most of this work lands on 2.x, before you upgrade.** `defaultTheme` and the token CSS files already ship in `@yleisradio/yds-core` 2.x, so you can convert every `props.theme.yds` read while still running the old package. Done in that order, the actual 3.0 upgrade is a version bump plus a bundler setting.

YDS no longer provides a styled-components `ThemeProvider`. Keep your own `<ThemeProvider>` if the app needs `props.theme` for non-YDS keys. Interpolate `defaultTheme` (or raw `var(--yds-color-*)`) for YDS colors.

## What does not change

Worth establishing up front, because it removes a lot of perceived scope:

- **JS token imports from `@yleisradio/yds-core` keep working.** `spacing`, `radius`, `typography`, `border`, `transition`, `color` and the theme objects are still plain JavaScript exports. Interpolating `spacing.SPACING_16` into a styled component is as valid in 3.0 as it was in 2.x. This is also what makes the color migration cheap — see [`defaultTheme`](#default-theme) below.
- **Component props are unaffected.** This migration is about tokens and theming, not component APIs.
- **`ydsThemeUnit` is still exported** from `@yleisradio/yds-components-react` if you use it for unit conversion.

What breaks is the theme context and nothing else: `props.theme.yds.*`, `props.theme.ydsThemeName`, `props.theme.ydsThemeProps`, and the `unit` / `baseUnit` props.

## Two ways to read a color

There are two targets you can convert `props.theme.yds.*` to. Both end up as the same CSS custom property at runtime.

### `defaultTheme` — the short path \{#default-theme\}

`@yleisradio/yds-core` exports `defaultTheme`, a typed `Theme` object whose values **are** CSS custom property references with a built-in fallback:

```ts
import { defaultTheme } from '@yleisradio/yds-core';

defaultTheme.BACKGROUND; // 'var(--yds-color-background, #ffffff)'
```

That makes the migration a rename. The key names are identical to 2.x, so `props.theme.yds.` becomes `defaultTheme.` and nothing else changes:

```
props.theme.yds.TEXT_DEFAULT   →   defaultTheme.TEXT_DEFAULT
props.theme.yds.ACTION_PRIMARY →   defaultTheme.ACTION_PRIMARY
```

Three properties make this the easiest place to start:

- **It is typed.** `Theme` declares all 106 tokens, so a mistyped name is a compile error. Hand-written `var(--yds-color-…)` strings are unchecked, and an undefined custom property fails silently.
- **It carries fallbacks.** Every value is `var(--yds-color-x, <light value>)`, so converted code renders correctly even before the token CSS is on `:root`. You can start here without doing Phase 1 first.
- **It still follows the live theme.** These are variable references, not a snapshot of light values — the colors change with the document theme exactly as they did through context.

### Raw `var()` — the destination

Writing the custom property directly drops the JavaScript indirection entirely. The rule is **`CONSTANT_CASE` to kebab-case, prefixed with `--yds-color-`**, with no exceptions or renames across all 106 tokens:

| 2.x | Raw CSS |
|---|---|
| `theme.yds.BACKGROUND` | `var(--yds-color-background)` |
| `theme.yds.BACKGROUND_VARIANT` | `var(--yds-color-background-variant)` |
| `theme.yds.TEXT_DEFAULT` | `var(--yds-color-text-default)` |
| `theme.yds.TEXT_MEDIUM_EMPHASIS` | `var(--yds-color-text-medium-emphasis)` |
| `theme.yds.ACTION_PRIMARY` | `var(--yds-color-action-primary)` |
| `theme.yds.BORDER_SEPARATOR` | `var(--yds-color-border-separator)` |
| `theme.yds.FEEDBACK_ERROR` | `var(--yds-color-feedback-error)` |

This is where you want to end up if you plan to leave styled-components later, since the declarations become portable CSS with no imports.

> **Which to pick**
> Start with `defaultTheme`. It is a mechanical rename with compiler support, and it converts a large codebase in one pass. Move to raw `var()` opportunistically — or as part of Phase 6, if you leave styled-components at all. There is no need to choose one for the whole codebase.

Note that `theme.yds` contained **colors only** — including shadow *colors* (`SHADOW_S`, `SHADOW_M`, `SHADOW_L`), but not full `box-shadow` values. Spacing, radius and typography came from separate `@yleisradio/yds-core` imports and are unaffected.

## Phase 0 — Inventory

Measure the work before starting. These searches cover everything that breaks:

```bash
# color reads — usually the bulk of the work
rg 'theme\.yds\.' --stats

# Theme-name branching and unit conversion
rg 'ydsThemeName|ydsThemeProps' --stats

# Unit props
rg 'YdsThemeProvider' -A 3 | rg 'unit|baseUnit'

# Where providers live, and how many
rg '<YdsThemeProvider' -l

# The type augmentation that makes all of the above compile
rg -l "declare module 'styled-components'"
```

The first number is the one that matters. It is a mechanical find-and-replace, so a large count means a long diff, not a hard problem.

The last search is the one to read first, because it determines whether the compiler helps you or hides the work — see [the augmentation step](#augmentation) below.

## Phase 1 — Put tokens on `:root` (on 2.x)

Import the token CSS once from your app entry or global stylesheet. This is additive: nothing reads the variables yet.

```css
/* yds-tokens.css */
@import '@yleisradio/yds-core/tokens/build/css/_border-radius.css';
@import '@yleisradio/yds-core/tokens/build/css/_spacing.css';
@import '@yleisradio/yds-core/tokens/build/css/_typography.css';
@import '@yleisradio/yds-core/tokens/build/css/_shadow-default.css';
@import '@yleisradio/yds-core/tokens/build/css/_shadow-default-prefers-dark.css';
@import '@yleisradio/yds-core/tokens/build/css/_theme-default.css';
@import '@yleisradio/yds-core/tokens/build/css/_theme-default-prefers-dark.css';
```

Pick the theme files that match what your app does today. If it is always light, omit the two `*-prefers-dark` files. If it is always dark, use `_theme-default-dark.css` and `_shadow-default-dark.css` instead. If a parent page already loads these files, do not import them again.

This phase and the next are independent — `defaultTheme` values fall back to their light value when a variable is missing, so Phase 2 does not wait on this. Do them in whichever order suits the team, but finish this one before the app needs dark mode.

**Verify:** in DevTools, `html` should list `--yds-color-*` variables. Nothing should look different yet.

## Phase 2 — Convert color reads (on 2.x)

### Delete the theme augmentation first \{#augmentation\}

`props.theme.yds` only type-checks because something augments styled-components' `DefaultTheme`:

```ts
// styled.d.ts
declare module 'styled-components' {
  export interface DefaultTheme {
    ydsThemeName: ThemeName;
    yds: Theme;
  }
}
```

2.x shipped this file inside `@yleisradio/yds-components-react`, and many applications keep their own copy as well — usually an extended one, since `ydsThemeProps` was never in the packaged version.

Which of the two you have decides how the whole migration feels. If you relied on the packaged augmentation, 3.0 removes it for you and every unconverted read becomes a compile error the moment you upgrade. If you have your own copy, upgrading changes nothing for the compiler: the reads keep type-checking and fail at runtime instead, where `props.theme` no longer carries `yds` and the interpolation throws.

Delete the YDS fields from your own augmentation **before** converting anything. It costs one line and turns every remaining read into a type error, which is a far better worklist than a ripgrep count:

```diff
 declare module 'styled-components' {
   export interface DefaultTheme {
-    ydsThemeName: ThemeName;
-    yds: Theme;
-    ydsThemeProps: { unit: string; baseUnit: number };
     // your own theme keys stay
   }
 }
```

If the interface is left empty afterwards, delete the file — but only if your application has no theme of its own. See [Phase 4](#phase-4) for why that distinction matters.

### Convert the reads

Swap the theme object for `defaultTheme`, file by file. The token names do not change, so this is a find-and-replace of `props.theme.yds.` with `defaultTheme.` plus one import per file:

```tsx
import { defaultTheme } from '@yleisradio/yds-core';

// Before
const Card = styled.div`
  background: ${(props) => props.theme.yds.BACKGROUND_VARIANT};
  border: 1px solid ${(props) => props.theme.yds.BORDER_SEPARATOR};
`;

// After
const Card = styled.div`
  background: ${defaultTheme.BACKGROUND_VARIANT};
  border: 1px solid ${defaultTheme.BORDER_SEPARATOR};
`;
```

The interpolations no longer depend on props, so they resolve once at module level instead of on every render.

Because `defaultTheme` values carry fallbacks, converted files render correctly whether or not Phase 1 has landed — the two phases are independent and can run in either order or in parallel. TypeScript checks every token name against the `Theme` type, so a rename that slipped through the find-and-replace fails the build rather than silently producing a missing color.

<details>
<summary>Going straight to raw `var()` instead</summary>

If a file is already close to plain CSS, or you know it is leaving styled-components soon, write the custom property directly and drop the import:

```tsx
const Card = styled.div`
  background: var(--yds-color-background-variant);
  border: 1px solid var(--yds-color-border-separator);
`;
```

This has no fallback, so it does depend on Phase 1 being in place. It also has no compile-time checking — verify these visually.
</details>

<details>
<summary>Converting shadows at the same time</summary>

`theme.yds` carried shadow *colors* (`SHADOW_S`, `SHADOW_M`, `SHADOW_L`), not complete `box-shadow` values. Those you assembled yourself, or imported per theme and branched on:

```tsx
import { lightShadow, darkShadow } from '@yleisradio/yds-core';

const Card = styled.div`
  box-shadow: ${(props) => (props.theme.ydsThemeName === 'dark' ? darkShadow.SHADOW_MD : lightShadow.SHADOW_MD)};
`;
```

Shadows follow the same two paths as colors. `defaultShadow` mirrors `defaultTheme` — typed keys whose values are variable references with a light fallback — so the branch collapses to a single import:

```tsx
import { defaultShadow } from '@yleisradio/yds-core';

defaultShadow.SHADOW_MD; // 'var(--yds-shadow-md, 0 0 16px 0 rgba(0, 0, 0, 0.15))'

const Card = styled.div`
  box-shadow: ${defaultShadow.SHADOW_MD};
`;
```

Or write the variable directly, once Phase 1 has put the shadow CSS on `:root`:

```tsx
const Card = styled.div`
  box-shadow: var(--yds-shadow-md);
`;
```

> **Warning**
> `lightShadow` and `darkShadow` **pin** a theme, exactly like `lightTheme` and `darkTheme`. Reach for `defaultShadow` unless you specifically want a shadow that ignores the active theme.
</details>

**Verify:** the app looks identical. With `defaultTheme` the compiler catches wrong names; with raw `var()` watch for missing colors, since an undefined custom property resolves to nothing rather than erroring.

## Phase 3 — Replace the remaining context reads (on 2.x)

Besides colors, the 2.x theme carried two things: the theme name, and the unit settings behind `ydsThemeUnit`.

### Theme-name branching

Code that branched on `props.theme.ydsThemeName` usually exists because 2.x needed the theme name to pick a value. Most of those branches collapse, because the token already differs per theme:

```tsx
// Before — two tokens selected in JS
color: ${(props) => (props.theme.ydsThemeName === 'dark' ? props.theme.yds.TEXT_LIGHT : props.theme.yds.TEXT_DARK)};

// After — one token that already follows the theme
color: var(--yds-color-text-default);
```

For a branch that is genuinely about theme rather than about a token, move the decision into CSS:

```css
/* Follows the OS */
@media (prefers-color-scheme: dark) { … }

/* Follows a theme class on an ancestor */
.yds-theme-dark & { … }
```

If you need the active theme in JavaScript after upgrading, `useThemeContext()` returns the nearest provider's scope. It returns `null` outside a provider, which is the normal case once document tokens come from CSS.

### Unit conversion

2.x put the provider's `unit` and `baseUnit` on the theme as `ydsThemeProps`, so `ydsThemeUnit` could convert every size to whatever the app was configured for:

```tsx
font-size: ${(props) =>
  ydsThemeUnit(
    typography.DEFAULT_XL_FONT_SIZE,
    props.theme.ydsThemeProps.unit,
    props.theme.ydsThemeProps.baseUnit
  )};
```

`ydsThemeProps` is gone in 3.0. `ydsThemeUnit` itself is still exported, so the smallest fix is to pass the values directly instead of reading them from the theme:

```tsx
font-size: ${ydsThemeUnit(typography.DEFAULT_XL_FONT_SIZE, 'rem', 16)};
```

Most call sites can drop the helper altogether. A 2.x provider defaulted to `rem` at a 16px base, and 3.0 components emit exactly that, so unless yours set `unit` or `baseUnit` explicitly the conversion produces the value it was given — interpolate the `typographyRem` token or the CSS variable and delete the call.

> **Warning**
> Do not simply drop the arguments. `ydsThemeUnit` defaults to `'px'`, not to the `'rem'` the provider defaulted to, so `ydsThemeUnit(value)` silently changes units. Pass `'rem'` explicitly or remove the call.

If the app did configure `unit="px"` or a custom `baseUnit`, that setting disappears along with the props in Phase 4. Handle it once in PostCSS rather than at every call site.

## Phase 4 — Upgrade to 3.0 \{#phase-4\}

Now the package upgrade itself, which should be small:

1. **Bump** `@yleisradio/yds-components-react` to 3.0 and `@yleisradio/yds-core` to the matching version.
2. **Configure CSS Modules from `node_modules`.** Vite compiles them as-is, but add [`vite-css-modules`](https://github.com/privatenumber/vite-css-modules) (`patchCssModules()`) so CSS Modules join Vite's module graph and shared `composes` rules are emitted once instead of duplicated; Next.js needs `transpilePackages` for YDS and for every dependency that uses YDS 3 components, because it cannot resolve CSS Modules from untranspiled `node_modules` code at runtime; webpack 5 must not `exclude: /node_modules/` on the CSS rule. Configs: [Get started — Let the bundler compile CSS Modules](./get-started-with-v3.md#4-let-the-bundler-compile-css-modules).
3. **Map CSS in your test runner.** Components now import stylesheets. Jest needs a CSS proxy; Vitest needs the packages inlined and `css: false`. Configs: [Get started — Test runners](./get-started-with-v3.md#test-runners).
4. **Remove `unit` and `baseUnit`** from every `YdsThemeProvider`. Component CSS now uses `rem` on a `1rem = 16px` baseline. If your app relied on `unit="px"` or a custom `baseUnit`, add `postcss-rem-to-pixel` or `postcss-pxtorem` to your PostCSS chain instead.
5. **Put your global CSS reset in a cascade layer.** Component styles now live in `@layer yds`. Recipe: [Breaking changes — Global resets](./breaking-changes-in-v3.md#global-resets). If the reset is a `createGlobalStyle`, see [below](#resets).
6. **Give styled-components a theme of its own, if it does not have one.** 2.x rendered styled-components' `ThemeProvider` on your behalf and replaced the theme with `{ ydsThemeName, yds, ydsThemeProps }`. 3.0 renders no styled-components provider at all, so if `YdsThemeProvider` was the only one in the tree, `props.theme` is now `{}` and every `props.theme.*` read breaks — not just the YDS ones. Render your own `<ThemeProvider>` with whatever the app needs. Conversely, if your provider sat *outside* `YdsThemeProvider`, 2.x was shadowing it inside that subtree and those keys become visible again.
7. **Keep your root provider for now** by adding `scope=":root"`, so this step changes nothing about theming:

```tsx
<YdsThemeProvider theme="light" scope=":root">
  <App />
</YdsThemeProvider>
```

Note that `theme` now defaults to `'default'` (follows `prefers-color-scheme`) rather than `'light'`. If your app should stay light, pass `theme="light"` explicitly.

**Verify:** run the app. Anything that looks unstyled is almost always the bundler not processing CSS Modules from `node_modules`, not a token problem.

## Phase 5 — Retire the root provider

Phase 1 already put tokens on `:root` via CSS, so the `scope=":root"` provider from Phase 4 is now doing the same job twice. Delete it:

```diff
-<YdsThemeProvider theme="light" scope=":root">
-  <App />
-</YdsThemeProvider>
+<App />
```

Keep `YdsThemeProvider` where it earns its place — a section that needs a different theme than the page, or a theme that changes in React:

```tsx
<YdsThemeProvider theme="dark">
  <DarkSidebar />
</YdsThemeProvider>
```

If the app switches theme at runtime, keep one provider with `scope=":root"` and a stateful `theme` prop, or toggle a class on `body` and load the class-scoped token files. See [YdsThemeProvider](../../components/YdsThemeProvider/YdsThemeProvider.md) for the full API.

**Verify:** exactly one source defines document tokens. Two `:root` rules from different sources is the setup that produces "the theme is right until something re-renders".

## Global CSS resets \{#resets\}

The layer recipe lives in [Breaking changes — Global resets](./breaking-changes-in-v3.md#global-resets). This section is only the styled-components part.

A `createGlobalStyle` reset is unlayered, so it beats `@layer yds` and strips component spacing:

```tsx
// Unlayered, so every declaration here beats @layer yds
export const GlobalStyle = createGlobalStyle`
  * {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
  }
`;
```

Leave `box-sizing: border-box` on `*`. Move `margin: 0` and `padding: 0` into a `@layer reset` in a **plain CSS file**, not in `createGlobalStyle`. styled-components injects its stylesheet when the component first renders, so a runtime-injected `@layer reset, yds, app;` is a coin flip against the bundler's CSS. Only styled-components 6 (stylis 4) reliably preserves `@layer` blocks inside `createGlobalStyle` anyway.

If you keep the reset itself in `createGlobalStyle`, wrap it in `@layer reset { … }` and declare the order in CSS that loads first.

If the reset cannot be layered at all, unwrap `@layer yds` in the app build.

## Custom themes

Applications passing a generated theme object to the provider keep doing exactly that — `customTheme()` from `@yleisradio/yds-theme-custom` still returns a `Theme`, and `YdsThemeProvider` still accepts it:

```tsx
const theme = customTheme(color.GRAY_95, color.NEWS_VIOLET_30);

<YdsThemeProvider theme={theme}>
  <Widget />
</YdsThemeProvider>;
```

The difference is reach. In 2.x the palette flowed through React context to every descendant. In 3.0 it applies to the provider's subtree in the DOM. For a self-contained widget that is the same thing, and it is safer — the palette can no longer leak into a host page.

To emit a custom palette as static CSS instead, use `themeToCss(selector, theme)` from `@yleisradio/yds-components-react`.

## Common problems

| Symptom | Cause |
|---|---|
| color missing entirely | Mistyped custom property in a hand-written `var()`. Undefined variables resolve to nothing rather than erroring — check the kebab-case spelling, or use `defaultTheme` so the compiler checks the name. |
| color or shadow renders, but ignores the theme | A pinned token object was imported. `lightTheme` / `darkTheme` and `lightShadow` / `darkShadow` hold literal values; only `defaultTheme` and `defaultShadow` hold custom property references that follow the active theme. |
| `props.theme.yds` compiles, then throws at runtime | Your own `styled.d.ts` still augments `DefaultTheme` with `yds`. The type says it exists; 3.0 does not provide it. Delete those fields so the compiler lists the remaining reads. |
| Every `props.theme.*` is suddenly undefined | 2.x supplied styled-components' theme through `YdsThemeProvider`. 3.0 does not render one, so an app without its own `<ThemeProvider>` has an empty theme. |
| Sizes changed after dropping `ydsThemeProps` | `ydsThemeUnit` defaults to `'px'`, while a 2.x provider defaulted to `'rem'`. Pass `'rem'` explicitly or remove the call. |
| Tests fail parsing CSS after upgrading | Jest needs `moduleNameMapper: { '\\.css$': 'identity-obj-proxy' }`. |
| Components look unstyled after upgrading | The bundler is not processing CSS Modules from `node_modules`. |
| Every component lost its padding and margins | A global reset. Unlayered declarations beat `@layer yds`. Move the reset into a layer below `yds` — [Breaking changes](./breaking-changes-in-v3.md#global-resets). If it is `createGlobalStyle`, see [Global CSS resets](#resets). |
| The reset is in a layer, but still overrides YDS | The `@layer reset, yds, app;` statement is being parsed after the first YDS rule. Import the file that declares the order at the top of your entry. |
| App turned dark on some machines | `theme` now defaults to `'default'`, which follows `prefers-color-scheme`. Pass `theme="light"` to pin it. |
| Sizes shifted slightly | `unit` / `baseUnit` are gone; components emit `rem` at a `1rem = 16px` baseline. Convert with PostCSS if the app uses a different root font size. |
| Spacing inconsistent between YDS and app code | JS spacing tokens are px strings (`SPACING_16 === '16px'`) while component CSS uses `rem`. These agree at a 16px root and diverge otherwise — use `var(--yds-spacing-16)` to stay consistent. |
| Theme applies, then a portal renders unthemed | Content portalled out of the provider's subtree does not inherit its tokens. Apply `useThemeContext().className` to the portal container, or put tokens on `:root`. |

## Related

- [Get started with yds-components-react 3.0](./get-started-with-v3.md) — Install, tokens, first component.
- [Breaking changes in React package 3.0](./breaking-changes-in-v3.md) — Catalogue of what 3.0 breaks.
- [CSS class naming conventions](./css-conventions.md) — Local names, `all.css` mapping, and element vocabulary.
- [YdsThemeProvider](../../components/YdsThemeProvider/YdsThemeProvider.md) — Alternative to token CSS for a subtree or React-driven theme.
- [Design Tokens](../../design-tokens/index.md) — Token system and CSS-based theming.