# Carbon Components Svelte

Carbon Components Svelte is a [Svelte](https://github.com/sveltejs/svelte)
component library that implements the
[Carbon Design System](https://www.carbondesignsystem.com/), an open source
design system by IBM.

## Installation

```sh
# npm
npm i carbon-components-svelte

# pnpm
pnpm i carbon-components-svelte

# Yarn
yarn add carbon-components-svelte

# Bun
bun add carbon-components-svelte
```

## Styling

Before importing components, you will need to first apply Carbon component
styles. The Carbon Design System supports five themes (2 light, 3 dark): White,
Gray 10, Gray 80, Gray 90, Gray 100.

This CSS needs only to be imported once, preferably at the root of your
application.

```javascript
// White theme
import "carbon-components-svelte/css/white.css";

// Gray 10 theme
import "carbon-components-svelte/css/g10.css";

// Gray 80 theme
import "carbon-components-svelte/css/g80.css";

// Gray 90 theme
import "carbon-components-svelte/css/g90.css";

// Gray 100 theme
import "carbon-components-svelte/css/g100.css";

// All themes
import "carbon-components-svelte/css/all.css";
```

The `all.css` StyleSheet uses CSS variables to dynamically switch between
themes.

## Optimization

For smaller bundles and faster builds, use
[carbon-preprocess-svelte](https://github.com/carbon-design-system/carbon-preprocess-svelte)
with `optimizeImports` and `optimizeCss` below.

Install
[carbon-preprocess-svelte](https://github.com/carbon-design-system/carbon-preprocess-svelte)
as a development dependency:

```bash
npm i -D carbon-preprocess-svelte

# pnpm
pnpm i -D carbon-preprocess-svelte

# Yarn
yarn add -D carbon-preprocess-svelte

# Bun
bun add -D carbon-preprocess-svelte
```

### optimizeImports

`optimizeImports` is a Svelte preprocessor that rewrites barrel imports from
Carbon components/icons/pictograms packages to their source Svelte code paths.
This speeds up development and production build compile times while preserving
IDE typeahead and autocompletion.

It optimizes imports from `carbon-components-svelte`, `carbon-icons-svelte`, and
`carbon-pictograms-svelte`. Example transformation:

```diff
- import { Button } from "carbon-components-svelte";
+ import Button from "carbon-components-svelte/src/Button/Button.svelte";

- import { Add } from "carbon-icons-svelte";
+ import Add from "carbon-icons-svelte/lib/Add.svelte";
```

**SvelteKit:** add it to `svelte.config.js`. If you use Vite, `vitePreprocess`
should run before `optimizeImports`:

```javascript
// svelte.config.js (SvelteKit)
import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
import { optimizeImports } from "carbon-preprocess-svelte";

export default {
  preprocess: [vitePreprocess(), optimizeImports()],
};
```

**Plain Vite:** pass the preprocessor in `vite.config.js` when calling the
Svelte plugin:

```javascript
// vite.config.js (plain Vite + Svelte)
import { svelte } from "@sveltejs/vite-plugin-svelte";
import { optimizeCss, optimizeImports } from "carbon-preprocess-svelte";

export default {
  plugins: [svelte({ preprocess: [optimizeImports()] }), optimizeCss()],
};
```

### optimizeCss

`optimizeCss` is a Vite plugin that removes unused Carbon styles at build time.
`carbon-components-svelte@0.85.0` or greater is required. Add it to your Vite
config:

```javascript
// vite.config.js
import { sveltekit } from "@sveltejs/kit/vite";
import { optimizeCss } from "carbon-preprocess-svelte";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [sveltekit(), optimizeCss()],
});
```

## Dynamic theming

Use the `all.css` StyleSheet for dynamic, client-side theming:

```javascript
import "carbon-components-svelte/css/all.css";
```

Programmatically switch between each of the five Carbon themes by setting the
"theme" attribute on the HTML element:

```svelte
<script>
  let theme = "white"; // "white" | "g10" | "g80" | "g90" | "g100"

  $: document.documentElement.setAttribute("theme", theme);
</script>
```

You can use the `Theme` component to update the theme at runtime.

## Collection

The Carbon Svelte collection includes packages for icons, pictograms, and data
visualization:

- **Carbon Components Svelte** — 50+ components —
  [GitHub](https://github.com/carbon-design-system/carbon-components-svelte)
- **Carbon Icons Svelte** — 2,600+ icons —
  [GitHub](https://github.com/carbon-design-system/carbon-icons-svelte)
- **Carbon Pictograms Svelte** — 1,500+ pictograms —
  [GitHub](https://github.com/carbon-design-system/carbon-pictograms-svelte)
- **Carbon Charts Svelte** — 25+ charts, powered by d3 —
  [GitHub](https://github.com/carbon-design-system/carbon-charts/tree/master/packages/svelte)
- **Carbon Preprocess Svelte** — Collection of Carbon Svelte preprocessors —
  [GitHub](https://github.com/carbon-design-system/carbon-preprocess-svelte)

## Accordion

Accordions create a vertically stacked list of expandable sections that show or
hide content. They support custom titles, different sizes, and various states
including disabled and skeleton loading.

### Default

Use the accordion and accordion item components to compose a collapsible list of
items.

By default, the chevron icon is on the right side of the accordion item.

```svelte
<script>
  import { Accordion, AccordionItem } from "carbon-components-svelte";
</script>

<Accordion>
  <AccordionItem title="Natural Language Classifier">
    <p>
      Natural Language Classifier uses advanced natural language processing and
      machine learning techniques to create custom classification models. Users
      train their data and the service predicts the appropriate category for the
      inputted text.
    </p>
  </AccordionItem>
  <AccordionItem title="Natural Language Understanding">
    <p>
      Analyze text to extract meta-data from content such as concepts, entities,
      emotion, relations, sentiment and more.
    </p>
  </AccordionItem>
  <AccordionItem title="Language Translator">
    <p>
      Translate text, documents, and websites from one language to another.
      Create industry or region-specific translations via the service's
      customization capability.
    </p>
  </AccordionItem>
</Accordion>
```

### Left-aligned chevron

The chevron icon can be aligned to the left side of the accordion item by
setting the `align` prop to "start". This provides an alternative visual style
while maintaining the same functionality.

```svelte
<script>
  import { Accordion, AccordionItem } from "carbon-components-svelte";
</script>

<Accordion align="start">
  <AccordionItem title="Natural Language Classifier">
    <p>
      Natural Language Classifier uses advanced natural language processing and
      machine learning techniques to create custom classification models. Users
      train their data and the service predicts the appropriate category for the
      inputted text.
    </p>
  </AccordionItem>
  <AccordionItem title="Natural Language Understanding">
    <p>
      Analyze text to extract meta-data from content such as concepts, entities,
      emotion, relations, sentiment and more.
    </p>
  </AccordionItem>
  <AccordionItem title="Language Translator">
    <p>
      Translate text, documents, and websites from one language to another.
      Create industry or region-specific translations via the service's
      customization capability.
    </p>
  </AccordionItem>
</Accordion>
```

### Custom title slot

Customize the title content by using the `title` slot instead of the `title`
prop. This allows for more complex title layouts with multiple elements.

```svelte
<script>
  import { Accordion, AccordionItem } from "carbon-components-svelte";
</script>

<Accordion>
  <AccordionItem>
    <svelte:fragment slot="title">
      <h5>Natural Language Classifier</h5>
      <div>AI / Machine Learning</div>
    </svelte:fragment>
    <p>
      Natural Language Classifier uses advanced natural language processing and
      machine learning techniques to create custom classification models. Users
      train their data and the service predicts the appropriate category for the
      inputted text.
    </p>
  </AccordionItem>
  <AccordionItem>
    <svelte:fragment slot="title">
      <h5>Natural Language Understanding</h5>
      <div>AI / Machine Learning</div>
    </svelte:fragment>
    <p>
      Analyze text to extract meta-data from content such as concepts, entities,
      emotion, relations, sentiment and more.
    </p>
  </AccordionItem>
  <AccordionItem>
    <svelte:fragment slot="title">
      <h5>Language Translator</h5>
      <div>AI / Machine Learning</div>
    </svelte:fragment>
    <p>
      Translate text, documents, and websites from one language to another.
      Create industry or region-specific translations via the service's
      customization capability.
    </p>
  </AccordionItem>
</Accordion>
```

### First item open

Set the `open` prop on an accordion item to have it expanded by default when the
accordion is first rendered.

```svelte
<script>
  import { Accordion, AccordionItem } from "carbon-components-svelte";
</script>

<Accordion>
  <AccordionItem open title="Natural Language Classifier">
    <p>
      Natural Language Classifier uses advanced natural language processing and
      machine learning techniques to create custom classification models. Users
      train their data and the service predicts the appropriate category for the
      inputted text.
    </p>
  </AccordionItem>
  <AccordionItem title="Natural Language Understanding">
    <p>
      Analyze text to extract meta-data from content such as concepts, entities,
      emotion, relations, sentiment and more.
    </p>
  </AccordionItem>
  <AccordionItem title="Language Translator">
    <p>
      Translate text, documents, and websites from one language to another.
      Create industry or region-specific translations via the service's
      customization capability.
    </p>
  </AccordionItem>
</Accordion>
```

### Programmatic example

This example demonstrates how to programmatically control the accordion items
using the `bind:open` directive. Expand and collapse items based on user
interactions or application state.

```svelte
<script>
  import { Accordion, AccordionItem, Button } from "carbon-components-svelte";

  const items = [
    {
      title: "Natural Language Classifier",
      description:
        "Natural Language Classifier uses advanced natural language processing and machine learning techniques to create custom classification models. Users train their data and the service predicts the appropriate category for the inputted text.",
    },
    {
      title: "Natural Language Understanding",
      description:
        "Analyze text to extract meta-data from content such as concepts, entities, emotion, relations, sentiment and more.",
    },
    {
      title: "Language Translator",
      description:
        "Translate text, documents, and websites from one language to another. Create industry or region-specific translations via the service's customization capability.",
    },
  ];

  let open = false;
</script>

<Button kind="ghost" size="field" on:click={() => (open = !open)}>
  {open ? "Collapse" : "Expand"}
  all
</Button>

<Accordion>
  {#each items as item}
    <AccordionItem title={item.title} {open}>
      <p>{item.description}</p>
    </AccordionItem>
  {/each}
</Accordion>
```

### Extra-large size

The accordion can be displayed in an extra-large size by setting the `size` prop
to "xl". This provides more visual emphasis and is suitable for prominent
content sections.

```svelte
<script>
  import { Accordion, AccordionItem } from "carbon-components-svelte";
</script>

<Accordion size="xl">
  <AccordionItem title="Natural Language Classifier">
    <p>
      Natural Language Classifier uses advanced natural language processing and
      machine learning techniques to create custom classification models. Users
      train their data and the service predicts the appropriate category for the
      inputted text.
    </p>
  </AccordionItem>
  <AccordionItem title="Natural Language Understanding">
    <p>
      Analyze text to extract meta-data from content such as concepts, entities,
      emotion, relations, sentiment and more.
    </p>
  </AccordionItem>
  <AccordionItem title="Language Translator">
    <p>
      Translate text, documents, and websites from one language to another.
      Create industry or region-specific translations via the service's
      customization capability.
    </p>
  </AccordionItem>
</Accordion>
```

### Small size

For more compact layouts, set the `size` prop to "sm" to display the accordion
in a smaller size. This is useful when space is limited or when the accordion is
used as a secondary UI element.

```svelte
<script>
  import { Accordion, AccordionItem } from "carbon-components-svelte";
</script>

<Accordion size="sm">
  <AccordionItem title="Natural Language Classifier">
    <p>
      Natural Language Classifier uses advanced natural language processing and
      machine learning techniques to create custom classification models. Users
      train their data and the service predicts the appropriate category for the
      inputted text.
    </p>
  </AccordionItem>
  <AccordionItem title="Natural Language Understanding">
    <p>
      Analyze text to extract meta-data from content such as concepts, entities,
      emotion, relations, sentiment and more.
    </p>
  </AccordionItem>
  <AccordionItem title="Language Translator">
    <p>
      Translate text, documents, and websites from one language to another.
      Create industry or region-specific translations via the service's
      customization capability.
    </p>
  </AccordionItem>
</Accordion>
```

### Disabled state

Set the `disabled` prop on the accordion to disable all items at once. This
prevents users from expanding or collapsing any items in the accordion.

```svelte
<script>
  import { Accordion, AccordionItem } from "carbon-components-svelte";
</script>

<Accordion disabled>
  <AccordionItem title="Natural Language Classifier">
    <p>
      Natural Language Classifier uses advanced natural language processing and
      machine learning techniques to create custom classification models. Users
      train their data and the service predicts the appropriate category for the
      inputted text.
    </p>
  </AccordionItem>
  <AccordionItem title="Natural Language Understanding">
    <p>
      Analyze text to extract meta-data from content such as concepts, entities,
      emotion, relations, sentiment and more.
    </p>
  </AccordionItem>
  <AccordionItem title="Language Translator">
    <p>
      Translate text, documents, and websites from one language to another.
      Create industry or region-specific translations via the service's
      customization capability.
    </p>
  </AccordionItem>
</Accordion>
```

### Batch disable

Programmatically toggle the disabled state of all accordion items using the
`disabled` prop. In this example, disabling all items also collapses them.

```svelte
<script>
  import {
    Accordion,
    AccordionItem,
    Button,
    ButtonSet,
  } from "carbon-components-svelte";

  let disabled = false;

  const items = [
    {
      title: "Natural Language Classifier",
      description:
        "Natural Language Classifier uses advanced natural language processing and machine learning techniques to create custom classification models. Users train their data and the service predicts the appropriate category for the inputted text.",
    },
    {
      title: "Natural Language Understanding",
      description:
        "Analyze text to extract meta-data from content such as concepts, entities, emotion, relations, sentiment and more.",
    },
    {
      title: "Language Translator",
      description:
        "Translate text, documents, and websites from one language to another. Create industry or region-specific translations via the service's customization capability.",
    },
  ];

  let open = false;
</script>

<ButtonSet>
  <Button size="field" {disabled} on:click={() => (open = !open)}>
    {open ? "Collapse" : "Expand"} all
  </Button>
  <Button
    kind="ghost"
    size="field"
    on:click={() => {
      disabled = !disabled;
      if (disabled) {
        open = false;
      }
    }}
  >
    {disabled ? "Enable" : "Disable"} all
  </Button>
</ButtonSet>

<Accordion {disabled}>
  {#each items as item}
    <AccordionItem title={item.title} {open}>
      <p>{item.description}</p>
    </AccordionItem>
  {/each}
</Accordion>
```

### Disabled (item)

Individual accordion items can be disabled by setting the `disabled` prop on
specific accordion item components. This allows for more granular control over
which items are interactive.

```svelte
<script>
  import { Accordion, AccordionItem } from "carbon-components-svelte";
</script>

<Accordion>
  <AccordionItem disabled title="Natural Language Classifier">
    <p>
      Natural Language Classifier uses advanced natural language processing and
      machine learning techniques to create custom classification models. Users
      train their data and the service predicts the appropriate category for the
      inputted text.
    </p>
  </AccordionItem>
  <AccordionItem title="Natural Language Understanding">
    <p>
      Analyze text to extract meta-data from content such as concepts, entities,
      emotion, relations, sentiment and more.
    </p>
  </AccordionItem>
  <AccordionItem title="Language Translator">
    <p>
      Translate text, documents, and websites from one language to another.
      Create industry or region-specific translations via the service's
      customization capability.
    </p>
  </AccordionItem>
</Accordion>
```

### Skeleton

The skeleton state provides a loading placeholder for the accordion. It displays
a simplified version of the component while content is being loaded.

```svelte
<script>
  import { Accordion } from "carbon-components-svelte";
</script>

<Accordion skeleton />
```

### Skeleton (left-aligned chevron)

The skeleton state can be combined with the left-aligned chevron style by
setting both the `skeleton` and `align="start"` props.

```svelte
<script>
  import { Accordion } from "carbon-components-svelte";
</script>

<Accordion skeleton align="start" />
```

### Skeleton (custom count)

By default, the skeleton state displays 4 items.

Specify the number of skeleton items to display using the `count` prop. This is
useful when you know the exact number of items that will be loaded.

```svelte
<script>
  import { Accordion } from "carbon-components-svelte";
</script>

<Accordion skeleton count={3} />
```

### Skeleton (closed)

By default, the first skeleton item is open. The skeleton state can be displayed
in a collapsed state by setting `open={false}`.

```svelte
<script>
  import { Accordion } from "carbon-components-svelte";
</script>

<Accordion skeleton open={false} />
```

### Skeleton (extra-large)

The skeleton state supports the extra-large size variant, maintaining visual
consistency with the active component states.

```svelte
<script>
  import { Accordion } from "carbon-components-svelte";
</script>

<Accordion skeleton size="xl" />
```

### Skeleton (small)

The skeleton state also supports the small size variant, providing a compact
loading placeholder for space-constrained layouts.

```svelte
<script>
  import { Accordion } from "carbon-components-svelte";
</script>

<Accordion skeleton size="sm" />
```

---

### Component API

#### `Accordion` props

| Prop       | Type               | Description                                       | Default     |
| ---------- | ------------------ | ------------------------------------------------- | ----------- |
| `align`    | `"start" \| "end"` | Specify alignment of accordion item chevron icon. | `"end"`     |
| `size`     | `"sm" \| "xl"`     | Specify the size of the accordion.                | _undefined_ |
| `disabled` | `boolean`          | Set to `true` to disable the accordion            | `false`     |
| `skeleton` | `boolean`          | Set to `true` to display the skeleton state       | `false`     |

#### `Accordion` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `Accordion` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `Accordion` $$restProps

`Accordion` spreads `$$restProps` to the `AccordionSkeleton` component.

#### `AccordionItem` props

| Prop                  | Type      | Description                                                                                | Default             |
| --------------------- | --------- | ------------------------------------------------------------------------------------------ | ------------------- |
| `open` (Reactive)     | `boolean` | Set to `true` to open the first accordion item                                             | `false`             |
| `disabled` (Reactive) | `boolean` | Set to `true` to disable the accordion item                                                | `false`             |
| `title`               | `string`  | Specify the title of the accordion item heading.<br />Alternatively, use the "title" slot. | `"title"`           |
| `iconDescription`     | `string`  | Specify the ARIA label for the accordion item chevron icon                                 | `"Expand/Collapse"` |

#### `AccordionItem` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |
| `title`   | `Record<string, never>` |

#### `AccordionItem` forwarded events

| Event             |
| ----------------- |
| `on:animationend` |
| `on:click`        |
| `on:mouseover`    |
| `on:mouseenter`   |
| `on:mouseleave`   |
| `on:keydown`      |

#### `AccordionItem` $$restProps

`AccordionItem` spreads `$$restProps` to the `li` element.

#### `AccordionSkeleton` props

| Prop    | Type               | Description                                       | Default     |
| ------- | ------------------ | ------------------------------------------------- | ----------- |
| `count` | `number`           | Specify the number of accordion items to render   | `4`         |
| `align` | `"start" \| "end"` | Specify alignment of accordion item chevron icon. | `"end"`     |
| `size`  | `"sm" \| "xl"`     | Specify the size of the accordion.                | _undefined_ |
| `open`  | `boolean`          | Set to `false` to close the first accordion item  | `true`      |

#### `AccordionSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `AccordionSkeleton` $$restProps

`AccordionSkeleton` spreads `$$restProps` to the `ul` element.


## AspectRatio

Aspect ratios maintain consistent proportions for content across different
screen sizes. They are particularly useful for images, videos, and other media
that need to preserve their aspect ratio when resizing.

Supported aspect ratios include `"2x1"`, `"2x3"`, `"16x9"`, `"4x3"`, `"1x1"`,
`"3x4"`, `"3x2"`, `"9x16"` and `"1x2"`.

### Default

Display a 2:1 aspect ratio container by default.

```svelte
<script>
  import { AspectRatio } from "carbon-components-svelte";
</script>

<AspectRatio>2x1</AspectRatio>
```

### Ratio 2x3

Display content with a 2:3 aspect ratio.

```svelte
<script>
  import { AspectRatio } from "carbon-components-svelte";
</script>

<AspectRatio ratio="2x3">2x3</AspectRatio>
```

### Ratio 16x9

Display content with a 16:9 aspect ratio.

```svelte
<script>
  import { AspectRatio } from "carbon-components-svelte";
</script>

<AspectRatio ratio="16x9">16x9</AspectRatio>
```

### Ratio 4x3

Display content with a 4:3 aspect ratio.

```svelte
<script>
  import { AspectRatio } from "carbon-components-svelte";
</script>

<AspectRatio ratio="4x3">4x3</AspectRatio>
```

### Ratio 1x1

Display content with a 1:1 (square) aspect ratio.

```svelte
<script>
  import { AspectRatio } from "carbon-components-svelte";
</script>

<AspectRatio ratio="1x1">1x1</AspectRatio>
```

### Ratio 3x4

Display content with a 3:4 aspect ratio.

```svelte
<script>
  import { AspectRatio } from "carbon-components-svelte";
</script>

<AspectRatio ratio="3x4">3x4</AspectRatio>
```

### Ratio 3x2

Display content with a 3:2 aspect ratio.

```svelte
<script>
  import { AspectRatio } from "carbon-components-svelte";
</script>

<AspectRatio ratio="3x2">3x2</AspectRatio>
```

### Ratio 9x16

Display content with a 9:16 aspect ratio.

```svelte
<script>
  import { AspectRatio } from "carbon-components-svelte";
</script>

<AspectRatio ratio="9x16">9x16</AspectRatio>
```

### Ratio 1x2

Display content with a 1:2 aspect ratio.

```svelte
<script>
  import { AspectRatio } from "carbon-components-svelte";
</script>

<AspectRatio ratio="1x2">1x2</AspectRatio>
```

### Tile (16x9)

Wrap a tile or other content in an aspect ratio container to maintain
proportions.

```svelte
<script>
  import { AspectRatio, Tile } from "carbon-components-svelte";
</script>

<AspectRatio ratio="16x9">
  <Tile style="height: 100%">Content</Tile>
</AspectRatio>
```

---

### Component API

#### `AspectRatio` props

| Prop    | Type                                                                              | Description               | Default |
| ------- | --------------------------------------------------------------------------------- | ------------------------- | ------- |
| `ratio` | `"2x1" \| "2x3" \| "16x9" \| "4x3" \| "1x1" \| "3x4" \| "3x2" \| "9x16" \| "1x2"` | Specify the aspect ratio. | `"2x1"` |

#### `AspectRatio` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `AspectRatio` $$restProps

`AspectRatio` spreads `$$restProps` to the `div` element.


## Breadcrumb

Breadcrumbs display a hierarchical navigation trail that shows users their
current location within an application. They support current page indication,
trailing slash customization, and overflow handling for long navigation paths.

### Default

Display a hierarchical navigation trail with slashes between items. Mark the
current page with `isCurrentPage`.

```svelte
<script>
  import { Breadcrumb, BreadcrumbItem } from "carbon-components-svelte";
</script>

<Breadcrumb>
  <BreadcrumbItem href="/">Dashboard</BreadcrumbItem>
  <BreadcrumbItem href="/reports">Annual reports</BreadcrumbItem>
  <BreadcrumbItem href="/reports/2019" isCurrentPage>2019</BreadcrumbItem>
</Breadcrumb>
```

### No trailing slash

Remove the trailing slash from the last breadcrumb item using `noTrailingSlash`.

```svelte
<script>
  import { Breadcrumb, BreadcrumbItem } from "carbon-components-svelte";
</script>

<Breadcrumb noTrailingSlash>
  <BreadcrumbItem href="/">Home</BreadcrumbItem>
  <BreadcrumbItem href="/profile" isCurrentPage>Profile</BreadcrumbItem>
</Breadcrumb>
```

### Overflow menu

Add an overflow menu to handle long breadcrumb trails. Use overflow menu item
components for menu options.

```svelte
<script>
  import {
    Breadcrumb,
    BreadcrumbItem,
    OverflowMenu,
    OverflowMenuItem,
  } from "carbon-components-svelte";
</script>

<Breadcrumb>
  <BreadcrumbItem href="/">Home</BreadcrumbItem>
  <BreadcrumbItem href="/api">API documentation</BreadcrumbItem>
  <BreadcrumbItem>
    <OverflowMenu>
      <OverflowMenuItem href="/api/data" text="Data" />
      <OverflowMenuItem href="/api/data/latest" text="Latest" />
    </OverflowMenu>
  </BreadcrumbItem>
  <BreadcrumbItem href="/api/data/latest/usage" isCurrentPage>
    Usage
  </BreadcrumbItem>
</Breadcrumb>
```

### Breadcrumb trail

Build a full breadcrumb trail with multiple items and a current page indicator.

```svelte
<script>
  import { Breadcrumb, BreadcrumbItem } from "carbon-components-svelte";

  const items = [
    { href: "/", text: "Dashboard" },
    { href: "/reports", text: "Annual reports" },
    { href: "/reports/2019", text: "2019" },
  ];
</script>

<Breadcrumb>
  {#each items as item, i}
    <BreadcrumbItem href={item.href} isCurrentPage={i === items.length - 1}>
      {item.text}
    </BreadcrumbItem>
  {/each}
</Breadcrumb>
```

### Skeleton

Display a loading state with `skeleton` prop. Use `count` to specify the number
of items.

```svelte
<script>
  import { Breadcrumb } from "carbon-components-svelte";
</script>

<Breadcrumb noTrailingSlash skeleton count={3} />
```

---

### Component API

#### `Breadcrumb` props

| Prop              | Type      | Description                                         | Default |
| ----------------- | --------- | --------------------------------------------------- | ------- |
| `noTrailingSlash` | `boolean` | Set to `true` to hide the breadcrumb trailing slash | `false` |
| `skeleton`        | `boolean` | Set to `true` to display skeleton state             | `false` |

#### `Breadcrumb` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `Breadcrumb` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `Breadcrumb` $$restProps

`Breadcrumb` spreads `$$restProps` to the `BreadcrumbSkeleton` component.

#### `BreadcrumbItem` props

| Prop            | Type      | Description                                                      | Default     |
| --------------- | --------- | ---------------------------------------------------------------- | ----------- |
| `href`          | `string`  | Set the `href` to use an anchor link.                            | _undefined_ |
| `isCurrentPage` | `boolean` | Set to `true` if the breadcrumb item represents the current page | `false`     |

#### `BreadcrumbItem` slots

| Slot      | Detail                                                                                      |
| --------- | ------------------------------------------------------------------------------------------- |
| `default` | `{<br /> props?: {<br /> "aria-current"?: string;<br /> class: "bx--link";<br /> };<br />}` |

#### `BreadcrumbItem` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `BreadcrumbItem` $$restProps

`BreadcrumbItem` spreads `$$restProps` to the `li` element.


## Breakpoint

The Carbon Design System
[grid implementation](https://carbondesignsystem.com/guidelines/2x-grid/implementation#responsive-options)
defines five responsive breakpoints:

- **Small**: less than 672px
- **Medium**: 672 - 1056px
- **Large**: 1056 - 1312px
- **X-Large**: 1312 - 1584px
- **Max**: greater than 1584px

This utility component uses the
[Window.matchMedia API](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia)
to declaratively determine the current Carbon breakpoint size.

### Default

Bind to the `size` prop to determine the current breakpoint size. Possible
values include: `"sm" | "md" | "lg" | "xlg" | "max"`.

The `"on:change"` event will fire when the size is initially determined and when
a breakpoint change event occurs (e.g., the browser width is resized).

```svelte
<script>
  import { Breakpoint } from "carbon-components-svelte";

  let size;
  let events = [];
</script>

<Breakpoint bind:size on:change={(e) => (events = [...events, e.detail])} />

<p>Resize the width of your browser.</p>
<h6>Breakpoint size</h6>
<h1>{size}</h1>

<h6>on:change</h6>
<pre>{JSON.stringify(events, null, 2)}</pre>

<style>
  p,
  h1 {
    margin-bottom: var(--cds-spacing-08);
  }

  h6 {
    margin-bottom: var(--cds-spacing-03);
  }
</style>
```

### Store and Breakpoint Values

Use `breakpointObserver` as an alternative to the component to get the current
size as a Svelte store. The store provides two additional functions that create
derived stores returning a `boolean` indicating whether the size is
smaller/larger than a certain breakpoint.

Access the `breakpoints` dictionary to map from `BreakpointSize` to
`BreakpointValue`.

```svelte
<script>
  import { breakpointObserver, breakpoints } from "carbon-components-svelte";

  const size = breakpointObserver();
  const smaller = size.smallerThan("md");
  const larger = size.largerThan("md");
</script>

<p>Current breakpoint size: {$size}</p>
<p>Current breakpoint value: {breakpoints[$size]}px</p>
<p>Smaller than medium: {$smaller}</p>
<p>Larger than medium: {$larger}</p>
```

---

### Component API

#### `Breakpoint` props

| Prop               | Type                              | Description                                        | Default                                                                                           |
| ------------------ | --------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `size` (Reactive)  | `BreakpointSize`                  | Determine the current Carbon grid breakpoint size. | _undefined_                                                                                       |
| `sizes` (Reactive) | `Record<BreakpointSize, boolean>` | Carbon grid sizes as an object.                    | `{<br /> sm: false,<br /> md: false,<br /> lg: false,<br /> xlg: false,<br /> max: false,<br />}` |

#### `Breakpoint` typedefs

```ts
type BreakpointSize = "sm" | "md" | "lg" | "xlg" | "max";

type BreakpointValue = 320 | 672 | 1056 | 1312 | 1584;
```

#### `Breakpoint` slots

| Slot      | Detail                                                                                                   |
| --------- | -------------------------------------------------------------------------------------------------------- |
| `default` | `{<br /> size: BreakpointSize;<br /> sizes: Record<<br /> BreakpointSize,<br /> boolean<br /> >;<br />}` |

#### `Breakpoint` dispatched events

| Event       | Detail                                                                         |
| ----------- | ------------------------------------------------------------------------------ |
| `on:change` | `{<br /> size: BreakpointSize;<br /> breakpointValue: BreakpointValue;<br />}` |


## Button

Buttons trigger actions in the interface. Use them to submit forms, navigate
between pages, or perform specific tasks. Choose from different styles and sizes
to match the importance and context of each action.

### Primary button

The default button style is primary. This should be used for primary actions.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button>Primary button</Button>
```

### Secondary button

Set `kind="secondary"` for secondary actions.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button kind="secondary">Secondary button</Button>
```

### Tertiary button

Set `kind="tertiary"` for tertiary actions.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button kind="tertiary">Tertiary button</Button>
```

### Ghost button

Set `kind="ghost"` for ghost-style buttons.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button kind="ghost">Ghost button</Button>
```

### Danger button

Set `kind="danger"` for destructive actions.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button kind="danger">Danger button</Button>
```

### Danger tertiary button

Set `kind="danger-tertiary"` for less prominent destructive actions.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button kind="danger-tertiary">Danger tertiary button</Button>
```

### Danger tertiary, icon-only button

Create an icon-only danger tertiary button by omitting the label text and
providing an icon description for accessibility.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
  import TrashCan from "carbon-icons-svelte/lib/TrashCan.svelte";
</script>

<Button kind="danger-tertiary" iconDescription="Delete" icon={TrashCan} />
```

### Danger ghost button

Set `kind="danger-ghost"` for ghost-style destructive actions.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button kind="danger-ghost">Danger ghost button</Button>
```

### Button with icon

Add an icon to the button using the `icon` prop.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<Button icon={Add}>With icon</Button>
```

### Icon-only button

> [!NOTE] Provide an **iconDescription** for accessibility. This text will be
> used as the button's tooltip and screen reader label.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<Button iconDescription="Tooltip text" icon={Add} />
```

### Icon-only, link button

Set `href` to create an icon-only link button.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
  import Login from "carbon-icons-svelte/lib/Login.svelte";
</script>

<Button iconDescription="Login" icon={Login} href="#" />
```

### Icon-only button (custom tooltip position)

Control the tooltip position and alignment with `tooltipPosition` and
`tooltipAlignment`.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<Button
  tooltipPosition="right"
  tooltipAlignment="end"
  iconDescription="Tooltip text"
  icon={Add}
/>
```

### Icon-only button (hidden tooltip)

Set `hideTooltip` to `true` to visually hide the tooltip while maintaining
accessibility for screen readers.

> [!NOTE] Use this when tooltips cause layout issues, interfere with
> interactions, or when multiple icon buttons are densely packed (e.g.,
> toolbars). The **iconDescription** remains accessible to screen readers.

```svelte
<script>
  import { Button, Stack } from "carbon-components-svelte";
  import Add from "carbon-icons-svelte/lib/Add.svelte";
  import Login from "carbon-icons-svelte/lib/Login.svelte";
  import TrashCan from "carbon-icons-svelte/lib/TrashCan.svelte";
</script>

<Stack orientation="horizontal" gap={2}>
  <Button hideTooltip iconDescription="Add item" icon={Add} />
  <Button
    hideTooltip
    iconDescription="Delete item"
    icon={TrashCan}
    kind="danger-tertiary"
  />
  <Button hideTooltip iconDescription="Login" icon={Login} kind="ghost" />
</Stack>
```

### Selected icon-only, ghost button

Set `isSelected` to `true` to enable the selected state for an icon-only, ghost
button.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
  import TextBold from "carbon-icons-svelte/lib/TextBold.svelte";
  import TextItalic from "carbon-icons-svelte/lib/TextItalic.svelte";
  import TextUnderline from "carbon-icons-svelte/lib/TextUnderline.svelte";

  let index = 1;
</script>

<Button
  isSelected={index === 0}
  kind="ghost"
  iconDescription="Bold"
  icon={TextBold}
  on:click={() => (index = 0)}
/>
<Button
  isSelected={index === 1}
  kind="ghost"
  iconDescription="Italicize"
  icon={TextItalic}
  on:click={() => (index = 1)}
/>
<Button
  isSelected={index === 2}
  kind="ghost"
  iconDescription="Underline"
  icon={TextUnderline}
  on:click={() => (index = 2)}
/>
```

### Adjacent icon-only buttons

When multiple icon-only buttons are placed next to each other, only one tooltip
will be visible at a time. Hovering a new button automatically hides the
previous tooltip, ensuring the correct button is always clicked.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
  import Add from "carbon-icons-svelte/lib/Add.svelte";
  import Save from "carbon-icons-svelte/lib/Save.svelte";
  import TrashCan from "carbon-icons-svelte/lib/TrashCan.svelte";

  let lastAction = "";
</script>

<Button
  kind="ghost"
  iconDescription="Add"
  tooltipPosition="right"
  icon={Add}
  on:click={() => (lastAction = "Add")}
/>
<Button
  kind="ghost"
  iconDescription="Delete"
  tooltipPosition="right"
  icon={TrashCan}
  on:click={() => (lastAction = "Delete")}
/>
<Button
  kind="ghost"
  iconDescription="Save"
  tooltipPosition="right"
  icon={Save}
  on:click={() => (lastAction = "Save")}
/>

{#if lastAction}
  Clicked: {lastAction}
{/if}
```

### Link button

Set `href` to render an
[anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a)
instead of a `button` element.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button href="#">Link button</Button>
```

### Link button with icon

Similarly, link buttons can have icons.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<Button href="#" icon={Add}>Link button with icon</Button>
```

### Custom element

By default, the button will render either a `button` or `a` element.

To render a different element, set `as` to `true` and spread `let:props` to the
element.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button as let:props>
  <p {...props}>Custom element</p>
</Button>
```

### Field size

Set `size="field"` for field-sized buttons that align with form input heights.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button size="field">Primary</Button>
<Button size="field" kind="secondary">Secondary</Button>
<Button size="field" kind="tertiary">Tertiary</Button>
<Button size="field" kind="ghost">Ghost</Button>
<Button size="field" kind="danger">Danger</Button>
```

### Small size

Set `size="small"` for small buttons.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button size="small">Primary</Button>
<Button size="small" kind="secondary">Secondary</Button>
<Button size="small" kind="tertiary">Tertiary</Button>
<Button size="small" kind="ghost">Ghost</Button>
<Button size="small" kind="danger">Danger</Button>
```

### Large size

Set `size="lg"` for large buttons.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button size="lg">Primary</Button>
<Button size="lg" kind="secondary">Secondary</Button>
<Button size="lg" kind="tertiary">Tertiary</Button>
<Button size="lg" kind="ghost">Ghost</Button>
<Button size="lg" kind="danger">Danger</Button>
```

### Extra-large size

Set `size="xl"` for extra-large buttons.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button size="xl">Primary</Button>
<Button size="xl" kind="secondary">Secondary</Button>
<Button size="xl" kind="tertiary">Tertiary</Button>
<Button size="xl" kind="ghost">Ghost</Button>
<Button size="xl" kind="danger">Danger</Button>
```

### Disabled state

Set `disabled` to disable the button.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<Button disabled>Disabled button</Button>
<Button disabled iconDescription="Tooltip text" icon={Add} />
```

### Expressive styles

Set `expressive` to `true` to use Carbon's expressive typesetting.

> [!NOTE] Use expressive styles with default, "lg", or "xl" button sizes.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button expressive size="xl">Primary</Button>
<Button expressive size="xl" kind="secondary">Secondary</Button>
<Button expressive size="xl" kind="tertiary">Tertiary</Button>
<Button expressive size="xl" kind="ghost">Ghost</Button>
<Button expressive size="xl" kind="danger">Danger</Button>
<br /><br />
<Button expressive size="lg">Primary</Button>
<Button expressive size="lg" kind="secondary">Secondary</Button>
<Button expressive size="lg" kind="tertiary">Tertiary</Button>
<Button expressive size="lg" kind="ghost">Ghost</Button>
<Button expressive size="lg" kind="danger">Danger</Button>
<br /><br />
<Button expressive>Primary</Button>
<Button expressive kind="secondary">Secondary</Button>
<Button expressive kind="tertiary">Tertiary</Button>
<Button expressive kind="ghost">Ghost</Button>
<Button expressive kind="danger">Danger</Button>
```

### Skeleton

Set `skeleton` to show a loading state.

```svelte
<script>
  import { Button } from "carbon-components-svelte";
</script>

<Button size="xl" skeleton />
<Button size="lg" skeleton />
<Button skeleton />
<Button skeleton size="field" />
<Button skeleton size="small" />
```

### Programmatic focus

Bind to the `ref` prop to access the button element for programmatic focus.

```svelte
<script>
  import { Button } from "carbon-components-svelte";

  let ref;
</script>

<Button bind:ref>Primary button</Button>
<Button
  kind="ghost"
  on:click={() => {
    ref?.focus();
  }}
>
  Click to focus the Primary button
</Button>
```

---

### Component API

#### `Button` props

| Prop               | Type                                                                                                   | Description                                                                                                                                                                                                                 | Default     |
| ------------------ | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `ref` (Reactive)   | `null \| HTMLAnchorElement \| HTMLButtonElement`                                                       | Obtain a reference to the HTML element                                                                                                                                                                                      | `null`      |
| `kind`             | `"primary" \| "secondary" \| "tertiary" \| "ghost" \| "danger" \| "danger-tertiary" \| "danger-ghost"` | Specify the kind of button.                                                                                                                                                                                                 | `"primary"` |
| `size`             | `"default" \| "field" \| "small" \| "lg" \| "xl"`                                                      | Specify the size of button.                                                                                                                                                                                                 | `"default"` |
| `expressive`       | `boolean`                                                                                              | Set to `true` to use Carbon's expressive typesetting                                                                                                                                                                        | `false`     |
| `isSelected`       | `boolean`                                                                                              | Set to `true` to enable the selected state for an icon-only, ghost button.                                                                                                                                                  | `false`     |
| `icon`             | `any`                                                                                                  | Specify the icon to render.<br />Alternatively, use the named slot "icon".                                                                                                                                                  | _undefined_ |
| `iconDescription`  | `string`                                                                                               | Specify the ARIA label for the button icon.                                                                                                                                                                                 | _undefined_ |
| `tooltipAlignment` | `"start" \| "center" \| "end"`                                                                         | Set the alignment of the tooltip relative to the icon.<br />Only applies to icon-only buttons.                                                                                                                              | `"center"`  |
| `tooltipPosition`  | `"top" \| "right" \| "bottom" \| "left"`                                                               | Set the position of the tooltip relative to the icon.                                                                                                                                                                       | `"bottom"`  |
| `hideTooltip`      | `boolean`                                                                                              | Set to `true` to hide the tooltip while maintaining accessibility.<br />Only applies to icon-only buttons.<br />When `true`, the tooltip is visually hidden but the `iconDescription` remains accessible to screen readers. | `false`     |
| `as`               | `boolean`                                                                                              | Set to `true` to render a custom HTML element.<br />Props are destructured as `props` in the default slot.                                                                                                                  | `false`     |
| `skeleton`         | `boolean`                                                                                              | Set to `true` to display the skeleton state                                                                                                                                                                                 | `false`     |
| `disabled`         | `boolean`                                                                                              | Set to `true` to disable the button                                                                                                                                                                                         | `false`     |
| `href`             | `string`                                                                                               | Set the `href` to use an anchor link.                                                                                                                                                                                       | _undefined_ |
| `tabindex`         | `string`                                                                                               | Specify the tabindex                                                                                                                                                                                                        | `"0"`       |
| `type`             | `string`                                                                                               | Specify the `type` attribute for the button element                                                                                                                                                                         | `"button"`  |

#### `Button` slots

| Slot      | Detail                                                                                                                                                                                          |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | `{<br /> props: {<br /> role: "button";<br /> type?: string;<br /> tabindex: any;<br /> disabled: boolean;<br /> href?: string;<br /> class: string;<br /> [key: string]: any;<br /> };<br />}` |
| `icon`    | `{<br /> style: undefined \| string;<br />}`                                                                                                                                                    |

#### `Button` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:focus`      |
| `on:blur`       |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `Button` $$restProps

`Button` spreads `$$restProps` to the `button | a | div` element.


## ButtonSet

Group related buttons together in a set. Use this component to create consistent
spacing and alignment between multiple buttons.

### Default

Place buttons side by side in a horizontal layout.

```svelte
<script>
  import { Button, ButtonSet } from "carbon-components-svelte";
</script>

<ButtonSet>
  <Button kind="secondary">Cancel</Button>
  <Button>Submit</Button>
</ButtonSet>
```

### Stacked

Set `stacked` to `true` to arrange buttons vertically.

```svelte
<script>
  import { Button, ButtonSet } from "carbon-components-svelte";
  import Login from "carbon-icons-svelte/lib/Login.svelte";
</script>

<ButtonSet stacked>
  <Button icon={Login}>Log in</Button>
  <Button kind="ghost">Sign up</Button>
</ButtonSet>
```

---

### Component API

#### `ButtonSet` props

| Prop      | Type      | Description                                   | Default |
| --------- | --------- | --------------------------------------------- | ------- |
| `stacked` | `boolean` | Set to `true` to stack the buttons vertically | `false` |

#### `ButtonSet` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ButtonSet` $$restProps

`ButtonSet` spreads `$$restProps` to the `div` element.


## Checkbox

Checkboxes let users select one or more options from a list. Use them for
multiple-choice questions, settings, or to confirm actions.

### Default

Create a checkbox with a label using `labelText`.

By default, the checkbox is unchecked.

```svelte
<script>
  import { Checkbox } from "carbon-components-svelte";
</script>

<Checkbox labelText="Label text" />
```

### Checked

Set `checked` to `true` to pre-select the checkbox.

```svelte
<script>
  import { Checkbox } from "carbon-components-svelte";
</script>

<Checkbox labelText="Label text" checked />
```

### Indeterminate

Set `indeterminate` to `true` to show a mixed state, typically used in parent
checkboxes with some children selected.

```svelte
<script>
  import { Checkbox } from "carbon-components-svelte";
</script>

<Checkbox labelText="Label text" indeterminate />
```

### Hidden label

Set `hideLabel` to `true` to visually hide the label while keeping it accessible
to screen readers.

```svelte
<script>
  import { Checkbox } from "carbon-components-svelte";
</script>

<Checkbox labelText="Label text" hideLabel />
```

### Helper text

Use `helperText` to provide additional context or instructions below the
checkbox.

```svelte
<script>
  import { Checkbox } from "carbon-components-svelte";
</script>

<Checkbox
  labelText="Subscribe to newsletter"
  helperText="You can unsubscribe at any time"
/>
```

### Disabled state

Set `disabled` to `true` to prevent user interaction.

```svelte
<script>
  import { Checkbox } from "carbon-components-svelte";
</script>

<Checkbox labelText="Label text" disabled />
```

### Read-only state

Set `readonly` to `true` to make the checkbox non-interactive while keeping the
label text readable. Unlike `disabled`, the readonly state is intended for
displaying checkbox values that can only be changed programmatically.

```svelte
<script>
  import { Checkbox } from "carbon-components-svelte";
</script>

<Checkbox labelText="Label text (unchecked)" readonly />
<Checkbox labelText="Label text (checked)" checked readonly />
```

### Reactive example (bind:checked)

Use two-way binding with `bind:checked` to track the checkbox state.

```svelte
<script>
  import { Button, Checkbox, Stack } from "carbon-components-svelte";

  let checked = false;
</script>

<Stack inline gap={4}>
  <Checkbox labelText="Label text" bind:checked />
  <Button on:click={() => (checked = !checked)}>Toggle</Button>
  <div>
    <strong>checked:</strong>
    {checked}
  </div>
</Stack>
```

### Reactive example (bind:group)

Bind an array to `group` so each checkbox adds or removes its `value` when
toggled. This API is inspired by Svelte
[group inputs](https://svelte.dev/tutorial/svelte/group-inputs).

When using `bind:group`, the checked state is derived from the group array: use
`bind:group` (not `bind:checked`) to control selection, since updating `checked`
directly will be overwritten.

```svelte
<script>
  import { Button, Checkbox, Stack } from "carbon-components-svelte";

  let values = ["Apple", "Banana", "Coconut"];
  let group = values.slice(0, 2);
</script>

<Stack inline gap={4}>
  <div>
    {#each values as value}
      <Checkbox bind:group labelText={value} {value} />
    {/each}
  </div>

  <Button on:click={() => (group = ["Banana"])}>Set to ["Banana"]</Button>

  <div>
    <strong>Selected:</strong>
    {JSON.stringify(group)}
  </div>
</Stack>
```

### Skeleton

Set `skeleton` to `true` to show a loading state.

```svelte
<script>
  import { Checkbox } from "carbon-components-svelte";
</script>

<Checkbox skeleton />
```

### CheckboxGroup

Use a checkbox group to wrap multiple checkbox components with a shared legend,
layout, and validation. This mirrors the
[RadioButtonGroup](/components/RadioButton) API but supports multiple
selections.

```svelte
<script>
  import { Checkbox, CheckboxGroup } from "carbon-components-svelte";
</script>

<CheckboxGroup
  legendText="Notification preferences"
  name="prefs"
  selected={["email"]}
>
  <Checkbox value="email" labelText="Email" />
  <Checkbox value="sms" labelText="SMS" />
  <Checkbox value="push" labelText="Push notifications" />
</CheckboxGroup>
```

### CheckboxGroup (reactive example)

Use two-way binding with `bind:selected` to track and update the selected
values.

```svelte
<script>
  import {
    Button,
    Checkbox,
    CheckboxGroup,
    Stack,
  } from "carbon-components-svelte";

  let selected = ["email"];
</script>

<Stack inline gap={4}>
  <CheckboxGroup
    legendText="Notification preferences"
    name="prefs"
    bind:selected
  >
    <Checkbox value="email" labelText="Email" />
    <Checkbox value="sms" labelText="SMS" />
    <Checkbox value="push" labelText="Push notifications" />
  </CheckboxGroup>

  <Button on:click={() => (selected = ["email", "push"])}>
    Select Email + Push
  </Button>

  <div>
    <strong>selected:</strong>
    {JSON.stringify(selected)}
  </div>
</Stack>
```

### CheckboxGroup (hidden legend)

Visually hide the legend while maintaining accessibility.

```svelte
<script>
  import { Checkbox, CheckboxGroup } from "carbon-components-svelte";
</script>

<CheckboxGroup
  hideLegend
  legendText="Notification preferences"
  name="prefs-hidden"
  selected={["email"]}
>
  <Checkbox value="email" labelText="Email" />
  <Checkbox value="sms" labelText="SMS" />
  <Checkbox value="push" labelText="Push notifications" />
</CheckboxGroup>
```

### CheckboxGroup (custom label content)

Use the `legendChildren` slot to provide custom label content instead of using
the `legendText` prop.

```svelte
<script>
  import {
    Checkbox,
    CheckboxGroup,
    Stack,
    Tooltip,
  } from "carbon-components-svelte";
</script>

<CheckboxGroup name="prefs-legend-slot" selected={["email"]}>
  <Stack slot="legendChildren" orientation="horizontal">
    Notification preferences
    <Tooltip>
      <p>You can change these settings at any time.</p>
    </Tooltip>
  </Stack>
  <Checkbox value="email" labelText="Email" />
  <Checkbox value="sms" labelText="SMS" />
  <Checkbox value="push" labelText="Push notifications" />
</CheckboxGroup>
```

### CheckboxGroup (helper text)

Use `helperText` to provide additional context below the checkbox group.

```svelte
<script>
  import { Checkbox, CheckboxGroup } from "carbon-components-svelte";
</script>

<CheckboxGroup
  legendText="Notification preferences"
  name="prefs-helper"
  selected={["email"]}
  helperText="You can change these settings at any time"
>
  <Checkbox value="email" labelText="Email" />
  <Checkbox value="sms" labelText="SMS" />
  <Checkbox value="push" labelText="Push notifications" />
</CheckboxGroup>
```

### CheckboxGroup (disabled)

Disable all checkboxes in the group.

```svelte
<script>
  import { Checkbox, CheckboxGroup } from "carbon-components-svelte";
</script>

<CheckboxGroup
  disabled
  legendText="Notification preferences"
  name="prefs-disabled"
  selected={["email"]}
>
  <Checkbox value="email" labelText="Email" />
  <Checkbox value="sms" labelText="SMS" />
  <Checkbox value="push" labelText="Push notifications" />
</CheckboxGroup>
```

### CheckboxGroup (read-only)

Set `readonly` on each checkbox to display selected values without allowing user
interaction. Unlike `disabled`, the readonly state keeps labels readable.

```svelte
<script>
  import { Checkbox, CheckboxGroup } from "carbon-components-svelte";
</script>

<CheckboxGroup
  legendText="Notification preferences"
  name="prefs-readonly"
  selected={["email", "push"]}
>
  <Checkbox value="email" labelText="Email" readonly />
  <Checkbox value="sms" labelText="SMS" readonly />
  <Checkbox value="push" labelText="Push notifications" readonly />
</CheckboxGroup>
```

---

### Component API

#### `Checkbox` props

| Prop                       | Type                       | Description                                        | Default                             |
| -------------------------- | -------------------------- | -------------------------------------------------- | ----------------------------------- |
| `checked` (Reactive)       | `boolean`                  | Specify whether the checkbox is checked            | `false`                             |
| `group` (Reactive)         | `ReadonlyArray<any>`       | Specify the bound group.                           | _undefined_                         |
| `indeterminate` (Reactive) | `boolean`                  | Specify whether the checkbox is indeterminate      | `false`                             |
| `title` (Reactive)         | `string`                   | Specify the title attribute for the label element. | _undefined_                         |
| `ref` (Reactive)           | `null \| HTMLInputElement` | Obtain a reference to the input HTML element       | `null`                              |
| `value`                    | `any`                      | Specify the value of the checkbox.                 | `""`                                |
| `skeleton`                 | `boolean`                  | Set to `true` to display the skeleton state        | `false`                             |
| `required`                 | `boolean`                  | Set to `true` to mark the field as required        | `false`                             |
| `readonly`                 | `boolean`                  | Set to `true` for the checkbox to be read-only     | `false`                             |
| `disabled`                 | `boolean`                  | Set to `true` to disable the checkbox              | `false`                             |
| `labelText`                | `string`                   | Specify the label text                             | `""`                                |
| `hideLabel`                | `boolean`                  | Set to `true` to visually hide the label text      | `false`                             |
| `helperText`               | `string`                   | Specify the helper text                            | `""`                                |
| `name`                     | `string`                   | Set a name for the input element                   | `""`                                |
| `id`                       | `string`                   | Set an id for the input label                      | `ccs-${Math.random().toString(36)}` |

#### `Checkbox` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `labelChildren` | `Record<string, never>` |

#### `Checkbox` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:change`     |
| `on:focus`      |
| `on:blur`       |

#### `Checkbox` dispatched events

| Event      | Detail    |
| ---------- | --------- |
| `on:check` | `boolean` |

#### `Checkbox` $$restProps

`Checkbox` spreads `$$restProps` to the `div` element.


## ClickableTile

Clickable tiles create interactive content areas that link to other pages or
trigger actions. Use them to group related content and provide clear navigation
targets.

### Default

Create a clickable tile with an `href` to link to another page.

```svelte
<script>
  import { ClickableTile } from "carbon-components-svelte";
</script>

<ClickableTile href="https://www.carbondesignsystem.com/">
  Carbon Design System
</ClickableTile>
```

### Prevent default behavior

Handle the `click` event to override the default link behavior. Use
`e.preventDefault()` to stop navigation.

```svelte
<script>
  import { ClickableTile } from "carbon-components-svelte";
</script>

<ClickableTile
  href="/"
  on:click={(e) => {
    e.preventDefault();
    // custom behavior
  }}
>
  Carbon Design System
</ClickableTile>
```

### Light variant

Set `light` to `true` to use the light color scheme.

```svelte
<script>
  import { ClickableTile } from "carbon-components-svelte";
</script>

<ClickableTile light href="https://www.carbondesignsystem.com/">
  Carbon Design System
</ClickableTile>
```

### Disabled state

Set `disabled` to `true` to prevent interaction.

```svelte
<script>
  import { ClickableTile } from "carbon-components-svelte";
</script>

<ClickableTile disabled href="https://www.carbondesignsystem.com/">
  Carbon Design System
</ClickableTile>
```

---

### Component API

#### `ClickableTile` props

| Prop                 | Type      | Description                               | Default     |
| -------------------- | --------- | ----------------------------------------- | ----------- |
| `clicked` (Reactive) | `boolean` | Set to `true` to click the tile           | `false`     |
| `light`              | `boolean` | Set to `true` to enable the light variant | `false`     |
| `disabled`           | `boolean` | Set to `true` to disable the tile         | `false`     |
| `href`               | `string`  | Set the `href`.                           | _undefined_ |

#### `ClickableTile` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ClickableTile` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:keydown`    |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `ClickableTile` $$restProps

`ClickableTile` spreads `$$restProps` to the `a | p` element.


## CodeSnippet

Code snippets display and copy code examples. They support single-line,
multi-line, and inline formats with customizable copy and expand functionality.

This component uses the native, asynchronous
[Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText)
to copy text.

You can override the default copy functionality with your own implementation.
See [Overriding copy functionality](#overriding-copy-functionality).

### Default

Display a single-line code snippet by default.

```svelte
<script>
  import { CodeSnippet } from "carbon-components-svelte";
</script>

<CodeSnippet code="npm i carbon-components-svelte" />
```

### Overriding copy functionality

Pass a custom function to the `copy` prop to override the default copy behavior.

In this example, we use the open source module
[clipboard-copy](https://github.com/feross/clipboard-copy) to copy the text
instead of the default Clipboard API.

```svelte
<script>
  import { CodeSnippet } from "carbon-components-svelte";
  import copy from "clipboard-copy";
</script>

<CodeSnippet
  code="npm i carbon-components-svelte"
  copy={(text) => copy(text)}
/>
```

### Preventing copy functionality

Pass a no-op function to the `copy` prop to disable copying.

```svelte
<script>
  import { CodeSnippet } from "carbon-components-svelte";
</script>

<CodeSnippet code="npm i carbon-components-svelte" copy={() => {}} />
```

### Inline

Set `type="inline"` to display code inline with text.

```svelte
<script>
  import { CodeSnippet } from "carbon-components-svelte";
</script>

<CodeSnippet type="inline" code="rm -rf node_modules/" />
```

### Multi-line

Set `type="multi"` to display multiple lines of code with expand/collapse
functionality.

```svelte
<script>
  import { CodeSnippet } from "carbon-components-svelte";

  let code =
    "export function multiply(a: number, b: number) {\n  return a * b;\n}\n\nexport function divide(a: number, b: number) {\n  return a / b;\n}\n\nexport function add(a: number, b: number) {\n  return a + b;\n}\n\nexport function subtract(a: number, b: number) {\n  return a - b;\n}";
</script>

<CodeSnippet type="multi" {code} />
```

### Expanded by default

Set `expanded` to `true` to show the full multi-line code snippet.

```svelte
<script>
  import { CodeSnippet } from "carbon-components-svelte";

  let code =
    "export function multiply(a: number, b: number) {\n  return a * b;\n}\n\nexport function divide(a: number, b: number) {\n  return a / b;\n}\n\nexport function add(a: number, b: number) {\n  return a + b;\n}\n\nexport function subtract(a: number, b: number) {\n  return a - b;\n}";
</script>

<CodeSnippet type="multi" {code} expanded />
```

### Reactive example

The multi-line code snippet dispatches "expand" and "collapse" events.

```svelte
<script>
  import { Button, CodeSnippet } from "carbon-components-svelte";

  let expanded = false;
</script>

<Button on:click={() => (expanded = !expanded)}>Toggle expansion</Button>

<CodeSnippet
  type="multi"
  code={Array.from({ length: 30 }, (_, i) => i + 1).join("\n")}
  bind:expanded
  on:expand={() => {
    console.log("on:expand");
  }}
  on:collapse={() => {
    console.log("on:collapse");
  }}
/>
```

### Custom copy feedback text

Set `feedback` to customize the copy button feedback text.

```svelte
<script>
  import { CodeSnippet } from "carbon-components-svelte";

  let code =
    "export function multiply(a: number, b: number) {\n  return a * b;\n}\n\nexport function divide(a: number, b: number) {\n  return a / b;\n}\n\nexport function add(a: number, b: number) {\n  return a + b;\n}\n\nexport function subtract(a: number, b: number) {\n  return a - b;\n}";
</script>

<CodeSnippet type="multi" {code} feedback="Copied to clipboard" />
```

### Hidden copy button

Set `hideCopyButton` to `true` to hide the copy button.

```svelte
<script>
  import { CodeSnippet } from "carbon-components-svelte";

  let code =
    "export function multiply(a: number, b: number) {\n  return a * b;\n}\n\nexport function divide(a: number, b: number) {\n  return a / b;\n}\n\nexport function add(a: number, b: number) {\n  return a + b;\n}\n\nexport function subtract(a: number, b: number) {\n  return a - b;\n}";
</script>

<CodeSnippet type="multi" {code} hideCopyButton />
```

### Hidden show more button

Set `showMoreLess` to `false` to hide the expand/collapse button on multi-line
snippets.

```svelte
<script>
  import { CodeSnippet } from "carbon-components-svelte";

  let code =
    "export function multiply(a: number, b: number) {\n  return a * b;\n}\n\nexport function divide(a: number, b: number) {\n  return a / b;\n}\n\nexport function add(a: number, b: number) {\n  return a + b;\n}\n\nexport function subtract(a: number, b: number) {\n  return a - b;\n}";
</script>

<CodeSnippet type="multi" {code} showMoreLess={false} />
```

### Hidden copy, show more buttons

Hide both the copy and expand/collapse buttons.

```svelte
<script>
  import { CodeSnippet } from "carbon-components-svelte";

  let code =
    "export function multiply(a: number, b: number) {\n  return a * b;\n}\n\nexport function divide(a: number, b: number) {\n  return a / b;\n}\n\nexport function add(a: number, b: number) {\n  return a + b;\n}\n\nexport function subtract(a: number, b: number) {\n  return a - b;\n}";
</script>

<CodeSnippet type="multi" {code} hideCopyButton showMoreLess={false} />
```

### Custom show more/less text

Set `showMoreText` and `showLessText` to customize the expand/collapse button
text.

```svelte
<script>
  import { CodeSnippet } from "carbon-components-svelte";

  let code =
    "export function multiply(a: number, b: number) {\n  return a * b;\n}\n\nexport function divide(a: number, b: number) {\n  return a / b;\n}\n\nexport function add(a: number, b: number) {\n  return a + b;\n}\n\nexport function subtract(a: number, b: number) {\n  return a - b;\n}";
</script>

<CodeSnippet
  type="multi"
  {code}
  showMoreText="Expand"
  showLessText="Collapse"
/>
```

### Disabled state

Set `disabled` to `true` to disable interaction. This only applies to `"single"`
and `"multi"` types.

```svelte
<script>
  import { CodeSnippet, Stack } from "carbon-components-svelte";

  let comment =
    "> carbon-components-svelte is a Svelte component library that implements the [Carbon Design System](https://github.com/carbon-design-system), an open source design system by IBM.\n\n> A design system can facilitate frontend development and prototyping because it is encourages reuse, consistency, and extensibility.\n";
</script>

<Stack gap={2}>
  <CodeSnippet disabled code="npm i carbon-components-svelte" />
  <CodeSnippet disabled type="multi" code={comment} />
</Stack>
```

### Wrapped text

By default, the code snippet preserves text formatting and does not wrap text.

Set `wrapText` to `true` to wrap long lines in multi-line snippets.

```svelte
<script>
  import { CodeSnippet } from "carbon-components-svelte";

  let comment =
    "> carbon-components-svelte is a Svelte component library that implements the [Carbon Design System](https://github.com/carbon-design-system), an open source design system by IBM.\n\n> A design system can facilitate frontend development and prototyping because it is encourages reuse, consistency, and extensibility.\n";
</script>

<CodeSnippet wrapText type="multi" code={comment} />
```

### Dynamic multi-line code

Use the `code` prop instead of the default slot for dynamically updated code.

```svelte
<script>
  import { CodeSnippet, Toggle } from "carbon-components-svelte";

  let toggled = false;

  $: length = toggled ? 20 : 10;
  $: code = Array.from({ length }, (_, i) => i + 1).join("\n");
</script>

<Toggle
  bind:toggled
  size="sm"
  labelText="Trigger snippet overflow"
  style="margin-bottom: var(--cds-spacing-05)"
/>
<CodeSnippet type="multi" {code} />
```

### Hidden multi-line code

The "Show more" button relies on the element's computed height. For hidden
content, the button won't appear because the height is `0`.

Re-render the component to fix this issue.

```svelte
<script>
  import { CodeSnippet, Toggle } from "carbon-components-svelte";

  let toggled = false;

  const code = Array.from({ length: 20 }, (_, i) => i + 1).join("\n");
</script>

<Toggle
  size="sm"
  style="margin-bottom: var(--cds-spacing-05)"
  labelText="Show code snippets"
  bind:toggled
/>

{#if toggled}
  <h5>"Show more" will not render</h5>
  <br />
{/if}
<div class:hidden={!toggled}>
  <CodeSnippet type="multi" {code} />
</div>

{#if toggled}
  <br /><br />
  <h5>"Show more" will render</h5>
  <br />
  <div class:hidden={!toggled}>
    <CodeSnippet type="multi" {code} />
  </div>
{/if}

<style>
  .hidden {
    display: none;
  }
</style>
```

### Skeleton

Set `skeleton` to `true` to show a loading state. Defaults to `"single"` type.

```svelte
<script>
  import { CodeSnippet } from "carbon-components-svelte";
</script>

<CodeSnippet skeleton />
```

### Skeleton (multi-line)

Set `type="multi"` with `skeleton` to show a multi-line loading state.

```svelte
<script>
  import { CodeSnippet } from "carbon-components-svelte";
</script>

<CodeSnippet type="multi" skeleton />
```

---

### Component API

#### `CodeSnippet` props

| Prop                      | Type                              | Description                                                                                                                                                               | Default                             |
| ------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `expanded` (Reactive)     | `boolean`                         | Set to `true` to expand a multi-line code snippet (type="multi")                                                                                                          | `false`                             |
| `showMoreLess` (Reactive) | `boolean`                         | Set to `false` to hide the show more/less button.<br /><br />NOTE: this prop only works with the `type="multi"` variant.                                                  | `true`                              |
| `ref` (Reactive)          | `null \| HTMLPreElement`          | Obtain a reference to the pre HTML element                                                                                                                                | `null`                              |
| `type`                    | `"single" \| "inline" \| "multi"` | Set the type of code snippet.                                                                                                                                             | `"single"`                          |
| `code`                    | `string`                          | Set the code snippet text.<br />Alternatively, use the default slot.<br /><br />NOTE: you _must_ use the `code` prop for the copy-to-clipboard functionality.             | _undefined_                         |
| `copy`                    | `(code: string) => void`          | By default, this component uses `navigator.clipboard.writeText` API to copy text to the user's clipboard.<br /><br />Provide a custom function to override this behavior. | _undefined_                         |
| `hideCopyButton`          | `boolean`                         | Set to `true` to hide the copy button                                                                                                                                     | `false`                             |
| `disabled`                | `boolean`                         | Set to `true` for the disabled variant.<br />Only applies to the "single", "multi" types.                                                                                 | `false`                             |
| `wrapText`                | `boolean`                         | Set to `true` to wrap the text.<br /><br />NOTE: this prop only works with the `type="multi"` variant.                                                                    | `false`                             |
| `light`                   | `boolean`                         | Set to `true` to enable the light variant                                                                                                                                 | `false`                             |
| `skeleton`                | `boolean`                         | Set to `true` to display the skeleton state                                                                                                                               | `false`                             |
| `copyButtonDescription`   | `string`                          | Specify the ARIA label for the copy button icon.                                                                                                                          | _undefined_                         |
| `copyLabel`               | `string`                          | Specify the ARIA label of the copy button.                                                                                                                                | _undefined_                         |
| `feedback`                | `string`                          | Specify the feedback text displayed when clicking the snippet                                                                                                             | `"Copied!"`                         |
| `feedbackTimeout`         | `number`                          | Set the timeout duration (ms) to display feedback text                                                                                                                    | `2000`                              |
| `showLessText`            | `string`                          | Specify the show less text.<br /><br />NOTE: this prop only works with the `type="multi"` variant.                                                                        | `"Show less"`                       |
| `showMoreText`            | `string`                          | Specify the show more text.<br /><br />NOTE: this prop only works with the `type="multi"` variant.                                                                        | `"Show more"`                       |
| `id`                      | `string`                          | Set an id for the code element                                                                                                                                            | `ccs-${Math.random().toString(36)}` |

#### `CodeSnippet` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `CodeSnippet` forwarded events

| Event             |
| ----------------- |
| `on:click`        |
| `on:mouseover`    |
| `on:mouseenter`   |
| `on:mouseleave`   |
| `on:animationend` |

#### `CodeSnippet` dispatched events

| Event         | Detail |
| ------------- | ------ |
| `on:expand`   | `null` |
| `on:collapse` | `null` |
| `on:copy`     | `null` |

#### `CodeSnippet` $$restProps

`CodeSnippet` spreads `$$restProps` to the `button | span` element.


## ComboBox

Combo boxes combine a text input with a dropdown menu to let users select from
predefined options or enter custom values. They support filtering, custom item
rendering, and various states.

Combo boxes are keyed for performance reasons.

> [!NOTE] Every `items` object must have a unique "id" property.

### Default

Create a combobox with a title and placeholder text. Each item requires a unique
`id` and `text`.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";
</script>

<ComboBox
  labelText="Contact"
  placeholder="Select contact method"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Custom slot

Override the default slot to customize how each item displays. Access the item
and index through the `let:` directive.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";
</script>

<ComboBox
  labelText="Contact"
  placeholder="Select contact method"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
  let:item
  let:index
>
  <div>
    <strong>{item.text}</strong>
  </div>
  <div>
    id: {item.id} - index:
    {index}
  </div>
</ComboBox>

<style>
  :global(.bx--list-box__menu-item, .bx--list-box__menu-item__option) {
    height: auto;
  }
</style>
```

### Hidden label

Set `hideLabel` to `true` to visually hide the label while keeping it accessible
to screen readers.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";
</script>

<ComboBox
  hideLabel
  labelText="Hidden Label"
  placeholder="Select contact method"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Initial selected id

Set `selectedId` to pre-select an item when the combobox loads.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";
</script>

<ComboBox
  labelText="Contact"
  placeholder="Select contact method"
  selectedId="1"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Reactive example

See how the combobox responds to user input and selection changes.

```svelte
<script>
  import { Button, ComboBox } from "carbon-components-svelte";

  let selectedId = "1";
</script>

<ComboBox
  labelText="Contact"
  placeholder="Select contact method"
  bind:selectedId
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
<br />
<Button on:click={() => (selectedId = undefined)}
  >Set to undefined (unselected)</Button
>
<Button on:click={() => (selectedId = "2")}>Set to 2 (Fax)</Button>
```

### Autocomplete with typeahead

Set `typeahead` to `true` to enable autocomplete with typeahead functionality.
As users type, the input automatically suggests and completes matching items.

The typeahead feature uses prefix matching (case-insensitive) to filter items
that start with the entered text. When a match is found, the suggestion is
displayed with the untyped portion highlighted, allowing users to accept it or
continue typing.

Note that when `typeahead` is enabled, the `shouldFilterItem` prop is ignored as
the typeahead functionality provides its own filtering logic.

```svelte
<script>
  import { Button, ComboBox } from "carbon-components-svelte";

  let selectedId = undefined;

  const items = [
    "Apple",
    "Apricot",
    "Avocado",
    "Banana",
    "Blackberry",
    "Blueberry",
    "Cantaloupe",
  ].map((item) => ({ id: item, text: item }));
</script>

<ComboBox
  labelText="Item"
  placeholder="Select an item"
  bind:selectedId
  typeahead
  {items}
/>
<br />
<Button on:click={() => (selectedId = undefined)}>
  Set to undefined (unselected)
</Button>
```

### Clear selection

Use `bind:this` to access the component instance and call `ComboBox.clear()` to
programmatically clear the selection.

Set `focus: false` in the method options to prevent re-focusing the input.

```svelte
<script>
  import { Button, ComboBox } from "carbon-components-svelte";

  let ref;
</script>

<ComboBox
  labelText="Contact"
  placeholder="Select contact method"
  selectedId="1"
  bind:this={ref}
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
<br />
<Button on:click={() => ref.clear()}>Clear</Button>
<Button on:click={() => ref.clear({ focus: false })}>Clear (no focus)</Button>
```

### Multiple combo boxes

See how to manage multiple comboboxes in a form.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";

  const items = [
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ];

  let comboBox1_selectedId = undefined;
  let comboBox2_selectedId = undefined;

  const formatSelected = (id) =>
    items.find((item) => item.id === id)?.text ?? "N/A";

  $: primary = formatSelected(comboBox1_selectedId);
  $: secondary = formatSelected(comboBox2_selectedId);
</script>

<ComboBox
  bind:selectedId={comboBox1_selectedId}
  labelText="Primary contact"
  placeholder="Select primary contact method"
  {items}
/>

<div>Primary: {primary}</div>

<ComboBox
  bind:selectedId={comboBox2_selectedId}
  labelText="Secondary contact"
  placeholder="Select secondary contact method"
  {items}
/>

<div>Secondary: {secondary}</div>

<style>
  div {
    margin: var(--cds-layout-01) 0 var(--cds-layout-03);
  }
</style>
```

### Filterable

Enable filtering to let users search through the options.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";

  function shouldFilterItem(item, value) {
    if (!value) return true;
    return item.text.toLowerCase().includes(value.toLowerCase());
  }
</script>

<ComboBox
  labelText="Contact"
  placeholder="Select contact method"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
  {shouldFilterItem}
/>
```

### Filterable with custom label

Set `itemToString` to customize how items display in the filterable combobox.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";

  const translation = {
    Slack: 'Custom label for "Slack"',
    Email: 'Custom label for "Email"',
    Fax: 'Custom label for "Fax"',
  };

  function itemToString(item) {
    return translation[item.key];
  }

  function shouldFilterItem(item, value) {
    if (!value) return true;
    const comparison = value.toLowerCase();
    return (
      item.key.toLowerCase().includes(comparison) ||
      itemToString(item).toLowerCase().includes(comparison)
    );
  }
</script>

<ComboBox
  labelText="Contact"
  placeholder="Select contact method"
  items={[
    { id: "0", key: "Slack" },
    { id: "1", key: "Email" },
    { id: "2", key: "Fax" },
  ]}
  {shouldFilterItem}
  {itemToString}
/>
```

### Clear filter on open

When using a filterable combobox, reopening the dropdown after making a
selection will normally show only the filtered results matching the selected
item. Set `clearFilterOnOpen` to `true` to temporarily clear the filter when
opening, showing all available items. This makes it easier to browse and change
selections.

The original value is automatically restored if you close the dropdown without
making a new selection.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";

  function shouldFilterItem(item, value) {
    if (!value) return true;
    return item.text.toLowerCase().includes(value.toLowerCase());
  }
</script>

<ComboBox
  labelText="Contact"
  placeholder="Select contact method"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
  {shouldFilterItem}
  clearFilterOnOpen
  selectedId="1"
  helperText="Select an item, then reopen to see all items again"
/>
```

### Filtering (async)

By default, combobox filtering is synchronous and client-side.

For async (e.g., server-side) filtering, bind to `value` and update `items` when
input changes. This example simulates async/await behavior with a debounced
input value change.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";
  import { onMount } from "svelte";

  let items = [];
  let timeoutId;
  let inputValue = "";

  // Simulate fetching data from a remote server.
  async function fetchItems(query) {
    if (!query) {
      return [];
    }

    await new Promise((resolve) => setTimeout(resolve, 300));

    const allItems = [
      { id: "0", text: "Slack" },
      { id: "1", text: "Email" },
      { id: "2", text: "Fax" },
      { id: "3", text: "Phone" },
      { id: "4", text: "SMS" },
      { id: "5", text: "WhatsApp" },
      { id: "6", text: "Teams" },
      { id: "7", text: "Discord" },
      { id: "8", text: "Zoom" },
      { id: "9", text: "Skype" },
    ];

    return allItems.filter((item) =>
      item.text.toLowerCase().includes(query.toLowerCase())
    );
  }

  onMount(() => {
    // Fetch initial items.
    fetchItems("")
      .then((data) => {
        items = data;
      })
      .catch(() => {});

    return () => {
      clearTimeout(timeoutId);
    };
  });

  $: {
    clearTimeout(timeoutId);
    timeoutId = setTimeout(async () => {
      items = await fetchItems(inputValue);
      // Debounce input value changes.
    }, 150);
  }
</script>

<ComboBox
  labelText="Contact"
  placeholder="Type to search..."
  bind:value={inputValue}
  {items}
/>
```

### Allow custom value

Set `allowCustomValue` to `true` to let users enter custom text that isn't in
the predefined list. By default, user-entered text is cleared when the combobox
loses focus without selecting an item. When `allowCustomValue` is enabled,
custom text is preserved.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";

  let selectedId = undefined;
  let value = "";
</script>

<ComboBox
  allowCustomValue
  labelText="Favorite fruit"
  placeholder="Select or enter a fruit"
  helperText="You can select from the list or type your own"
  bind:selectedId
  bind:value
  items={[
    { id: "0", text: "Apple" },
    { id: "1", text: "Banana" },
    { id: "2", text: "Orange" },
    { id: "3", text: "Strawberry" },
  ]}
  shouldFilterItem={(item, value) => {
    if (!value) return true;
    return item.text.toLowerCase().includes(value.toLowerCase());
  }}
  on:select={(e) => {
    console.log("Selected item:", e.detail);
  }}
/>

<div style:margin-top="var(--cds-layout-01)">
  <div><strong>Selected ID:</strong> {selectedId ?? "none"}</div>
  <div><strong>Current value:</strong> {value || "empty"}</div>
</div>
```

### Top direction

Set `direction` to `"top"` to make the dropdown menu appear above the input.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";
</script>

<ComboBox
  direction="top"
  labelText="Contact"
  placeholder="Select contact method"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Light variant

Set `light` to `true` to use the light color scheme.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";
</script>

<ComboBox
  light
  labelText="Contact"
  placeholder="Select contact method"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Portal menu

Set `portalMenu` to `true` to render the dropdown menu in a floating portal.
This prevents the menu from being clipped by parent containers with
`overflow: hidden` or z-index stacking contexts. The example below shows a
container with hidden overflow. Without `portalMenu`, the dropdown would be
clipped.

When inside a [Modal](/components/Modal#modal-with-dropdowns), `portalMenu`
defaults to `true` unless explicitly set to `false`.

```svelte
<script>
  import { ComboBox, Stack } from "carbon-components-svelte";
</script>

<Stack
  gap={4}
  style="overflow: hidden; border: 1px dashed var(--cds-border-subtle); padding: 1rem; max-height: 120px;"
>
  <div>
    This container has hidden overflow. Without <code>portalMenu</code>, the
    dropdown would be clipped.
  </div>
  <ComboBox
    portalMenu
    light
    labelText="Contact method"
    placeholder="Select contact method"
    items={[
      { id: "0", text: "Slack" },
      { id: "1", text: "Email" },
      { id: "2", text: "Fax" },
    ]}
  />
</Stack>
```

### Extra-large size

Set `size` to `"xl"` for an extra-large combobox.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";
</script>

<ComboBox
  labelText="Contact"
  placeholder="Select contact method"
  size="xl"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Small size

Set `size` to `"sm"` for a small combobox.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";
</script>

<ComboBox
  labelText="Contact"
  placeholder="Select contact method"
  size="sm"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Invalid state

Set `invalid` to `true` and provide `invalidText` to show an error message.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";
</script>

<ComboBox
  invalid
  invalidText="Secondary contact method must be different from the primary contact"
  labelText="Contact"
  placeholder="Select contact method"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Warning state

Set `warn` to `true` and provide `warnText` to show a warning message.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";
</script>

<ComboBox
  warn
  warnText="This contact method is not associated with your account"
  labelText="Contact"
  placeholder="Select contact method"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Disabled state

Set `disabled` to `true` to prevent interaction with the combobox.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";
</script>

<ComboBox
  disabled
  labelText="Contact"
  placeholder="Select contact method"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Disabled items

Set `disabled: true` in an item object to disable specific options.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";
</script>

<ComboBox
  labelText="Contact"
  placeholder="Select contact method"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email", disabled: true },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Virtualized items (large lists)

Virtualization is a technique that allows only the items currently visible in
the viewport to be rendered in the DOM, improving performance for large lists.

By default, the combo box will virtualize lists with more than 100 items.

In the example below, 10,000 items are provided to the combobox but only 11
items (8 visible items + 3 overscan items) are rendered in the DOM.

Set `virtualize={false}` to explicitly disable virtualization, even for large
lists. Or, customize the threshold at which virtualization activates. See
[Virtualized items (custom threshold)](#virtualized-items-custom-threshold).

```svelte
<script>
  import { ComboBox, Stack } from "carbon-components-svelte";

  const items = Array.from({ length: 10_000 }, (_, i) => ({
    id: i,
    text: `Item ${i + 1}`,
  }));

  let value = "";
  let selectedId = undefined;
  $: selectedItem = items.find((item) => item.id === selectedId);
</script>

<Stack gap={5}>
  <ComboBox
    labelText="Virtualized ComboBox (10,000 items)"
    placeholder="Filter..."
    {items}
    shouldFilterItem={(item, value) =>
      item.text.toLowerCase().includes(value.toLowerCase())}
    bind:selectedId
    bind:value
  />
  <div>
    <strong>Selected:</strong>
    {selectedItem?.text}
  </div>
</Stack>
```

### Virtualized items (custom overscan)

Overscanning is the process of rendering extra items above and below the
viewport to ensure smooth scrolling. The default overscan value is 3.

Specify a custom value for `overscan` to control how many extra items are
rendered above/below the viewport for smoother scrolling.

> [!NOTE] During very fast scrolling, higher overscan values may cause more
> flickering due to increased DOM updates. For fast scrolling scenarios, use a
> lower overscan value.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";

  const items = Array.from({ length: 10_000 }, (_, i) => ({
    id: i,
    text: `Item ${i + 1}`,
  }));

  let value = "";
  let selectedId = undefined;
</script>

<ComboBox
  virtualize={{ overscan: 100 }}
  labelText="High overscan (10,000 items, overscan: 100)"
  placeholder="Filter..."
  {items}
  shouldFilterItem={(item, value) =>
    item.text.toLowerCase().includes(value.toLowerCase())}
  bind:selectedId
  bind:value
/>
```

### Virtualized items (custom threshold)

The threshold is the minimum number of items required before virtualization
activates. The default threshold value is 100, meaning lists with fewer than 100
items will not be virtualized and all items will be rendered normally.

Specify a custom value for `threshold` to control when virtualization activates.
Below the threshold, all items are rendered normally without virtualization.

```svelte
<script>
  import { ComboBox } from "carbon-components-svelte";

  const items = Array.from({ length: 100 }, (_, i) => ({
    id: i,
    text: `Item ${i + 1}`,
  }));

  let value = "";
  let selectedId = undefined;
</script>

<ComboBox
  virtualize={{ threshold: 200 }}
  labelText="Custom threshold (threshold: 200)"
  placeholder="Filter..."
  {items}
  shouldFilterItem={(item, value) =>
    item.text.toLowerCase().includes(value.toLowerCase())}
  bind:selectedId
  bind:value
/>
```

### Virtualized items (custom item height)

The default item height for virtualization is 40 pixels. When using custom slots
to render items with different heights (e.g., multi-line items with
descriptions), specify a custom `itemHeight` value to match your item's actual
height.

```svelte
<script>
  import { ComboBox, Stack } from "carbon-components-svelte";

  const items = Array.from({ length: 10_000 }, (_, i) => ({
    id: i,
    text: `Item ${i + 1}`,
    description: `Description for item ${i + 1}`,
  }));

  let value = "";
  let selectedId = undefined;
</script>

<ComboBox
  virtualize={{ itemHeight: 60 }}
  labelText="Custom item height (60px)"
  placeholder="Filter..."
  {items}
  shouldFilterItem={(item, value) =>
    item.text.toLowerCase().includes(value.toLowerCase())}
  bind:selectedId
  bind:value
  let:item
>
  <Stack gap={2}>
    <strong>{item.text}</strong>
    <span>{item.description}</span>
  </Stack>
</ComboBox>
```

---

### Component API

#### `ComboBox` props

| Prop                       | Type                                                                                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Default                             |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `selectedId` (Reactive)    | `Item["id"]`                                                                                                                          | Set the selected item by value id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | _undefined_                         |
| `value` (Reactive)         | `string`                                                                                                                              | Specify the selected combobox value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `""`                                |
| `open` (Reactive)          | `boolean`                                                                                                                             | Set to `true` to open the combobox menu dropdown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `false`                             |
| `ref` (Reactive)           | `null \| HTMLInputElement`                                                                                                            | Obtain a reference to the input HTML element                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `null`                              |
| `listRef` (Reactive)       | `null \| HTMLDivElement`                                                                                                              | Obtain a reference to the list HTML element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `null`                              |
| `items`                    | `ReadonlyArray<Item>`                                                                                                                 | Set the combobox items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `[]`                                |
| `itemToString`             | `(item: Item) => string`                                                                                                              | Override the display of a combobox item.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | _undefined_                         |
| `direction`                | `"bottom" \| "top"`                                                                                                                   | Specify the direction of the combobox dropdown menu.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `"bottom"`                          |
| `size`                     | `"sm" \| "xl"`                                                                                                                        | Set the size of the combobox.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | _undefined_                         |
| `disabled`                 | `boolean`                                                                                                                             | Set to `true` to disable the combobox                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `false`                             |
| `labelText`                | `string`                                                                                                                              | Specify the title text of the combobox                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `""`                                |
| `hideLabel`                | `boolean`                                                                                                                             | Set to `true` to visually hide the label text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `false`                             |
| `placeholder`              | `string`                                                                                                                              | Specify the placeholder text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `""`                                |
| `helperText`               | `string`                                                                                                                              | Specify the helper text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `""`                                |
| `invalidText`              | `string`                                                                                                                              | Specify the invalid state text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `""`                                |
| `invalid`                  | `boolean`                                                                                                                             | Set to `true` to indicate an invalid state                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `false`                             |
| `warn`                     | `boolean`                                                                                                                             | Set to `true` to indicate a warning state                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                             |
| `warnText`                 | `string`                                                                                                                              | Specify the warning state text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `""`                                |
| `light`                    | `boolean`                                                                                                                             | Set to `true` to enable the light variant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                             |
| `allowCustomValue`         | `boolean`                                                                                                                             | Set to `true` to allow custom values that are not in the items list.<br />By default, user-entered text is cleared when the combobox loses focus without selecting an item.<br />When enabled, custom text is preserved.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `false`                             |
| `clearFilterOnOpen`        | `boolean`                                                                                                                             | Set to `true` to clear the input value when opening the dropdown.<br />This allows users to see all available items instead of only filtered results.<br />The original value is restored if the dropdown is closed without making a selection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `false`                             |
| `typeahead`                | `boolean`                                                                                                                             | Set to `true` to enable autocomplete with typeahead                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                             |
| `shouldFilterItem`         | `(item: Item, value: string) => boolean`                                                                                              | Determine if an item should be filtered given the current combobox value.<br />Will be ignored if `typeahead` is enabled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | _undefined_                         |
| `translateWithId`          | `(id: import("../ListBox/ListBoxMenuIcon.svelte").ListBoxMenuIconTranslationId) => string`                                            | Override the chevron icon label based on the open state.<br />Defaults to "Open menu" when closed and "Close menu" when open.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | _undefined_                         |
| `translateWithIdSelection` | `(id: "clearSelection") => string`                                                                                                    | Override the label of the clear button when the input has a selection.<br />Defaults to "Clear selected item" since a combo box can only have one selection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | _undefined_                         |
| `id`                       | `string`                                                                                                                              | Set an id for the list box component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `ccs-${Math.random().toString(36)}` |
| `name`                     | `string`                                                                                                                              | Specify a name attribute for the input.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | _undefined_                         |
| `virtualize`               | `undefined \| boolean \| { itemHeight?: number, containerHeight?: number, overscan?: number, threshold?: number, maxItems?: number }` | Enable virtualization for large lists. Virtualization renders only the items currently visible in the viewport, improving performance for large lists.<br /><br />By default, virtualization is automatically enabled for lists with more than 100 items.<br /><br />Set `virtualize={false}` to explicitly disable virtualization, even for large lists.<br /><br />Set `virtualize={true}` to explicitly enable virtualization with default settings.<br /><br />Provide an object to customize virtualization behavior:<br />- `itemHeight` (default: 40): The height in pixels of each item. Specify a custom value when using custom slots with multi-line items or different heights.<br />- `containerHeight` (default: 300): The maximum height in pixels of the dropdown container.<br />- `overscan` (default: 3): The number of extra items to render above and below the viewport for smoother scrolling. Higher values may cause more flickering during very fast scrolling.<br />- `threshold` (default: 100): The minimum number of items required before virtualization activates. Lists with fewer items will render all items normally without virtualization.<br />- `maxItems` (default: undefined): The maximum number of items to render. When undefined, all visible items are rendered. | _undefined_                         |
| `portalMenu`               | `boolean \| undefined`                                                                                                                | Set to `true` to render the dropdown menu in a portal,<br />allowing it to escape containers with `overflow: hidden`.<br />When inside a Modal, defaults to `true` unless explicitly set to `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | _undefined_                         |
| `clear`                    | `(options?: { focus?: boolean; }) => Promise<void>`                                                                                   | Clear the combo box programmatically.<br />By default, focuses the combo box after clearing. Set `options.focus` to `false` to prevent focusing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | _undefined_                         |

#### `ComboBox` typedefs

```ts
type ComboBoxItem<Id = any> = {
  id: Id;
  text: string;
  /** Whether the item is disabled */
  disabled?: boolean;
};
```

#### `ComboBox` slots

| Slot            | Detail                                            |
| --------------- | ------------------------------------------------- |
| `default`       | `{<br /> item: Item;<br /> index: number;<br />}` |
| `labelChildren` | `Record<string, never>`                           |

#### `ComboBox` forwarded events

| Event        |
| ------------ |
| `on:clear`   |
| `on:input`   |
| `on:keydown` |
| `on:keyup`   |
| `on:focus`   |
| `on:blur`    |
| `on:paste`   |
| `on:scroll`  |

#### `ComboBox` dispatched events

| Event       | Detail                                                             |
| ----------- | ------------------------------------------------------------------ |
| `on:select` | `{<br /> selectedId: Item["id"];<br /> selectedItem: Item;<br />}` |

#### `ComboBox` $$restProps

`ComboBox` spreads `$$restProps` to the `input` element.


## ComposedModal

Composed modals let you build custom modals by combining modal header, modal
body, and modal footer components. Use them to create focused interactions that
require user attention or input.

**ComposedModal vs Modal**

The composed modal provides a composition-based approach with modal header,
modal body, and modal footer sub-components for maximum flexibility. For simpler
use cases, use [Modal](/components/Modal) instead. Both components share the
same events, accessibility features, and
[focus behavior](/components/Modal#focus-behavior).

### Composed modal

Create a modal with a header, body, and footer. Each section can be customized
independently.

```svelte
<script>
  import {
    Checkbox,
    ComposedModal,
    ModalBody,
    ModalFooter,
    ModalHeader,
  } from "carbon-components-svelte";

  let checked = false;
</script>

<ComposedModal open>
  <ModalHeader label="Changes" title="Confirm changes" />
  <ModalBody hasForm>
    <Checkbox labelText="I have reviewed the changes" bind:checked />
  </ModalBody>
  <ModalFooter primaryButtonText="Proceed" primaryButtonDisabled={!checked} />
</ComposedModal>
```

### With Portal

Wrap the composed modal in a portal to ensure it renders above all z-index
stacking contexts and parent overflow constraints, preventing visual clipping
and layering issues.

```svelte
<script>
  import {
    Button,
    ComposedModal,
    ModalBody,
    ModalFooter,
    ModalHeader,
    Portal,
    Stack,
  } from "carbon-components-svelte";

  let open = false;
</script>

<Stack gap={5} style="overflow: hidden; position: relative; height: 200px;">
  <p>
    This container hides overflowing content. Without a portal, the modal would
    be clipped.
  </p>
  <div>
    <Button on:click={() => (open = true)}>Open modal</Button>
  </div>
  <Portal>
    <ComposedModal bind:open>
      <ModalHeader title="Composed Modal in Portal" />
      <ModalBody>
        <p>
          This composed modal is rendered in a portal, ensuring it appears above
          all z-index stacking contexts and parent overflow constraints.
        </p>
      </ModalBody>
      <ModalFooter
        primaryButtonText="Confirm"
        secondaryButtonText="Cancel"
        on:click:button--secondary={() => (open = false)}
      />
    </ComposedModal>
  </Portal>
</Stack>
```

### Prevent default close behavior

The modal dispatches a cancelable `close` event, allowing you to prevent the
modal from closing using `e.preventDefault()`. The event includes a `trigger`
property indicating what triggered the close attempt: `"escape-key"`,
`"outside-click"`, or `"close-button"`.

```svelte
<script>
  import {
    Button,
    ComposedModal,
    InlineNotification,
    ModalBody,
    ModalFooter,
    ModalHeader,
  } from "carbon-components-svelte";

  let open = false;
  let hasUnsavedChanges = true;
  let showWarning = false;
</script>

<Button
  on:click={() => {
    open = true;
    hasUnsavedChanges = true;
    showWarning = false;
  }}>Open modal with unsaved changes</Button
>

<ComposedModal
  bind:open
  on:close={(e) => {
    console.log("Close triggered by:", e.detail.trigger);
    if (hasUnsavedChanges) {
      e.preventDefault();
      showWarning = true;
    }
  }}
  on:submit={() => {
    hasUnsavedChanges = false;
    open = false;
  }}
>
  <ModalHeader title="Edit profile" />
  <ModalBody>
    {#if showWarning}
      <InlineNotification
        kind="warning"
        title="Unsaved changes"
        subtitle="Please save or discard your changes before closing."
        hideCloseButton
      />
    {/if}
    <p>You have unsaved changes. Click "Save" to apply them.</p>
  </ModalBody>
  <ModalFooter
    primaryButtonText="Save"
    secondaryButtonText="Discard changes"
    on:click:button--secondary={async () => {
      hasUnsavedChanges = false;
      showWarning = false;
      open = false;
    }}
  />
</ComposedModal>
```

### Danger modal

Display critical actions or destructive operations with the danger variant. Set
`danger` on both `ComposedModal` and `ModalFooter` for the red danger styling.

By default, the cancel button receives focus instead of the critical button to
prevent accidental destructive actions.

```svelte
<script>
  import {
    Button,
    ComposedModal,
    ModalBody,
    ModalFooter,
    ModalHeader,
  } from "carbon-components-svelte";

  let open = false;
</script>

<Button kind="danger" on:click={() => (open = true)}>Delete all</Button>

<ComposedModal danger bind:open on:open on:close>
  <ModalHeader title="Delete all instances" />
  <ModalBody>
    <p>This is a permanent action and cannot be undone.</p>
  </ModalBody>
  <ModalFooter
    primaryButtonText="Delete"
    secondaryButtonText="Cancel"
    danger
    on:submit={() => (open = false)}
  />
</ComposedModal>
```

### Progress modal

Combine the composed modal with a progress indicator to create a multi-step flow
within a modal. Use the modal footer's default slot to render Cancel (ghost),
Previous (secondary), and Next (primary) buttons. Track the current step to
control which content is displayed and update the button label on the final
step.

```svelte
<script>
  import {
    Button,
    ComposedModal,
    ModalBody,
    ModalFooter,
    ModalHeader,
    ProgressIndicator,
    ProgressStep,
    Stack,
    TextInput,
  } from "carbon-components-svelte";
  import { tick } from "svelte";

  let open = false;
  let step = 0;
  let name = "";
  let region = "";

  async function goNext() {
    if (step < 2) {
      step++;
      await tick();
      const nextInput = document.querySelector(
        step === 1 ? "#region-input" : ".bx--modal-container .bx--btn--primary"
      );
      nextInput?.focus();
    } else {
      open = false;
    }
  }

  function handleSubmit() {
    goNext();
  }
</script>

<Button
  on:click={() => {
    open = true;
    step = 0;
    name = "";
    region = "";
  }}
>
  Create workspace
</Button>

<ComposedModal bind:open>
  <ModalHeader title="Create workspace" />
  <ModalBody hasForm>
    <form id="workspace-form" on:submit|preventDefault={handleSubmit}>
      <Stack gap={6}>
        <ProgressIndicator
          currentIndex={step}
          spaceEqually
          preventChangeOnClick
        >
          <ProgressStep complete={step > 0} label="General" />
          <ProgressStep complete={step > 1} label="Configure" />
          <ProgressStep label="Review" />
        </ProgressIndicator>
        {#if step === 0}
          <TextInput
            id="name-input"
            bind:value={name}
            labelText="Name"
            placeholder="e.g., My workspace"
          />
        {:else if step === 1}
          <TextInput
            id="region-input"
            bind:value={region}
            labelText="Region"
            placeholder="e.g., us-east-1"
          />
        {:else}
          <p>Review your workspace configuration before creating.</p>
          {#if name || region}
            <p>
              <strong>Name:</strong>
              {name || "(not set)"} · <strong>Region:</strong>
              {region || "(not set)"}
            </p>
          {/if}
        {/if}
      </Stack>
    </form>
  </ModalBody>
  <ModalFooter>
    <Button kind="ghost" on:click={() => (open = false)}>Cancel</Button>
    <Button kind="secondary" disabled={step === 0} on:click={() => step--}>
      Previous
    </Button>
    <Button type="submit" form="workspace-form">
      {step < 2 ? "Next" : "Create"}
    </Button>
  </ModalFooter>
</ComposedModal>
```

### Multiple secondary buttons

Set `secondaryButtons` in the modal footer to create a 3-button modal. This prop
replaces `secondaryButtonText` and takes a tuple of two button configurations.

```svelte
<script>
  import {
    Button,
    Checkbox,
    ComposedModal,
    ModalBody,
    ModalFooter,
    ModalHeader,
  } from "carbon-components-svelte";

  let open = true;
  let checked = false;
</script>

<Button on:click={() => (open = true)}>Review changes</Button>

<ComposedModal bind:open on:submit={() => (open = false)}>
  <ModalHeader label="Changes" title="Confirm changes" />
  <ModalBody hasForm>
    <Checkbox labelText="I have reviewed the changes" bind:checked />
  </ModalBody>
  <ModalFooter
    primaryButtonText="Proceed"
    primaryButtonDisabled={!checked}
    secondaryButtons={[{ text: "Cancel" }, { text: "Review" }]}
    on:click:button--secondary={({ detail }) => {
      if (detail.text === "Cancel") open = false;
      if (detail.text === "Review") console.log("Review");
    }}
  />
</ComposedModal>
```

---

### Component API

#### `ComposedModal` props

| Prop                         | Type                     | Description                                                           | Default                        |
| ---------------------------- | ------------------------ | --------------------------------------------------------------------- | ------------------------------ |
| `open` (Reactive)            | `boolean`                | Set to `true` to open the modal                                       | `false`                        |
| `ref` (Reactive)             | `null \| HTMLDivElement` | Obtain a reference to the top-level HTML element                      | `null`                         |
| `size`                       | `"xs" \| "sm" \| "lg"`   | Set the size of the composed modal.                                   | _undefined_                    |
| `danger`                     | `boolean`                | Set to `true` to use the danger variant                               | `false`                        |
| `preventCloseOnClickOutside` | `boolean`                | Set to `true` to prevent the modal from closing when clicking outside | `false`                        |
| `containerClass`             | `string`                 | Specify a class for the inner modal                                   | `""`                           |
| `selectorPrimaryFocus`       | `null \| string`         | Specify a selector to be focused when opening the modal.              | `"[data-modal-primary-focus]"` |

#### `ComposedModal` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ComposedModal` forwarded events

| Event           |
| --------------- |
| `on:keydown`    |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `ComposedModal` dispatched events

| Event                      | Detail                                                                                            |
| -------------------------- | ------------------------------------------------------------------------------------------------- |
| `on:close`                 | `{<br /> trigger:<br /> \| "escape-key"<br /> \| "outside-click"<br /> \| "close-button";<br />}` |
| `on:transitionend`         | `{<br /> open: boolean;<br />}`                                                                   |
| `on:submit`                | `null`                                                                                            |
| `on:click:button--primary` | `null`                                                                                            |
| `on:open`                  | `null`                                                                                            |

#### `ComposedModal` $$restProps

`ComposedModal` spreads `$$restProps` to the `div` element.

#### `ModalHeader` props

| Prop              | Type     | Description                               | Default   |
| ----------------- | -------- | ----------------------------------------- | --------- |
| `title`           | `string` | Specify the modal title                   | `""`      |
| `label`           | `string` | Specify the modal label                   | `""`      |
| `labelClass`      | `string` | Specify the label class                   | `""`      |
| `titleClass`      | `string` | Specify the title class                   | `""`      |
| `closeClass`      | `string` | Specify the close class                   | `""`      |
| `closeIconClass`  | `string` | Specify the close icon class              | `""`      |
| `iconDescription` | `string` | Specify the ARIA label for the close icon | `"Close"` |

#### `ModalHeader` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ModalHeader` forwarded events

| Event      |
| ---------- |
| `on:click` |

#### `ModalHeader` $$restProps

`ModalHeader` spreads `$$restProps` to the `div` element.

#### `ModalBody` props

| Prop                  | Type      | Description                                           | Default |
| --------------------- | --------- | ----------------------------------------------------- | ------- |
| `hasForm`             | `boolean` | Set to `true` if the modal contains form elements     | `false` |
| `hasScrollingContent` | `boolean` | Set to `true` if the modal contains scrolling content | `false` |

#### `ModalBody` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ModalBody` $$restProps

`ModalBody` spreads `$$restProps` to the `div` element.

#### `ModalFooter` props

| Prop                    | Type                                           | Description                                                                                               | Default     |
| ----------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------- |
| `primaryButtonText`     | `string`                                       | Specify the primary button text                                                                           | `""`        |
| `primaryButtonIcon`     | `any`                                          | Specify the primary button icon.                                                                          | _undefined_ |
| `primaryButtonDisabled` | `boolean`                                      | Set to `true` to disable the primary button                                                               | `false`     |
| `primaryClass`          | `string`                                       | Specify a class for the primary button.                                                                   | _undefined_ |
| `secondaryButtonText`   | `string`                                       | Specify the secondary button text                                                                         | `""`        |
| `secondaryButtons`      | `[] \| [{ text: string; }, { text: string; }]` | 2-tuple prop to render two secondary buttons for a 3 button modal.<br />Supersedes `secondaryButtonText`. | `[]`        |
| `secondaryClass`        | `string`                                       | Specify a class for the secondary button.                                                                 | _undefined_ |
| `danger`                | `boolean`                                      | Set to `true` to use the danger variant                                                                   | `false`     |

#### `ModalFooter` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ModalFooter` dispatched events

| Event                        | Detail                         |
| ---------------------------- | ------------------------------ |
| `on:click:button--secondary` | `{<br /> text: string;<br />}` |

#### `ModalFooter` $$restProps

`ModalFooter` spreads `$$restProps` to the `div` element.


## ContainedList

Contained lists provide a structured way to display a list of items within a
container. They support various sizes, interactive items, icons, actions, and
search functionality. They are useful for displaying hierarchical or grouped
content with consistent spacing and styling.

### Default

Display a basic contained list with a header label and list items. The default
size is `md`.

```svelte
<script>
  import { ContainedList, ContainedListItem } from "carbon-components-svelte";
</script>

<ContainedList labelText="List title">
  <ContainedListItem>Item 1</ContainedListItem>
  <ContainedListItem>Item 2</ContainedListItem>
  <ContainedListItem>Item 3</ContainedListItem>
</ContainedList>
```

### Custom label

Use the `labelChildren` slot to provide custom label content instead of using
the `labelText` prop.

```svelte
<script>
  import { ContainedList, ContainedListItem } from "carbon-components-svelte";
</script>

<ContainedList>
  <span slot="labelChildren" style:font-weight="normal">Custom label</span>
  <ContainedListItem>Item 1</ContainedListItem>
  <ContainedListItem>Item 2</ContainedListItem>
  <ContainedListItem>Item 3</ContainedListItem>
</ContainedList>
```

### Small size

Use the `sm` size variant for more compact list items with reduced padding and
height.

```svelte
<script>
  import { ContainedList, ContainedListItem } from "carbon-components-svelte";
</script>

<ContainedList labelText="List title" size="sm">
  <ContainedListItem>Item 1</ContainedListItem>
  <ContainedListItem>Item 2</ContainedListItem>
  <ContainedListItem>Item 3</ContainedListItem>
</ContainedList>
```

### Large size

Use the `lg` size variant for larger list items with increased padding and
height.

```svelte
<script>
  import { ContainedList, ContainedListItem } from "carbon-components-svelte";
</script>

<ContainedList labelText="List title" size="lg">
  <ContainedListItem>Item 1</ContainedListItem>
  <ContainedListItem>Item 2</ContainedListItem>
  <ContainedListItem>Item 3</ContainedListItem>
</ContainedList>
```

### Extra-large size

Use the `xl` size variant for the largest list items with maximum padding and
height.

```svelte
<script>
  import { ContainedList, ContainedListItem } from "carbon-components-svelte";
</script>

<ContainedList labelText="List title" size="xl">
  <ContainedListItem>Item 1</ContainedListItem>
  <ContainedListItem>Item 2</ContainedListItem>
  <ContainedListItem>Item 3</ContainedListItem>
</ContainedList>
```

### Inset rulers

Set the `inset` prop to `true` to make the divider lines between list items
inset from the edges, creating a more refined visual appearance.

```svelte
<script>
  import { ContainedList, ContainedListItem } from "carbon-components-svelte";
</script>

<ContainedList labelText="List title" inset>
  <ContainedListItem>Item 1</ContainedListItem>
  <ContainedListItem>Item 2</ContainedListItem>
  <ContainedListItem>Item 3</ContainedListItem>
</ContainedList>
```

### Disclosed variant

Set `kind="disclosed"` to use a more compact header style with sticky
positioning. When scrolling, the list header will stick to the top of the
container, making it useful for long lists where you want to keep the context
visible. The header in the disclosed variant has a fixed height.

```svelte
<script>
  import { ContainedList, ContainedListItem } from "carbon-components-svelte";
</script>

<div style:height="200px" style:overflow-y="auto">
  <ContainedList labelText="List title 1" kind="disclosed">
    {#each Array.from({ length: 6 }) as i}
      <ContainedListItem>Item</ContainedListItem>
    {/each}
  </ContainedList>
  <ContainedList labelText="List title 2" kind="disclosed">
    {#each Array.from({ length: 6 }) as i}
      <ContainedListItem>Item</ContainedListItem>
    {/each}
  </ContainedList>
</div>
```

### With icons

Add icons to list items by passing an icon component to the `icon` prop. Icons
are displayed to the left of the item content.

```svelte
<script>
  import { ContainedList, ContainedListItem } from "carbon-components-svelte";
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<ContainedList labelText="List title">
  <ContainedListItem icon={Add}>Item 1</ContainedListItem>
  <ContainedListItem icon={Add}>Item 2</ContainedListItem>
  <ContainedListItem icon={Add}>Item 3</ContainedListItem>
</ContainedList>
```

### With expandable search

Use the `action` slot on the contained list to add interactive elements like an
expandable search component. The search will be positioned in the header and can
be used to filter list items.

```svelte
<script>
  import {
    ContainedList,
    ContainedListItem,
    Search,
  } from "carbon-components-svelte";
</script>

<ContainedList labelText="List title">
  <Search slot="action" expandable />
  <ContainedListItem>Item 1</ContainedListItem>
  <ContainedListItem>Item 2</ContainedListItem>
  <ContainedListItem>Item 3</ContainedListItem>
</ContainedList>
```

### With persistent search

Pass the search component as a direct child (not in the `action` slot) to create
a persistent search that appears below the title. The search input is styled
specifically for use within the list and is adapted to work with the sticky list
headers.

```svelte
<script>
  import {
    ContainedList,
    ContainedListItem,
    Search,
  } from "carbon-components-svelte";

  let searchTerm = "";
  let searchResults = Array.from(
    { length: 50 },
    (_, i) => `List item ${i + 1}`
  );

  $: filteredResults = searchResults.filter((item) => {
    const lowerItem = item.toLowerCase();
    const lowerSearch = searchTerm.toLowerCase();
    return lowerItem.includes(lowerSearch);
  });
</script>

<ContainedList kind="disclosed" labelText="List title">
  <Search placeholder="Filterable search" bind:value={searchTerm} />
  {#each filteredResults as item}
    <ContainedListItem>{item}</ContainedListItem>
  {/each}
</ContainedList>
```

### Interactive items

Set the `interactive` prop to `true` on a contained list item to render the item
as a clickable button element. This enables keyboard navigation and click event
handling. You can also set `disabled` to prevent interaction.

```svelte
<script>
  import { ContainedList, ContainedListItem } from "carbon-components-svelte";
</script>

<ContainedList labelText="List title">
  <ContainedListItem interactive on:click={() => console.log("click")}>
    Item 1
  </ContainedListItem>
  <ContainedListItem interactive disabled>Item 2</ContainedListItem>
  <ContainedListItem interactive>Item 3</ContainedListItem>
</ContainedList>
```

### Interactive items with actions

Add interactive elements to individual list items using the `action` slot on a
contained list item. This is useful for adding buttons, icons, or other controls
that appear on the right side of each item. Actions are positioned absolutely
and don't interfere with the item's clickable area.

```svelte
<script>
  import {
    Button,
    ContainedList,
    ContainedListItem,
  } from "carbon-components-svelte";
  import Close from "carbon-icons-svelte/lib/Close.svelte";
</script>

<ContainedList labelText="List title">
  <ContainedListItem interactive on:click={() => console.log("click")}>
    Item 1
    <Button
      slot="action"
      kind="ghost"
      iconDescription="Dismiss"
      icon={Close}
      on:click={() => console.log("click close")}
    />
  </ContainedListItem>
  <ContainedListItem interactive disabled>Item 2</ContainedListItem>
  <ContainedListItem interactive>Item 3</ContainedListItem>
</ContainedList>
```

---

### Component API

#### `ContainedList` props

| Prop        | Type                           | Description                                                                     | Default                             |
| ----------- | ------------------------------ | ------------------------------------------------------------------------------- | ----------------------------------- |
| `kind`      | `"on-page" \| "disclosed"`     | Specify the kind of contained list.                                             | `"on-page"`                         |
| `labelText` | `string`                       | Specify the label text.<br />Alternatively, use the named slot "labelChildren". | `""`                                |
| `size`      | `"sm" \| "md" \| "lg" \| "xl"` | Specify the size of the list.                                                   | `"md"`                              |
| `inset`     | `boolean`                      | Set to `true` for lines between list items to be inset                          | `false`                             |
| `id`        | `string`                       | Set an id for the list element                                                  | `ccs-${Math.random().toString(36)}` |

#### `ContainedList` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `default`       | `Record<string, never>` |
| `action`        | `Record<string, never>` |
| `labelChildren` | `Record<string, never>` |

#### `ContainedListItem` props

| Prop          | Type      | Description                                                                        | Default     |
| ------------- | --------- | ---------------------------------------------------------------------------------- | ----------- |
| `interactive` | `boolean` | Set to `true` to render a `button` element instead of a `div`                      | `false`     |
| `disabled`    | `boolean` | Set to `true` to disable the list item                                             | `false`     |
| `icon`        | `any`     | Specify the icon to render.<br />Icon is rendered to the left of the item content. | _undefined_ |

#### `ContainedListItem` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |
| `action`  | `Record<string, never>` |

#### `ContainedListItem` forwarded events

| Event      |
| ---------- |
| `on:click` |


## ContentSwitcher

Content switchers let users switch between different views or sections of
content. Use them to organize related content into distinct categories or
states.

### Default

Create a content switcher with switch components. Each switch needs a `text`
prop.

```svelte
<script>
  import { ContentSwitcher, Switch } from "carbon-components-svelte";
</script>

<ContentSwitcher>
  <Switch text="Latest news" />
  <Switch text="Trending" />
</ContentSwitcher>
```

### Initial selected index

Set `selectedIndex` to pre-select a switch when the content switcher loads.

```svelte
<script>
  import { ContentSwitcher, Switch } from "carbon-components-svelte";
</script>

<ContentSwitcher selectedIndex={1}>
  <Switch text="Latest news" />
  <Switch text="Trending" />
  <Switch text="Recommended" />
</ContentSwitcher>
```

### Reactive example

This example demonstrates how to programmatically control the content switcher
using the `bind:selectedIndex` directive. Update the selected index based on
user interactions or application state.

```svelte
<script>
  import { Button, ContentSwitcher, Switch } from "carbon-components-svelte";

  let selectedIndex = 1;
</script>

<ContentSwitcher bind:selectedIndex>
  <Switch text="Latest news" />
  <Switch text="Trending" />
  <Switch text="Recommended" />
</ContentSwitcher>

<div>
  <Button
    size="small"
    disabled={selectedIndex === 2}
    on:click={() => (selectedIndex = 2)}
  >
    Set selected to 2
  </Button>
</div>

<div>Selected index: {selectedIndex}</div>

<style>
  div {
    margin-top: var(--cds-spacing-05);
  }
</style>
```

### Custom switch slot

Override the default slot in the switch to customize how each option displays.

```svelte
<script>
  import { ContentSwitcher, Stack, Switch } from "carbon-components-svelte";
  import Analytics from "carbon-icons-svelte/lib/Analytics.svelte";
  import Bullhorn from "carbon-icons-svelte/lib/Bullhorn.svelte";
</script>

<ContentSwitcher>
  <Switch>
    <Stack orientation="horizontal" gap={3}>
      <Bullhorn /> Latest news
    </Stack>
  </Switch>
  <Switch>
    <Stack orientation="horizontal" gap={3}>
      <Analytics /> Trending
    </Stack>
  </Switch>
</ContentSwitcher>
```

### Extra-large size

Set `size` to `"xl"` for an extra-large content switcher.

```svelte
<script>
  import { ContentSwitcher, Switch } from "carbon-components-svelte";
</script>

<ContentSwitcher size="xl">
  <Switch text="All" />
  <Switch text="Archived" />
</ContentSwitcher>
```

### Small size

Set `size` to `"sm"` for a small content switcher.

```svelte
<script>
  import { ContentSwitcher, Switch } from "carbon-components-svelte";
</script>

<ContentSwitcher size="sm">
  <Switch text="All" />
  <Switch text="Archived" />
</ContentSwitcher>
```

### Disabled state

Set `disabled` to `true` on individual switches to prevent interaction.

```svelte
<script>
  import { ContentSwitcher, Switch } from "carbon-components-svelte";
</script>

<ContentSwitcher>
  <Switch disabled text="All" />
  <Switch disabled text="Archived" />
</ContentSwitcher>
```

---

### Component API

#### `ContentSwitcher` props

| Prop                       | Type           | Description                               | Default     |
| -------------------------- | -------------- | ----------------------------------------- | ----------- |
| `selectedIndex` (Reactive) | `number`       | Set the selected index of the switch item | `0`         |
| `size`                     | `"sm" \| "xl"` | Specify the size of the content switcher. | _undefined_ |

#### `ContentSwitcher` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ContentSwitcher` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `ContentSwitcher` dispatched events

| Event       | Detail   |
| ----------- | -------- |
| `on:change` | `number` |

#### `ContentSwitcher` $$restProps

`ContentSwitcher` spreads `$$restProps` to the `div` element.

#### `Switch` props

| Prop                  | Type                        | Description                                                        | Default                             |
| --------------------- | --------------------------- | ------------------------------------------------------------------ | ----------------------------------- |
| `selected` (Reactive) | `boolean`                   | Set to `true` for the switch to be selected                        | `false`                             |
| `ref` (Reactive)      | `null \| HTMLButtonElement` | Obtain a reference to the button HTML element                      | `null`                              |
| `text`                | `string`                    | Specify the switch text.<br />Alternatively, use the default slot. | `"Provide text"`                    |
| `disabled`            | `boolean`                   | Set to `true` to disable the switch                                | `false`                             |
| `id`                  | `string`                    | Set an id for the button element                                   | `ccs-${Math.random().toString(36)}` |

#### `Switch` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `Switch` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:keydown`    |

#### `Switch` $$restProps

`Switch` spreads `$$restProps` to the `button` element.


## ContextMenu

Context menus display a menu when users right-click. Use them to provide quick
access to contextual actions or options.

In the examples, right click anywhere within the iframe.

### Default

The context menu appears when right-clicking anywhere in the window. Use context
menu option for menu items and context menu divider for visual separation.

```svelte
<script>
  import {
    ContextMenu,
    ContextMenuDivider,
    ContextMenuGroup,
    ContextMenuOption,
  } from "carbon-components-svelte";
  import CopyFile from "carbon-icons-svelte/lib/CopyFile.svelte";
  import Cut from "carbon-icons-svelte/lib/Cut.svelte";

  let selectedIds = [];

  $: console.log("selectedIds", selectedIds);
</script>

<ContextMenu>
  <ContextMenuOption
    indented
    labelText="Copy"
    shortcutText="⌘C"
    icon={CopyFile}
  />
  <ContextMenuOption indented labelText="Cut" shortcutText="⌘X" icon={Cut} />
  <ContextMenuDivider />
  <ContextMenuOption indented labelText="Export as">
    <ContextMenuGroup labelText="Export options" bind:selectedIds>
      <ContextMenuOption id="pdf" labelText="PDF" />
      <ContextMenuOption id="txt" labelText="TXT" />
      <ContextMenuOption id="mp3" labelText="MP3" />
    </ContextMenuGroup>
  </ContextMenuOption>
  <ContextMenuDivider />
  <ContextMenuOption selectable labelText="Remove metadata" />
  <ContextMenuDivider />
  <ContextMenuGroup labelText="Style options">
    <ContextMenuOption id="0" labelText="Font smoothing" selected />
    <ContextMenuOption id="1" labelText="Reduce noise" />
    <ContextMenuOption id="2" labelText="Auto-sharpen" />
  </ContextMenuGroup>
  <ContextMenuDivider />
  <ContextMenuOption indented kind="danger" labelText="Delete" />
</ContextMenu>

<div>
  <p>Right click anywhere on this page</p>
</div>

<style>
  div {
    position: absolute;
    width: calc(100% - var(--cds-spacing-05));
    height: calc(100% - var(--cds-spacing-06));
    display: flex;
    align-items: center;
    justify-content: center;
    color: var(--cds-text-02);
  }
</style>
```

### Custom target

By default, the context menu will trigger when right clicking anywhere in the
`window`.

Set `target` to specify which element triggers the context menu.

```svelte
<script>
  import {
    ContextMenu,
    ContextMenuDivider,
    ContextMenuGroup,
    ContextMenuOption,
  } from "carbon-components-svelte";
  import CopyFile from "carbon-icons-svelte/lib/CopyFile.svelte";
  import Cut from "carbon-icons-svelte/lib/Cut.svelte";

  let target;
</script>

<ContextMenu {target} on:open={(e) => console.log(e.detail)}>
  <ContextMenuOption
    indented
    labelText="Copy"
    shortcutText="⌘C"
    icon={CopyFile}
  />
  <ContextMenuOption indented labelText="Cut" shortcutText="⌘X" icon={Cut} />
  <ContextMenuDivider />
  <ContextMenuOption indented labelText="Export as">
    <ContextMenuGroup labelText="Export options">
      <ContextMenuOption id="pdf" labelText="PDF" />
      <ContextMenuOption id="txt" labelText="TXT" />
      <ContextMenuOption id="mp3" labelText="MP3" />
    </ContextMenuGroup>
  </ContextMenuOption>
  <ContextMenuDivider />
  <ContextMenuOption selectable labelText="Remove metadata" />
  <ContextMenuDivider />
  <ContextMenuGroup labelText="Style options">
    <ContextMenuOption id="0" labelText="Font smoothing" selected />
    <ContextMenuOption id="1" labelText="Reduce noise" />
    <ContextMenuOption id="2" labelText="Auto-sharpen" />
  </ContextMenuGroup>
  <ContextMenuDivider />
  <ContextMenuOption indented kind="danger" labelText="Delete" />
</ContextMenu>

<div>
  <p bind:this={target}>Right click this element</p>
</div>

<style>
  div {
    position: absolute;
    width: calc(100% - var(--cds-spacing-05));
    height: calc(100% - var(--cds-spacing-06));
    display: flex;
    align-items: center;
    justify-content: center;
    color: var(--cds-text-02);
  }

  p {
    outline: 1px solid var(--cds-interactive-01);
  }
</style>
```

### Multiple targets

Set `target` to an array of elements to trigger the context menu from multiple
sources.

```svelte
<script>
  import {
    ContextMenu,
    ContextMenuDivider,
    ContextMenuGroup,
    ContextMenuOption,
  } from "carbon-components-svelte";
  import CopyFile from "carbon-icons-svelte/lib/CopyFile.svelte";
  import Cut from "carbon-icons-svelte/lib/Cut.svelte";

  let target;
  let target2;
</script>

<ContextMenu target={[target, target2]} on:open={(e) => console.log(e.detail)}>
  <ContextMenuOption
    indented
    labelText="Copy"
    shortcutText="⌘C"
    icon={CopyFile}
  />
  <ContextMenuOption indented labelText="Cut" shortcutText="⌘X" icon={Cut} />
  <ContextMenuDivider />
  <ContextMenuOption indented labelText="Export as">
    <ContextMenuGroup labelText="Export options">
      <ContextMenuOption id="pdf" labelText="PDF" />
      <ContextMenuOption id="txt" labelText="TXT" />
      <ContextMenuOption id="mp3" labelText="MP3" />
    </ContextMenuGroup>
  </ContextMenuOption>
  <ContextMenuDivider />
  <ContextMenuOption selectable labelText="Remove metadata" />
  <ContextMenuDivider />
  <ContextMenuGroup labelText="Style options">
    <ContextMenuOption id="0" labelText="Font smoothing" selected />
    <ContextMenuOption id="1" labelText="Reduce noise" />
    <ContextMenuOption id="2" labelText="Auto-sharpen" />
  </ContextMenuGroup>
  <ContextMenuDivider />
  <ContextMenuOption indented kind="danger" labelText="Delete" />
</ContextMenu>

<div>
  <p bind:this={target}>Right click this element</p>
  <p bind:this={target2}>... or this one</p>
</div>

<style>
  div {
    position: absolute;
    width: calc(100% - var(--cds-spacing-05));
    height: calc(100% - var(--cds-spacing-06));
    display: flex;
    align-items: center;
    justify-content: center;
    color: var(--cds-text-02);
  }

  p {
    outline: 1px solid var(--cds-interactive-01);
  }
</style>
```

### Radio groups

Use context menu group and context menu radio group to organize related options
and create radio button selections.

```svelte
<script>
  import {
    ContextMenu,
    ContextMenuDivider,
    ContextMenuOption,
    ContextMenuRadioGroup,
  } from "carbon-components-svelte";

  let selectedId = "0";

  $: console.log("selectedId", selectedId);
</script>

<ContextMenu>
  <ContextMenuOption indented labelText="Open" />
  <ContextMenuDivider />
  <ContextMenuRadioGroup bind:selectedId labelText="Radio group">
    <ContextMenuOption id="0" labelText="Set as foreground" />
    <ContextMenuOption id="1" labelText="Set as background" />
  </ContextMenuRadioGroup>
  <ContextMenuDivider />
  <ContextMenuOption selectable labelText="Lock layer" />
</ContextMenu>

<div>
  <p>Right click anywhere on this page</p>
</div>

<style>
  div {
    position: absolute;
    width: calc(100% - var(--cds-spacing-05));
    height: calc(100% - var(--cds-spacing-06));
    display: flex;
    align-items: center;
    justify-content: center;
    color: var(--cds-text-02);
  }
</style>
```

---

### Component API

#### `ContextMenu` props

| Prop              | Type                                         | Description                                                                                                                                         | Default |
| ----------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `open` (Reactive) | `boolean`                                    | Set to `true` to open the menu.<br />Either `x` and `y` must be greater than zero.                                                                  | `false` |
| `x` (Reactive)    | `number`                                     | Specify the horizontal offset of the menu position                                                                                                  | `0`     |
| `y` (Reactive)    | `number`                                     | Specify the vertical offset of the menu position                                                                                                    | `0`     |
| `ref` (Reactive)  | `null \| HTMLUListElement`                   | Obtain a reference to the unordered list HTML element                                                                                               | `null`  |
| `target`          | `null \| ReadonlyArray<null \| HTMLElement>` | Specify an element or list of elements to trigger the context menu.<br />If no element is specified, the context menu applies to the entire window. | `null`  |

#### `ContextMenu` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ContextMenu` forwarded events

| Event        |
| ------------ |
| `on:click`   |
| `on:keydown` |

#### `ContextMenu` dispatched events

| Event      | Detail        |
| ---------- | ------------- |
| `on:open`  | `HTMLElement` |
| `on:close` | `null`        |

#### `ContextMenu` $$restProps

`ContextMenu` spreads `$$restProps` to the `ul` element.

#### `ContextMenuGroup` props

| Prop                     | Type                    | Description            | Default |
| ------------------------ | ----------------------- | ---------------------- | ------- |
| `selectedIds` (Reactive) | `ReadonlyArray<string>` |                        | `[]`    |
| `labelText`              | `string`                | Specify the label text | `""`    |

#### `ContextMenuGroup` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ContextMenuRadioGroup` props

| Prop                    | Type     | Description                     | Default |
| ----------------------- | -------- | ------------------------------- | ------- |
| `selectedId` (Reactive) | `string` | Set the selected radio group id | `""`    |
| `labelText`             | `string` | Specify the label text          | `""`    |

#### `ContextMenuRadioGroup` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ContextMenuOption` props

| Prop                    | Type                    | Description                                                                                                        | Default                             |
| ----------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
| `indented` (Reactive)   | `boolean`               | Set to `true` to indent the label                                                                                  | `false`                             |
| `icon` (Reactive)       | `any`                   | Specify the icon to render.<br />Icon is rendered to the left of the label text.                                   | _undefined_                         |
| `selected` (Reactive)   | `boolean`               | Set to `true` to use the selected variant                                                                          | `false`                             |
| `selectable` (Reactive) | `boolean`               | Set to `true` to enable the selectable variant.<br />Automatically set to `true` if `selected` is `true`.          | `false`                             |
| `ref` (Reactive)        | `null \| HTMLLIElement` | Obtain a reference to the list item HTML element                                                                   | `null`                              |
| `kind`                  | `"default" \| "danger"` | Specify the kind of option.                                                                                        | `"default"`                         |
| `disabled`              | `boolean`               | Set to `true` to enable the disabled state                                                                         | `false`                             |
| `labelText`             | `string`                | Specify the label text.<br />Alternatively, use the "labelChildren" slot.                                          | `""`                                |
| `shortcutText`          | `string`                | Specify the shortcut text.<br />Alternatively, use the "shortcutText" slot.                                        | `""`                                |
| `id`                    | `string`                | Specify the id.<br />It's recommended to provide an id as a value to bind to within a selectable/radio menu group. | `ccs-${Math.random().toString(36)}` |

#### `ContextMenuOption` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `default`       | `Record<string, never>` |
| `icon`          | `Record<string, never>` |
| `labelChildren` | `Record<string, never>` |
| `shortcutText`  | `Record<string, never>` |

#### `ContextMenuOption` forwarded events

| Event           |
| --------------- |
| `on:keydown`    |
| `on:mouseenter` |
| `on:mouseleave` |

#### `ContextMenuOption` dispatched events

| Event      | Detail |
| ---------- | ------ |
| `on:click` | `null` |

#### `ContextMenuOption` $$restProps

`ContextMenuOption` spreads `$$restProps` to the `li` element.


## CopyButton

Copy buttons let users copy text to their clipboard with a single click. Use
them to provide quick access to code snippets, links, or other text content.

This component uses the native
[Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText)
to copy text. Override the default copy functionality with your own
implementation. See
[Overriding copy functionality](#overriding-copy-functionality).

### Default

Create a copy button with the `text` prop to specify what to copy.

```svelte
<script>
  import { CopyButton } from "carbon-components-svelte";
</script>

<CopyButton text="Carbon svelte" />
```

### Custom feedback text

Set `feedback` to customize the message shown after copying.

```svelte
<script>
  import { CopyButton } from "carbon-components-svelte";
</script>

<CopyButton text="Carbon svelte" feedback="Copied to clipboard" />
```

### Overriding copy functionality

Pass a custom function to the `copy` prop to override the default copy behavior.

This example uses the NPM package
[clipboard-copy](https://github.com/feross/clipboard-copy) to copy the text
instead of the default Clipboard API.

```svelte
<script>
  import { CopyButton } from "carbon-components-svelte";
  import copy from "clipboard-copy";
</script>

<CopyButton text="Carbon svelte" copy={(text) => copy(text)} />
```

### Preventing copy functionality

Pass a no-op function to the `copy` prop to disable copying.

```svelte
<script>
  import { CopyButton } from "carbon-components-svelte";
</script>

<CopyButton text="This text should not be copied" copy={() => {}} />
```

---

### Component API

#### `CopyButton` props

| Prop              | Type                     | Description                                                                                     | Default               |
| ----------------- | ------------------------ | ----------------------------------------------------------------------------------------------- | --------------------- |
| `text` (Required) | `string`                 | Specify the text to copy.                                                                       | _undefined_           |
| `feedback`        | `string`                 | Set the feedback text shown after clicking the button                                           | `"Copied!"`           |
| `feedbackTimeout` | `number`                 | Set the timeout duration (ms) to display feedback text                                          | `2000`                |
| `iconDescription` | `string`                 | Set the title and ARIA label for the copy button                                                | `"Copy to clipboard"` |
| `copy`            | `(text: string) => void` | Override the default copy behavior of using the navigator.clipboard.writeText API to copy text. | _undefined_           |

#### `CopyButton` forwarded events

| Event             |
| ----------------- |
| `on:click`        |
| `on:animationend` |

#### `CopyButton` dispatched events

| Event     | Detail |
| --------- | ------ |
| `on:copy` | `null` |

#### `CopyButton` $$restProps

`CopyButton` spreads `$$restProps` to the `button` element.


## DataTable

Data tables display structured data in a tabular format. Use them to present
large datasets with features like sorting, filtering, pagination,
virtualization, and row selection.

> [!NOTE] This component is keyed for performance. Every **headers** object must
> have a unique "key" property. Every **rows** object must have a unique "id"
> property.

### Default

Create a basic table by providing `headers` and `rows` data. Match the `key` in
headers with the corresponding property in rows.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
/>
```

### Slotted cells

Use the `"cell"` slot to customize cell content. Access row and cell data
through `let:row` and `let:cell` directives. Use `"cellHeader"` slot for header
cells.

```svelte
<script>
  import { DataTable, Link } from "carbon-components-svelte";
  import Launch from "carbon-icons-svelte/lib/Launch.svelte";
</script>

<DataTable
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
>
  <svelte:fragment slot="cellHeader" let:header>
    {#if header.key === "port"}
      {header.value} (network)
    {:else}
      {header.value}
    {/if}
  </svelte:fragment>
  <svelte:fragment slot="cell" let:row let:cell>
    {#if cell.key === "rule" && cell.value === "Round robin"}
      <Link
        icon={Launch}
        href="https://en.wikipedia.org/wiki/Round-robin_DNS"
        target="_blank">{cell.value}</Link
      >
    {:else}
      {cell.value}
    {/if}
  </svelte:fragment>
</DataTable>
```

### Custom cell rendering with row state

The `"cell"` slot provides `rowSelected` and `rowExpanded` props to
conditionally render content based on row state.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";

  let selectedRowIds = ["a", "c"];
  let expandedRowIds = ["b"];
</script>

<DataTable
  selectable
  expandable
  bind:selectedRowIds
  bind:expandedRowIds
  headers={[
    { key: "name", value: "Name" },
    { key: "status", value: "Status" },
    { key: "port", value: "Port" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 1",
      status: "Active",
      port: 3000,
    },
    {
      id: "b",
      name: "Load Balancer 2",
      status: "Active",
      port: 443,
    },
    {
      id: "c",
      name: "Load Balancer 3",
      status: "Inactive",
      port: 80,
    },
  ]}
>
  <svelte:fragment slot="cell" let:row let:cell let:rowSelected let:rowExpanded>
    {#if cell.key === "status"}
      <span
        style="color: {rowSelected
          ? '#0f62fe'
          : cell.value === 'Active'
          ? 'green'
          : 'gray'}"
      >
        {cell.value}
        {rowExpanded ? "(expanded)" : ""}
      </span>
    {:else}
      {cell.value}
    {/if}
  </svelte:fragment>
  <svelte:fragment slot="expanded-row" let:row let:rowSelected>
    <div>
      Additional details for <strong>{row.name}</strong>
      {rowSelected ? "(Currently selected)" : ""}
    </div>
  </svelte:fragment>
</DataTable>
```

### With title, description

Add a title and description to provide context for the table data.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  title="Load balancers"
  description="Your organization's active load balancers."
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
/>
```

### Slottable title, description

By default, the title is rendered as a `<h4>` element and the description is
rendered as a `<p>` element.

Use slots to customize the elements and styles. The original classes can be
destructured using `let:props`.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
>
  <h1 slot="titleChildren" let:props {...props}>Load balancers</h1>
  <span slot="descriptionChildren" let:props {...props} style="font-size: 1rem"
    >Your organization's active load balancers.</span
  >
</DataTable>
```

### Static width

Set `useStaticWidth` to `true` to render the table with an auto width instead of
100%.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  useStaticWidth
  title="Load balancers"
  description="Your organization's active load balancers."
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
/>
```

### Custom column widths

Specify `width` or `minWidth` in the `headers` object to set column dimensions.
This applies a fixed table layout.

> [!WARNING] Custom column widths do not work with a
> [sticky header](#sticky-header).

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  headers={[
    { key: "name", value: "Name", width: "50%", minWidth: "200px" },
    { key: "protocol", value: "Protocol", width: "60px" },
    { key: "port", value: "Port", width: "60px" },
    { key: "rule", value: "Rule", width: "10rem" },
  ]}
  rows={Array.from({ length: 6 }).map((_, i) => ({
    id: i,
    name: "Load Balancer " + (i + 1),
    protocol: "HTTP",
    port: i % 3 ? (i % 2 ? 3000 : 80) : 443,
    rule: i % 3 ? "Round robin" : "DNS delegation",
  }))}
/>
```

### Sticky header

Set `stickyHeader` to `true` to fix the header in place. This adds a maximum
height to force scrolling.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  stickyHeader
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={Array.from({ length: 20 }).map((_, i) => ({
    id: i,
    name: "Load Balancer " + (i + 1),
    protocol: "HTTP",
    port: i % 3 ? (i % 2 ? 3000 : 80) : 443,
    rule: i % 3 ? "Round robin" : "DNS delegation",
  }))}
/>
```

### Virtualized rows (large datasets)

Virtualization renders only the rows currently visible in the viewport,
improving performance for large datasets. Set `virtualize={true}` to enable. The
header stays visible while scrolling (sticky positioning is applied
automatically). Use `stickyHeader={true}` for the intended layout, if necessary.
Container height defaults to 10 rows (`itemHeight * maxVisibleRows`).

The example below shows 10,000 rows with a filterable toolbar; only visible rows
are rendered in the DOM.

```svelte
<script>
  import {
    DataTable,
    Toolbar,
    ToolbarContent,
    ToolbarSearch,
  } from "carbon-components-svelte";

  const rows = Array.from({ length: 10_000 }, (_, i) => ({
    id: i,
    name: `Load Balancer ${i + 1}`,
    protocol: "HTTP",
    port: 3000 + i * 10,
    rule: i % 2 ? "Round robin" : "DNS delegation",
  }));

  let filteredRowIds = [];
</script>

<DataTable
  sortable
  virtualize={true}
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  {rows}
>
  <Toolbar>
    <ToolbarContent>
      <ToolbarSearch
        persistent
        placeholder="Search 10,000 rows..."
        shouldFilterRows
        bind:filteredRowIds
      />
    </ToolbarContent>
  </Toolbar>
</DataTable>
```

### Virtualized rows (custom overscan)

Overscanning renders extra rows above and below the viewport for smoother
scrolling. The default overscan value is 3. Specify a custom `overscan` to
control how many extra rows are rendered.

```svelte
<script>
  import {
    DataTable,
    Toolbar,
    ToolbarContent,
    ToolbarSearch,
  } from "carbon-components-svelte";

  const rows = Array.from({ length: 10_000 }, (_, i) => ({
    id: i,
    name: `Load Balancer ${i + 1}`,
    protocol: "HTTP",
    port: 3000 + i * 10,
    rule: i % 2 ? "Round robin" : "DNS delegation",
  }));

  let filteredRowIds = [];
</script>

<DataTable
  sortable
  virtualize={{ overscan: 10 }}
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  {rows}
>
  <Toolbar>
    <ToolbarContent>
      <ToolbarSearch
        persistent
        placeholder="Search 10,000 rows..."
        shouldFilterRows
        bind:filteredRowIds
      />
    </ToolbarContent>
  </Toolbar>
</DataTable>
```

### Virtualized rows (custom row height)

By default, the virtual row height matches the table size variant (48px medium,
24px compact, 32px short, 64px tall). Use `rowClass` to apply a custom row
height via CSS and set `itemHeight` to match for correct virtualization.

```svelte
<script>
  import {
    DataTable,
    Toolbar,
    ToolbarContent,
    ToolbarSearch,
  } from "carbon-components-svelte";

  const rows = Array.from({ length: 10_000 }, (_, i) => ({
    id: i,
    name: `Load Balancer ${i + 1}`,
    protocol: "HTTP",
    port: 3000 + i * 10,
  }));

  let filteredRowIds = [];
</script>

<DataTable
  sortable
  virtualize={{ itemHeight: 20 }}
  rowClass="virtualize-tall-row"
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
  ]}
  {rows}
>
  <Toolbar>
    <ToolbarContent>
      <ToolbarSearch
        persistent
        placeholder="Search 10,000 rows..."
        shouldFilterRows
        bind:filteredRowIds
      />
    </ToolbarContent>
  </Toolbar>
</DataTable>

<style>
  :global(.bx--data-table-container tbody tr.virtualize-tall-row) {
    height: 24px;
  }
</style>
```

### Virtualized rows (custom max visible rows)

By default, the table shows 10 rows in the viewport. Customize `maxVisibleRows`
to control how many rows are visible at once. Container height is calculated as
`itemHeight * maxVisibleRows`, or use `containerHeight` for pixel-based control.

```svelte
<script>
  import {
    DataTable,
    Toolbar,
    ToolbarContent,
    ToolbarSearch,
  } from "carbon-components-svelte";

  const rows = Array.from({ length: 10_000 }, (_, i) => ({
    id: i,
    name: `Load Balancer ${i + 1}`,
    protocol: "HTTP",
    port: 3000 + i * 10,
    rule: i % 2 ? "Round robin" : "DNS delegation",
  }));

  let filteredRowIds = [];
</script>

<DataTable
  sortable
  virtualize={{ maxVisibleRows: 5 }}
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  {rows}
>
  <Toolbar>
    <ToolbarContent>
      <ToolbarSearch
        persistent
        placeholder="Search 10,000 rows..."
        shouldFilterRows
        bind:filteredRowIds
      />
    </ToolbarContent>
  </Toolbar>
</DataTable>
```

### With toolbar

Add a toolbar with search, menu, and actions above the table.

```svelte
<script>
  import {
    Button,
    DataTable,
    Toolbar,
    ToolbarContent,
    ToolbarMenu,
    ToolbarMenuItem,
    ToolbarSearch,
  } from "carbon-components-svelte";
</script>

<DataTable
  title="Load balancers"
  description="Your organization's active load balancers."
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
>
  <Toolbar>
    <ToolbarContent>
      <ToolbarSearch />
      <ToolbarMenu>
        <ToolbarMenuItem primaryFocus>Restart all</ToolbarMenuItem>
        <ToolbarMenuItem href="https://cloud.ibm.com/docs/loadbalancer-service">
          API documentation
        </ToolbarMenuItem>
        <ToolbarMenuItem hasDivider danger>Stop all</ToolbarMenuItem>
      </ToolbarMenu>
      <Button>Create balancer</Button>
    </ToolbarContent>
  </Toolbar>
</DataTable>
```

### With toolbar (small size)

Use `size="short"` to create a more compact table with a small toolbar.

```svelte
<script>
  import {
    Button,
    DataTable,
    Toolbar,
    ToolbarContent,
    ToolbarMenu,
    ToolbarMenuItem,
    ToolbarSearch,
  } from "carbon-components-svelte";
</script>

<DataTable
  size="short"
  title="Load balancers"
  description="Your organization's active load balancers."
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
>
  <Toolbar size="sm">
    <ToolbarContent>
      <ToolbarSearch />
      <ToolbarMenu>
        <ToolbarMenuItem primaryFocus>Restart all</ToolbarMenuItem>
        <ToolbarMenuItem href="https://cloud.ibm.com/docs/loadbalancer-service"
          >API documentation</ToolbarMenuItem
        >
        <ToolbarMenuItem hasDivider danger>Stop all</ToolbarMenuItem>
      </ToolbarMenu>
      <Button>Create balancer</Button>
    </ToolbarContent>
  </Toolbar>
</DataTable>
```

### With toolbar and selectable rows

Set `selectable` to `true` to enable selectable rows. Here, the toolbar is used
standalone. For batch actions for selected rows, see the
[batch selection with toolbar](#batch-selection-with-batch-actions-toolbar)
example.

```svelte
<script>
  import {
    Button,
    DataTable,
    Toolbar,
    ToolbarContent,
    ToolbarSearch,
  } from "carbon-components-svelte";
</script>

<DataTable
  selectable
  size="short"
  title="Load balancers"
  description="Your organization's active load balancers."
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
>
  <Toolbar size="sm">
    <ToolbarContent>
      <ToolbarSearch persistent />
      <Button>Action</Button>
    </ToolbarContent>
  </Toolbar>
</DataTable>
```

### Filterable

Set `shouldFilterRows` to `true` to enable client-side filtering. The default
filter performs string comparisons on cell values.

For pagination with filtering, bind to `filteredRowIds` and pass its length to
the pagination component's `totalItems`.

```svelte
<script>
  import {
    DataTable,
    Pagination,
    Toolbar,
    ToolbarContent,
    ToolbarSearch,
  } from "carbon-components-svelte";

  let rows = Array.from({ length: 10 }).map((_, i) => ({
    id: i,
    name: `Load Balancer ${i + 1}`,
    protocol: "HTTP",
    port: 3000 + i * 10,
    rule: i % 2 ? "Round robin" : "DNS delegation",
  }));
  let pageSize = 5;
  let page = 1;
  let filteredRowIds = [];

  $: console.log("filteredRowIds", filteredRowIds);
</script>

<DataTable
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  {rows}
  {pageSize}
  {page}
>
  <Toolbar>
    <ToolbarContent>
      <ToolbarSearch
        persistent
        value="round"
        shouldFilterRows
        bind:filteredRowIds
      />
    </ToolbarContent>
  </Toolbar>
</DataTable>

<Pagination
  bind:pageSize
  bind:page
  totalItems={filteredRowIds.length}
  pageSizeInputDisabled
/>
```

### Filterable (custom)

Pass a function to `shouldFilterRows` to implement custom filtering logic.

```svelte
<script>
  import {
    DataTable,
    Pagination,
    Toolbar,
    ToolbarContent,
    ToolbarSearch,
  } from "carbon-components-svelte";

  let rows = Array.from({ length: 10 }).map((_, i) => ({
    id: i,
    name: `Load Balancer ${i + 1}`,
    protocol: "HTTP",
    port: 3000 + i * 10,
    rule: i % 2 ? "Round robin" : "DNS delegation",
  }));
  let pageSize = 5;
  let page = 1;
  let filteredRowIds = [];

  $: console.log("filteredRowIds", filteredRowIds);
</script>

<DataTable
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  {rows}
  {pageSize}
  {page}
>
  <Toolbar>
    <ToolbarContent>
      <ToolbarSearch
        persistent
        value="round"
        shouldFilterRows={(row, value) => {
          return (
            /(6|8)$/.test(row.name) &&
            row.rule.toLowerCase().includes(value.toLowerCase())
          );
        }}
        bind:filteredRowIds
      />
    </ToolbarContent>
  </Toolbar>
</DataTable>

<Pagination
  bind:pageSize
  bind:page
  totalItems={filteredRowIds.length}
  pageSizeInputDisabled
/>
```

### Zebra stripes

Set `zebra` to `true` to add alternating row colors.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  zebra
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
/>
```

### Custom row classes

Use `rowClass` to apply custom CSS classes to rows. Pass a string for a static
class, or a function that receives `{ row, rowIndex, selected, expanded }` and
returns conditional classes. Try selecting and expanding rows to see the custom
styles.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";

  let selectedRowIds = [];
  let expandedRowIds = [];
</script>

<DataTable
  selectable
  expandable
  bind:selectedRowIds
  bind:expandedRowIds
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTPS",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTPS",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
  rowClass={({ row, selected, expanded }) => {
    const classes = [];
    if (row.protocol === "HTTPS") classes.push("secure");
    if (selected) classes.push("selected");
    if (expanded) classes.push("expanded");
    return classes.join(" ") || undefined;
  }}
>
  <svelte:fragment slot="expanded-row" let:row>
    <pre>{JSON.stringify(row, null, 2)}</pre>
  </svelte:fragment>
</DataTable>

<style>
  :global(.selected) {
    outline: 2px solid var(--cds-focus);
  }

  :global(:not(.bx--data-table--selected) .expanded) {
    border-left: 3px solid var(--cds-interactive-01);
  }
</style>
```

### Tall rows

Set `size="tall"` for increased row height.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  size="tall"
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
/>
```

### Medium rows

Set `size="medium"` for standard row height.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  size="medium"
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
/>
```

### Short rows

Set `size="short"` for compact row height.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  size="short"
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
/>
```

### Compact rows

Set `size="compact"` for minimal row height.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  size="compact"
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
/>
```

### Sortable

Set `sortable` to `true` to enable column sorting. Disable sorting on specific
columns by setting `sort: false` in the header object.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  sortable
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol", sort: false },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
/>
```

### Sortable with pagination

Bind to `pageSize` and `page` props of the pagination component and pass them to
the data table.

```svelte
<script>
  import { DataTable, Pagination } from "carbon-components-svelte";

  let rows = Array.from({ length: 10 }).map((_, i) => ({
    id: i,
    name: `Load Balancer ${i + 1}`,
    protocol: "HTTP",
    port: 3000 + i * 10,
    rule: i % 2 ? "Round robin" : "DNS delegation",
  }));
  let pageSize = 5;
  let page = 1;
</script>

<DataTable
  sortable
  title="Load balancers"
  description="Your organization's active load balancers."
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  {pageSize}
  {page}
  {rows}
/>
<Pagination
  bind:pageSize
  bind:page
  totalItems={rows.length}
  pageSizeInputDisabled
/>
```

### Sortable with custom display and sort methods

Use `display` and `sort` functions in header objects to customize cell rendering
and sorting.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  sortable
  title="Load balancers"
  description="Your organization's active load balancers."
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "cost", value: "Cost", display: (cost) => cost + " €" },
    {
      key: "expireDate",
      value: "Expire date",
      display: (date) => new Date(date).toLocaleString(),
      sort: (a, b) => new Date(a) - new Date(b),
    },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      cost: 100,
      expireDate: "2020-10-21",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      cost: 200,
      expireDate: "2020-09-10",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      cost: 150,
      expireDate: "2020-11-24",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      cost: 250,
      expireDate: "2020-12-01",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      cost: 550,
      expireDate: "2021-03-21",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      cost: 400,
      expireDate: "2020-11-14",
    },
  ]}
/>
```

### Sortable with nested object values

Access nested object properties using dot notation in the header key.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  sortable
  title="Load balancers"
  description="Your organization's active load balancers."
  headers={[
    { key: "name", value: "Name" },
    { key: "network.protocol", value: "Protocol" },
    { key: "network.port", value: "Port" },
    { key: "cost", value: "Cost", display: (cost) => cost + " €" },
    {
      key: "expireDate",
      value: "Expire date",
      display: (date) => new Date(date).toLocaleString(),
      sort: (a, b) => new Date(a) - new Date(b),
    },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      network: {
        protocol: "HTTP",
        port: 3000,
      },
      cost: 100,
      expireDate: "2020-10-21",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      network: {
        protocol: "HTTP",
        port: 443,
      },
      cost: 200,
      expireDate: "2020-09-10",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      network: {
        protocol: "HTTP",
        port: 80,
      },
      cost: 150,
      expireDate: "2020-11-24",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      network: {
        protocol: "HTTP",
        port: 3000,
      },
      cost: 250,
      expireDate: "2020-12-01",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      network: {
        protocol: "HTTP",
        port: 443,
      },
      cost: 550,
      expireDate: "2021-03-21",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      network: {
        protocol: "HTTP",
        port: 80,
      },
      cost: 400,
      expireDate: "2020-11-14",
    },
  ]}
/>
```

### Programmatic sorting

Use `sortKey` and `sortDirection` props to control sorting programmatically. Set
`sortKey` to a valid header key and `sortDirection` to "none", "ascending", or
"descending".

```svelte
<script>
  import { Button, DataTable } from "carbon-components-svelte";

  let sortKey = "port";
  let sortDirection = "ascending";

  $: console.log("sortKey", sortKey);
  $: console.log("sortDirection", sortDirection);
</script>

<div style="margin-bottom: 1rem">
  <Button
    size="sm"
    kind="tertiary"
    disabled={sortKey === "port" && sortDirection === "ascending"}
    on:click={() => {
      sortKey = "port";
      sortDirection = "ascending";
    }}
  >
    Sort "port" in ascending order
  </Button>
  <Button
    size="sm"
    kind="tertiary"
    disabled={sortKey === "name" && sortDirection === "descending"}
    on:click={() => {
      sortKey = "name";
      sortDirection = "descending";
    }}
  >
    Sort "name" in descending order
  </Button>
  <Button
    size="sm"
    kind="ghost"
    on:click={() => {
      sortKey = null;
      sortDirection = "none";
    }}
  >
    Clear sorting
  </Button>
</div>

<DataTable
  sortable
  bind:sortKey
  bind:sortDirection
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol", sort: false },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
/>
```

### Empty column with overflow menu

Set `empty: true` in a header object to create an empty column. Use this for
overflow menus without a header.

```svelte
<script>
  import {
    DataTable,
    OverflowMenu,
    OverflowMenuItem,
  } from "carbon-components-svelte";

  const headers = [
    { key: "name", value: "Name" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
    { key: "overflow", empty: true, width: "72px" },
  ];

  const rows = [
    { id: "a", name: "Load Balancer 3", port: 3000, rule: "Round robin" },
    { id: "b", name: "Load Balancer 1", port: 443, rule: "Round robin" },
    { id: "c", name: "Load Balancer 2", port: 80, rule: "DNS delegation" },
    { id: "d", name: "Load Balancer 6", port: 3000, rule: "Round robin" },
    { id: "e", name: "Load Balancer 4", port: 443, rule: "Round robin" },
    { id: "f", name: "Load Balancer 5", port: 80, rule: "DNS delegation" },
  ];
</script>

<DataTable sortable {headers} {rows}>
  <svelte:fragment slot="cell" let:cell>
    {#if cell.key === "overflow"}
      <OverflowMenu portalMenu flipped>
        <OverflowMenuItem text="Restart" />
        <OverflowMenuItem
          href="https://cloud.ibm.com/docs/loadbalancer-service"
          text="API documentation"
        />
        <OverflowMenuItem danger text="Stop" />
      </OverflowMenu>
    {:else}{cell.value}{/if}
  </svelte:fragment>
</DataTable>
```

### Selectable rows (checkbox)

Set `selectable` to `true` for multi-select functionality. Bind to
`selectedRowIds` to track selections. Use `inputName` to customize checkbox
names.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";

  let selectedRowIds = [];

  $: console.log("selectedRowIds", selectedRowIds);
</script>

<DataTable
  selectable
  bind:selectedRowIds
  headers={[
    { key: "name", value: "Name" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={Array.from({ length: 6 }).map((_, i) => ({
    id: i,
    name: "Load Balancer " + (i + 1),
    protocol: "HTTP",
    port: i % 3 ? (i % 2 ? 3000 : 80) : 443,
    rule: i % 3 ? "Round robin" : "DNS delegation",
  }))}
/>
```

### Batch selection

Set `batchSelection` to `true` to add a checkbox for selecting all rows. The
checkbox shows an indeterminate state when some rows are selected.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";

  let selectedRowIds = [];

  $: console.log("selectedRowIds", selectedRowIds);
</script>

<DataTable
  batchSelection
  bind:selectedRowIds
  headers={[
    { key: "name", value: "Name" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={Array.from({ length: 6 }).map((_, i) => ({
    id: i,
    name: "Load Balancer " + (i + 1),
    protocol: "HTTP",
    port: i % 3 ? (i % 2 ? 3000 : 80) : 443,
    rule: i % 3 ? "Round robin" : "DNS delegation",
  }))}
/>
```

### Batch selection with initial selected rows

Use `selectedRowIds` to specify initially selected rows.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";

  let selectedRowIds = [2, 4];

  $: console.log("selectedRowIds", selectedRowIds);
</script>

<DataTable
  batchSelection
  bind:selectedRowIds
  headers={[
    { key: "name", value: "Name" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={Array.from({ length: 6 }).map((_, i) => ({
    id: i,
    name: "Load Balancer " + (i + 1),
    protocol: "HTTP",
    port: i % 3 ? (i % 2 ? 3000 : 80) : 443,
    rule: i % 3 ? "Round robin" : "DNS delegation",
  }))}
/>
```

### Batch selection with batch actions toolbar

Add a toolbar for batch actions when rows are selected.

```svelte
<script>
  import {
    Button,
    DataTable,
    Toolbar,
    ToolbarBatchActions,
    ToolbarContent,
    ToolbarMenu,
    ToolbarMenuItem,
    ToolbarSearch,
  } from "carbon-components-svelte";
  import Save from "carbon-icons-svelte/lib/Save.svelte";

  const headers = [
    { key: "name", value: "Name" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ];

  const rows = [
    { id: "a", name: "Load Balancer 3", port: 3000, rule: "Round robin" },
    { id: "b", name: "Load Balancer 1", port: 443, rule: "Round robin" },
    { id: "c", name: "Load Balancer 2", port: 80, rule: "DNS delegation" },
    { id: "d", name: "Load Balancer 6", port: 3000, rule: "Round robin" },
    { id: "e", name: "Load Balancer 4", port: 443, rule: "Round robin" },
    { id: "f", name: "Load Balancer 5", port: 80, rule: "DNS delegation" },
  ];

  let selectedRowIds = [rows[0].id, rows[1].id];

  $: console.log("selectedRowIds", selectedRowIds);
</script>

<DataTable batchSelection bind:selectedRowIds {headers} {rows}>
  <Toolbar>
    <ToolbarBatchActions>
      <Button icon={Save}>Save</Button>
    </ToolbarBatchActions>
    <ToolbarContent>
      <ToolbarSearch />
      <ToolbarMenu>
        <ToolbarMenuItem primaryFocus>Restart all</ToolbarMenuItem>
        <ToolbarMenuItem href="https://cloud.ibm.com/docs/loadbalancer-service">
          API documentation
        </ToolbarMenuItem>
        <ToolbarMenuItem hasDivider danger>Stop all</ToolbarMenuItem>
      </ToolbarMenu>
      <Button>Create balancer</Button>
    </ToolbarContent>
  </Toolbar>
</DataTable>
```

### Batch selection with controlled toolbar

Control the batch actions toolbar with the `active` prop. Prevent default cancel
behavior in the `on:cancel` event.

```svelte
<script>
  import {
    Button,
    DataTable,
    Toolbar,
    ToolbarBatchActions,
    ToolbarContent,
  } from "carbon-components-svelte";
  import TrashCan from "carbon-icons-svelte/lib/TrashCan.svelte";

  const headers = [
    { key: "name", value: "Name" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ];

  let rows = [
    { id: "a", name: "Load Balancer 3", port: 3000, rule: "Round robin" },
    { id: "b", name: "Load Balancer 1", port: 443, rule: "Round robin" },
    { id: "c", name: "Load Balancer 2", port: 80, rule: "DNS delegation" },
    { id: "d", name: "Load Balancer 6", port: 3000, rule: "Round robin" },
    { id: "e", name: "Load Balancer 4", port: 443, rule: "Round robin" },
    { id: "f", name: "Load Balancer 5", port: 80, rule: "DNS delegation" },
  ];

  let active = false;
  let selectedRowIds = [];

  $: console.log("active", active);
  $: console.log("selectedRowIds", selectedRowIds);
</script>

<DataTable
  selectable
  batchSelection={active}
  bind:selectedRowIds
  {headers}
  {rows}
>
  <Toolbar>
    <ToolbarBatchActions
      bind:active
      on:cancel={(e) => {
        e.preventDefault();
        active = false;
      }}
    >
      <Button
        icon={TrashCan}
        disabled={selectedRowIds.length === 0}
        on:click={() => {
          rows = rows.filter((row) => !selectedRowIds.includes(row.id));
          selectedRowIds = [];
        }}
      >
        Delete
      </Button>
    </ToolbarBatchActions>
    <ToolbarContent>
      <Button on:click={() => (active = true)}>Edit rows</Button>
    </ToolbarContent>
  </Toolbar>
</DataTable>
```

### Selectable rows (radio)

Set `radio` to `true` for single-row selection. Bind to `selectedRowIds` to
track the selected row. Use `inputName` to customize radio button names.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";

  const headers = [
    { key: "name", value: "Name" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ];

  const rows = [
    { id: "a", name: "Load Balancer 3", port: 3000, rule: "Round robin" },
    { id: "b", name: "Load Balancer 1", port: 443, rule: "Round robin" },
    { id: "c", name: "Load Balancer 2", port: 80, rule: "DNS delegation" },
    { id: "d", name: "Load Balancer 6", port: 3000, rule: "Round robin" },
    { id: "e", name: "Load Balancer 4", port: 443, rule: "Round robin" },
    { id: "f", name: "Load Balancer 5", port: 80, rule: "DNS delegation" },
  ];

  let selectedRowIds = [rows[1].id];

  $: console.log("selectedRowIds", selectedRowIds);
</script>

<DataTable radio bind:selectedRowIds {headers} {rows} />
```

### Non-selectable rows

Use `nonSelectableRowIds` to prevent selection of specific rows.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";

  const rows = [
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ];
</script>

<DataTable
  batchSelection
  nonSelectableRowIds={rows
    .filter((row) => row.port === 3000)
    .map((row) => row.id)}
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  {rows}
/>
```

### Expandable rows

Set `expandable` to `true` to make rows expandable. Use the `expanded-row` slot
to customize expanded content.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  expandable
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
>
  <svelte:fragment slot="expanded-row" let:row>
    <pre>{JSON.stringify(row, null, 2)}</pre>
  </svelte:fragment>
</DataTable>
```

### Non-expandable rows

Use `nonExpandableRowIds` to prevent expansion of specific rows.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";

  const rows = [
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ];
</script>

<DataTable
  batchExpansion
  nonExpandableRowIds={rows
    .filter((row) => row.port < 3000)
    .map((row) => row.id)}
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  {rows}
>
  <svelte:fragment slot="expanded-row" let:row>
    <pre>{JSON.stringify(row, null, 2)}</pre>
  </svelte:fragment>
</DataTable>
```

### Expandable (zebra styles)

Combine expandable rows with zebra striping.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  zebra
  expandable
  nonExpandableRowIds={["a", "d"]}
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
>
  <svelte:fragment slot="expanded-row" let:row>
    <pre>{JSON.stringify(row, null, 2)}</pre>
  </svelte:fragment>
</DataTable>
```

### Expandable (compact size)

Set `size="compact"` for expandable rows with minimal height.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  size="compact"
  expandable
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
>
  <svelte:fragment slot="expanded-row" let:row>
    <pre>{JSON.stringify(row, null, 2)}</pre>
  </svelte:fragment>
</DataTable>
```

### Expandable (short size)

Set `size="short"` for expandable rows with compact height.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  size="short"
  expandable
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
>
  <svelte:fragment slot="expanded-row" let:row>
    <pre>{JSON.stringify(row, null, 2)}</pre>
  </svelte:fragment>
</DataTable>
```

### Expandable (tall size)

Set `size="tall"` for expandable rows with increased height.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  size="tall"
  expandable
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
>
  <svelte:fragment slot="expanded-row" let:row>
    <pre>{JSON.stringify(row, null, 2)}</pre>
  </svelte:fragment>
</DataTable>
```

### Batch expansion

Set `batchExpansion` to `true` to expand and collapse all rows at once.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";
</script>

<DataTable
  batchExpansion
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={[
    {
      id: "a",
      name: "Load Balancer 3",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "b",
      name: "Load Balancer 1",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "c",
      name: "Load Balancer 2",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
    {
      id: "d",
      name: "Load Balancer 6",
      protocol: "HTTP",
      port: 3000,
      rule: "Round robin",
    },
    {
      id: "e",
      name: "Load Balancer 4",
      protocol: "HTTP",
      port: 443,
      rule: "Round robin",
    },
    {
      id: "f",
      name: "Load Balancer 5",
      protocol: "HTTP",
      port: 80,
      rule: "DNS delegation",
    },
  ]}
>
  <svelte:fragment slot="expanded-row" let:row>
    <pre>{JSON.stringify(row, null, 2)}</pre>
  </svelte:fragment>
</DataTable>
```

### Expandable and selectable rows

Combine `batchExpansion` and `batchSelection` for tables with both expandable
and selectable rows.

```svelte
<script>
  import { DataTable } from "carbon-components-svelte";

  let expandedRowIds = [];
  let selectedRowIds = [];

  $: {
    console.log("expandedRowIds", expandedRowIds);
    console.log("selectedRowIds", selectedRowIds);
  }
</script>

<DataTable
  batchExpansion
  batchSelection
  bind:expandedRowIds
  bind:selectedRowIds
  headers={[
    { key: "name", value: "Name" },
    { key: "protocol", value: "Protocol" },
    { key: "port", value: "Port" },
    { key: "rule", value: "Rule" },
  ]}
  rows={Array.from({ length: 6 }).map((_, i) => ({
    id: i,
    name: "Load Balancer " + (i + 1),
    protocol: "HTTP",
    port: i % 3 ? (i % 2 ? 3000 : 80) : 443,
    rule: i % 3 ? "Round robin" : "DNS delegation",
  }))}
>
  <svelte:fragment slot="expanded-row" let:row>
    <pre> {JSON.stringify(row, null, 2)}</pre>
  </svelte:fragment>
</DataTable>
```

### Skeleton

Use the data table skeleton to show a loading state.

```svelte
<script>
  import { DataTableSkeleton } from "carbon-components-svelte";
</script>

<DataTableSkeleton />
```

### Skeleton with headers, row count

Specify headers and row count for the skeleton.

```svelte
<script>
  import { DataTableSkeleton } from "carbon-components-svelte";
</script>

<DataTableSkeleton headers={["Name", "Protocol", "Port", "Rule"]} rows={10} />
```

### Skeleton with object headers

Pass header objects to customize the skeleton.

```svelte
<script>
  import { DataTableSkeleton } from "carbon-components-svelte";
</script>

<DataTableSkeleton
  headers={[
    { value: "Name" },
    { value: "Protocol" },
    { value: "Port" },
    { value: "Rule" },
  ]}
  rows={10}
/>
```

### Skeleton with empty header

Add an empty header column with `empty: true`.

```svelte
<script>
  import { DataTableSkeleton } from "carbon-components-svelte";
</script>

<DataTableSkeleton
  headers={[
    { value: "Name" },
    { value: "Protocol" },
    { value: "Port" },
    { value: "Rule" },
    { empty: true },
  ]}
  rows={10}
/>
```

### Skeleton without header, toolbar

Hide the header and toolbar in the skeleton.

```svelte
<script>
  import { DataTableSkeleton } from "carbon-components-svelte";
</script>

<DataTableSkeleton showHeader={false} showToolbar={false} />
```

### Skeleton (tall size)

Set `size="tall"` for a taller skeleton.

```svelte
<script>
  import { DataTableSkeleton } from "carbon-components-svelte";
</script>

<DataTableSkeleton showHeader={false} showToolbar={false} size="tall" />
```

### Skeleton (short size)

Set `size="short"` for a shorter skeleton.

```svelte
<script>
  import { DataTableSkeleton } from "carbon-components-svelte";
</script>

<DataTableSkeleton showHeader={false} showToolbar={false} size="short" />
```

### Skeleton (compact size)

Set `size="compact"` for a minimal skeleton.

```svelte
<script>
  import { DataTableSkeleton } from "carbon-components-svelte";
</script>

<DataTableSkeleton showHeader={false} showToolbar={false} size="compact" />
```

---

### Component API

#### `DataTable` props

| Prop                            | Type                                                                                                                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Default                             |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `sortKey` (Reactive)            | `DataTableKey<Row>`                                                                                                                                            | Specify the header key to sort by.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `null`                              |
| `sortDirection` (Reactive)      | `"none" \| "ascending" \| "descending"`                                                                                                                        | Specify the sort direction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `"none"`                            |
| `expandable` (Reactive)         | `boolean`                                                                                                                                                      | Set to `true` for the expandable variant.<br />Automatically set to `true` if `batchExpansion` is `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `false`                             |
| `expandedRowIds` (Reactive)     | `ReadonlyArray<Row["id"]>`                                                                                                                                     | Specify the row ids to be expanded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `[]`                                |
| `selectable` (Reactive)         | `boolean`                                                                                                                                                      | Set to `true` for the selectable variant.<br />Automatically set to `true` if `radio` or `batchSelection` are `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `false`                             |
| `selectedRowIds` (Reactive)     | `ReadonlyArray<Row["id"]>`                                                                                                                                     | Specify the row ids to be selected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `[]`                                |
| `scrollContainerRef` (Reactive) | `null \| HTMLDivElement`                                                                                                                                       | Obtain a reference to the table wrapper element. When virtualization is enabled and `stickyHeader` is false, this element is the scroll container—use `bind:scrollContainerRef` to programmatically control scroll position (e.g. `scrollContainerRef.scrollTop = 0`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `null`                              |
| `headers`                       | `ReadonlyArray<DataTableHeader<Row>>`                                                                                                                          | Specify the data table headers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `[]`                                |
| `rows`                          | `ReadonlyArray<Row>`                                                                                                                                           | Specify the rows the data table should render.<br />Keys defined in `headers` are used for the row ids.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `[]`                                |
| `size`                          | `"compact" \| "short" \| "medium" \| "tall"`                                                                                                                   | Set the size of the data table.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | _undefined_                         |
| `title`                         | `string`                                                                                                                                                       | Specify the title of the data table                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `""`                                |
| `description`                   | `string`                                                                                                                                                       | Specify the description of the data table                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `""`                                |
| `rowClass`                      | `DataTableRowClass<Row>`                                                                                                                                       | Specify a custom class name for each row.<br />Provide a function to return a class name based<br />on row properties, allowing conditional classes<br />based on selected/expanded state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | _undefined_                         |
| `inputName`                     | `string`                                                                                                                                                       | Specify a name attribute for the input elements<br />in a selectable data table (radio or checkbox).<br />When the table is inside a form, this name will<br />be included in the form data on submit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `ccs-${Math.random().toString(36)}` |
| `zebra`                         | `boolean`                                                                                                                                                      | Set to `true` to use zebra styles                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `false`                             |
| `sortable`                      | `boolean`                                                                                                                                                      | Set to `true` for the sortable variant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `false`                             |
| `batchExpansion`                | `boolean`                                                                                                                                                      | Set to `true` to enable batch expansion.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                             |
| `nonExpandableRowIds`           | `ReadonlyArray<Row["id"]>`                                                                                                                                     | Specify the ids for rows that should not be expandable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `[]`                                |
| `radio`                         | `boolean`                                                                                                                                                      | Set to `true` for the radio selection variant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `false`                             |
| `batchSelection`                | `boolean`                                                                                                                                                      | Set to `true` to enable batch selection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `false`                             |
| `nonSelectableRowIds`           | `ReadonlyArray<Row["id"]>`                                                                                                                                     | Specify the ids of rows that should not be selectable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `[]`                                |
| `stickyHeader`                  | `boolean`                                                                                                                                                      | Set to `true` to enable a sticky header                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `false`                             |
| `useStaticWidth`                | `boolean`                                                                                                                                                      | Set to `true` to use static width                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `false`                             |
| `pageSize`                      | `number`                                                                                                                                                       | Specify the number of items to display in a page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `0`                                 |
| `page`                          | `number`                                                                                                                                                       | Set to `number` to set current page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `0`                                 |
| `virtualize`                    | `undefined \| boolean \| { itemHeight?: number, maxVisibleRows?: number, containerHeight?: number, overscan?: number, threshold?: number, maxItems?: number }` | Enable virtualization for large row lists. Virtualization renders only the rows currently visible in the viewport, improving performance for large datasets.<br /><br />Virtualization is opt-in. Set `virtualize={true}` to enable with default settings, or pass a configuration object to customize.<br />Virtualized tables are intended for use with `stickyHeader={true}` so the header stays visible while scrolling. Pagination is ignored when virtualization is enabled.<br /><br />Provide an object to customize virtualization behavior:<br />- `itemHeight` (default: 48 for medium size, adjusted for size variant): The height in pixels of each row. Specify a custom value when using custom slots with multi-line content or different heights.<br />- `maxVisibleRows` (default: 10): The maximum number of rows to display in the viewport. The container height will be calculated as `itemHeight * maxVisibleRows`. Overridden by `containerHeight` if explicitly provided.<br />- `containerHeight` (default: calculated from maxVisibleRows): The maximum height in pixels of the table body container. If not provided, calculated from `itemHeight * maxVisibleRows`.<br />- `overscan` (default: 3): The number of extra rows to render above and below the viewport for smoother scrolling. Higher values may cause more flickering during very fast scrolling.<br />- `threshold` (default: 100): The minimum number of rows required before virtualization activates. Tables with fewer rows will render all rows normally without virtualization.<br />- `maxItems` (default: undefined): The maximum number of rows to render. When undefined, all visible rows are rendered. | _undefined_                         |
| `tableHeaderTranslateWithId`    | `(id: import("./TableHeader.svelte").TableHeaderTranslationId) => string`                                                                                      | Override the default table header translation ids.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | _undefined_                         |

#### `DataTable` typedefs

```ts
type DataTableKey<Row = DataTableRow> =
  import("./data-table-utils.d.ts").PropertyPath<Row>;

type DataTableValue = any;

type DataTableEmptyHeader<Row = DataTableRow> = {
  key: DataTableKey<Row> | (string & {});
  /** Whether the header is empty */
  empty: boolean;
  display?: (item: DataTableValue, row: Row) => DataTableValue;
  sort?: false | ((a: DataTableValue, b: DataTableValue) => number);
  /** Whether the column menu is enabled */
  columnMenu?: boolean;
  width?: string;
  minWidth?: string;
};

type DataTableNonEmptyHeader<Row = DataTableRow> = {
  key: DataTableKey<Row>;
  value: DataTableValue;
  display?: (item: DataTableValue, row: Row) => DataTableValue;
  sort?: false | ((a: DataTableValue, b: DataTableValue) => number);
  /** Whether the column menu is enabled */
  columnMenu?: boolean;
  width?: string;
  minWidth?: string;
};

type DataTableHeader<Row = DataTableRow> =
  | DataTableNonEmptyHeader<Row>
  | DataTableEmptyHeader<Row>;

interface DataTableRow<Id = any> {
  id: Id;
  [key: string]: DataTableValue;
}

type DataTableCell<Row = DataTableRow> = {
  key: DataTableKey<Row> | (string & {});
  value: DataTableValue;
  display?: (item: DataTableValue, row: DataTableRow) => DataTableValue;
};

interface DataTableRowClassArgs<Row = DataTableRow> {
  row: Row;
  rowIndex: number;
  selected: boolean;
  expanded: boolean;
}

type DataTableRowClass<Row = DataTableRow> =
  | string
  | ((row: DataTableRowClassArgs<Row>) => string | undefined);
```

#### `DataTable` slots

| Slot                  | Detail                                                                                                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default`             | `Record<string, never>`                                                                                                                                             |
| `cell`                | `{<br /> row: Row;<br /> cell: DataTableCell<Row>;<br /> rowIndex: number;<br /> cellIndex: number;<br /> rowSelected: boolean;<br /> rowExpanded: boolean;<br />}` |
| `cellHeader`          | `{<br /> header: DataTableNonEmptyHeader;<br />}`                                                                                                                   |
| `descriptionChildren` | `{<br /> props: {<br /> class: "bx--data-table-header__description";<br /> };<br />}`                                                                               |
| `expanded-row`        | `{<br /> row: Row;<br /> rowSelected: boolean;<br />}`                                                                                                              |
| `titleChildren`       | `{<br /> props: {<br /> class: "bx--data-table-header__title";<br /> };<br />}`                                                                                     |

#### `DataTable` dispatched events

| Event                     | Detail                                                                                                                                                                                        |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `on:click`                | `{<br /> header?: DataTableHeader<Row>;<br /> row?: Row;<br /> cell?: DataTableCell<Row>;<br />}`                                                                                             |
| `on:click:header--expand` | `{<br /> expanded: boolean;<br />}`                                                                                                                                                           |
| `on:click:header`         | `{<br /> header: DataTableHeader<Row>;<br /> sortDirection?:<br /> \| "ascending"<br /> \| "descending"<br /> \| "none";<br /> target: EventTarget;<br /> currentTarget: EventTarget;<br />}` |
| `on:click:header--select` | `{<br /> indeterminate: boolean;<br /> selected: boolean;<br />}`                                                                                                                             |
| `on:click:row`            | `{<br /> row: Row;<br /> target: EventTarget;<br /> currentTarget: EventTarget;<br />}`                                                                                                       |
| `on:mouseenter:row`       | `Row`                                                                                                                                                                                         |
| `on:mouseleave:row`       | `Row`                                                                                                                                                                                         |
| `on:click:row--expand`    | `{<br /> expanded: boolean;<br /> row: Row;<br />}`                                                                                                                                           |
| `on:click:row--select`    | `{<br /> selected: boolean;<br /> row: Row;<br />}`                                                                                                                                           |
| `on:click:cell`           | `{<br /> cell: DataTableCell<Row>;<br /> target: EventTarget;<br /> currentTarget: EventTarget;<br /> rowClass?: DataTableRowClass<Row>;<br />}`                                              |

#### `DataTable` $$restProps

`DataTable` spreads `$$restProps` to the `div` element.

#### `Pagination` props

| Prop                    | Type                                                  | Description                                                                                                                                                                                                                                                                                                                                         | Default                             |
| ----------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `page` (Reactive)       | `number`                                              | Specify the current page index                                                                                                                                                                                                                                                                                                                      | `1`                                 |
| `pageSize` (Reactive)   | `number`                                              | Specify the number of items to display in a page                                                                                                                                                                                                                                                                                                    | `10`                                |
| `totalItems`            | `number`                                              | Specify the total number of items                                                                                                                                                                                                                                                                                                                   | `0`                                 |
| `pageWindow`            | `number`                                              | If `totalItems` is a large number, it can affect the<br />rendering performance of this component since its value<br />is used to calculate the number of pages in the native<br />select dropdown. This value creates a small window of<br />pages rendered around the current page. By default,<br />a maximum of 1000 select items are rendered. | `1000`                              |
| `disabled`              | `boolean`                                             | Set to `true` to disable the pagination                                                                                                                                                                                                                                                                                                             | `false`                             |
| `forwardText`           | `string`                                              | Specify the forward button text                                                                                                                                                                                                                                                                                                                     | `"Next page"`                       |
| `backwardText`          | `string`                                              | Specify the backward button text                                                                                                                                                                                                                                                                                                                    | `"Previous page"`                   |
| `itemsPerPageText`      | `string`                                              | Specify the items per page text                                                                                                                                                                                                                                                                                                                     | `"Items per page:"`                 |
| `itemText`              | `(min: number, max: number) => string`                | Override the item text.                                                                                                                                                                                                                                                                                                                             | _undefined_                         |
| `itemRangeText`         | `(min: number, max: number, total: number) => string` | Override the item range text.                                                                                                                                                                                                                                                                                                                       | _undefined_                         |
| `pageInputDisabled`     | `boolean`                                             | Set to `true` to disable the page input                                                                                                                                                                                                                                                                                                             | `false`                             |
| `pageSizeInputDisabled` | `boolean`                                             | Set to `true` to disable the page size input                                                                                                                                                                                                                                                                                                        | `false`                             |
| `pageSizes`             | `ReadonlyArray<number>`                               | Specify the available page sizes.                                                                                                                                                                                                                                                                                                                   | `[10]`                              |
| `dynamicPageSizes`      | `boolean`                                             | Set to `true` to dynamically filter page sizes based on total items.<br />Page sizes larger than needed to display all items on a single page are hidden.                                                                                                                                                                                           | `false`                             |
| `pagesUnknown`          | `boolean`                                             | Set to `true` if the number of pages is unknown                                                                                                                                                                                                                                                                                                     | `false`                             |
| `pageText`              | `(page: number) => string`                            | Override the page text.                                                                                                                                                                                                                                                                                                                             | _undefined_                         |
| `pageRangeText`         | `(current: number, total: number) => string`          | Override the page range text.                                                                                                                                                                                                                                                                                                                       | _undefined_                         |
| `id`                    | `string`                                              | Set an id for the top-level element                                                                                                                                                                                                                                                                                                                 | `ccs-${Math.random().toString(36)}` |

#### `Pagination` dispatched events

| Event                       | Detail                                                   | Description                                                                     |
| --------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `on:change`                 | `{<br /> page?: number;<br /> pageSize?: number;<br />}` | Dispatched when the user changes the page or page size through any interaction. |
| `on:click:button--previous` | `{<br /> page: number;<br />}`                           | Dispatched when the user clicks the previous page button.                       |
| `on:click:button--next`     | `{<br /> page: number;<br />}`                           | Dispatched when the user clicks the next page button.                           |
| `on:update`                 | `{<br /> pageSize: number;<br /> page: number;<br />}`   | Dispatched reactively whenever the page or page size changes.                   |

#### `Pagination` $$restProps

`Pagination` spreads `$$restProps` to the `div` element.

#### `Toolbar` props

| Prop   | Type                | Description               | Default     |
| ------ | ------------------- | ------------------------- | ----------- |
| `size` | `"sm" \| "default"` | Specify the toolbar size. | `"default"` |

#### `Toolbar` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `Toolbar` $$restProps

`Toolbar` spreads `$$restProps` to the `section` element.

#### `ToolbarContent` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ToolbarSearch` props

| Prop                        | Type                                                          | Description                                                                                                                                                                                                                                                                                                                                     | Default |
| --------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `value` (Reactive)          | `number \| string`                                            | Specify the value of the search input.                                                                                                                                                                                                                                                                                                          | `""`    |
| `expanded` (Reactive)       | `boolean`                                                     | Set to `true` to expand the search bar                                                                                                                                                                                                                                                                                                          | `false` |
| `filteredRowIds` (Reactive) | `ReadonlyArray<Row["id"]>`                                    | The filtered row ids.                                                                                                                                                                                                                                                                                                                           | `[]`    |
| `ref` (Reactive)            | `null \| HTMLInputElement`                                    | Obtain a reference to the input HTML element.                                                                                                                                                                                                                                                                                                   | `null`  |
| `persistent`                | `boolean`                                                     | Set to `true` to keep the search bar expanded                                                                                                                                                                                                                                                                                                   | `false` |
| `disabled`                  | `boolean`                                                     | Set to `true` to disable the search bar                                                                                                                                                                                                                                                                                                         | `false` |
| `shouldFilterRows`          | `boolean \| ((row: Row, value: number \| string) => boolean)` | Set to `true` to filter table rows using the search value.<br /><br />If `true`, the default search excludes `id`, `cells` fields and<br />only does a basic comparison on string and number type cell values.<br /><br />To implement your own client-side filtering, pass a function<br />that accepts a row and value and returns a boolean. | `false` |
| `tabindex`                  | `string`                                                      | Specify the tabindex                                                                                                                                                                                                                                                                                                                            | `"0"`   |

#### `ToolbarSearch` forwarded events

| Event        |
| ------------ |
| `on:clear`   |
| `on:change`  |
| `on:input`   |
| `on:focus`   |
| `on:blur`    |
| `on:keyup`   |
| `on:keydown` |
| `on:paste`   |

#### `ToolbarSearch` $$restProps

`ToolbarSearch` spreads `$$restProps` to the `input` element.

#### `ToolbarMenu` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ToolbarMenu` $$restProps

`ToolbarMenu` spreads `$$restProps` to the `OverflowMenu` component.

#### `ToolbarMenuItem` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ToolbarMenuItem` forwarded events

| Event        |
| ------------ |
| `on:click`   |
| `on:keydown` |

#### `ToolbarMenuItem` $$restProps

`ToolbarMenuItem` spreads `$$restProps` to the `OverflowMenuItem` component.

#### `ToolbarBatchActions` props

| Prop                  | Type                                | Description                                                                                                       | Default     |
| --------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------- |
| `active` (Reactive)   | `undefined \| boolean`              | Use a boolean to show or hide the toolbar.                                                                        | _undefined_ |
| `formatTotalSelected` | `(totalSelected: number) => string` | Override the total items selected text.                                                                           | _undefined_ |
| `selectedIds`         | `ReadonlyArray<any>`                | Specify the selected IDs for standalone usage.<br />This is unnecessary if using this component with `DataTable`. | `[]`        |

#### `ToolbarBatchActions` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |
| `cancel`  | `Record<string, never>` |

#### `ToolbarBatchActions` dispatched events

| Event       | Detail |
| ----------- | ------ |
| `on:cancel` | `null` |

#### `ToolbarBatchActions` $$restProps

`ToolbarBatchActions` spreads `$$restProps` to the `div` element.


## DatePicker

Date pickers let users select a date or date range using a calendar interface.
They use the [flatpickr](https://github.com/flatpickr/flatpickr) library for
their calendar implementation.

> [!NOTE] If using Rollup, specify **inlineDynamicImports: true** in your
> **rollup.config.js**.

### Single

Set `datePickerType` to `"single"` for single date selection.

```svelte
<script>
  import { DatePicker, DatePickerInput } from "carbon-components-svelte";
</script>

<DatePicker datePickerType="single" on:change>
  <DatePickerInput labelText="Meeting date" placeholder="mm/dd/yyyy" />
</DatePicker>
```

### Range

Set `datePickerType` to `"range"` to enable date range selection.

```svelte
<script>
  import { DatePicker, DatePickerInput } from "carbon-components-svelte";
</script>

<DatePicker datePickerType="range" on:change>
  <DatePickerInput labelText="Start date" placeholder="mm/dd/yyyy" />
  <DatePickerInput labelText="End date" placeholder="mm/dd/yyyy" />
</DatePicker>
```

### Programmatic range update

Use `bind:valueFrom` and `bind:valueTo` to programmatically update the date
range from outside the component.

```svelte
<script>
  import {
    Button,
    DatePicker,
    DatePickerInput,
    Stack,
  } from "carbon-components-svelte";

  let valueFrom = "01/01/2024";
  let valueTo = "01/31/2024";

  function advanceMonth(value) {
    var d = new Date(value);
    var month = d.getMonth() + 1;
    var year = d.getFullYear() + (month > 11 ? 1 : 0);
    month = month % 12;
    var lastDay = new Date(year, month + 1, 0).getDate();
    var day = Math.min(d.getDate(), lastDay);
    var mm = String(month + 1).padStart(2, "0");
    var dd = String(day).padStart(2, "0");
    return `${mm}/${dd}/${year}`;
  }

  function nextMonth() {
    valueFrom = advanceMonth(valueFrom);
    valueTo = advanceMonth(valueTo);
  }
</script>

<Stack gap={4}>
  <DatePicker datePickerType="range" bind:valueFrom bind:valueTo on:change>
    <DatePickerInput labelText="Start date" placeholder="mm/dd/yyyy" />
    <DatePickerInput labelText="End date" placeholder="mm/dd/yyyy" />
  </DatePicker>
  <Button on:click={nextMonth}>Next month</Button>
</Stack>
```

### Custom date format

Use the `dateFormat` prop to customize the date format (default: `"m/d/Y"`). The
input `pattern` attribute is automatically derived to match, ensuring native
form validation works correctly.

```svelte
<script>
  import {
    Button,
    DatePicker,
    DatePickerInput,
    Stack,
  } from "carbon-components-svelte";

  let value = "";
  let submittedValue = "";
</script>

<form on:submit|preventDefault={() => (submittedValue = value)}>
  <Stack inline gap={4}>
    <DatePicker bind:value datePickerType="single" dateFormat="Y-m-d">
      <DatePickerInput
        labelText="Date of birth"
        placeholder="yyyy-mm-dd"
        helperText={submittedValue ? `Submitted: ${submittedValue}` : ""}
      />
    </DatePicker>
    <Button type="submit" disabled={!value}>Submit</Button>
  </Stack>
</form>
```

### Portal menu

Set `portalMenu` to `true` to render the calendar in a floating portal. This
prevents the calendar from being clipped by parent containers with
`overflow: hidden` or z-index stacking contexts. When inside a Modal,
`portalMenu` defaults to `true` unless explicitly set to `false`.

```svelte
<script>
  import {
    Button,
    DatePicker,
    DatePickerInput,
    Modal,
  } from "carbon-components-svelte";

  let open = false;
</script>

<Button on:click={() => (open = true)}>Select date</Button>

<Modal
  bind:open
  size="sm"
  modalHeading="Meeting date"
  primaryButtonText="Confirm"
  secondaryButtonText="Cancel"
  on:click:button--secondary={() => (open = false)}
>
  <DatePicker datePickerType="single">
    <DatePickerInput labelText="Meeting date" placeholder="mm/dd/yyyy" />
  </DatePicker>
</Modal>
```

### Simple

Create a simple date picker without a dropdown calendar.

```svelte
<script>
  import { DatePicker, DatePickerInput } from "carbon-components-svelte";
</script>

<DatePicker>
  <DatePickerInput labelText="Date of birth" placeholder="mm/dd/yyyy" />
</DatePicker>
```

### With helper text

Add helper text to provide additional context or formatting instructions.

```svelte
<script>
  import { DatePicker, DatePickerInput } from "carbon-components-svelte";
</script>

<DatePicker>
  <DatePickerInput
    labelText="Date of birth"
    helperText="Example: 01/12/1990"
    placeholder="mm/dd/yyyy"
  />
</DatePicker>
```

### Hidden label

Hide the label while maintaining accessibility.

```svelte
<script>
  import { DatePicker, DatePickerInput } from "carbon-components-svelte";
</script>

<DatePicker>
  <DatePickerInput
    hideLabel
    labelText="Date of birth"
    placeholder="mm/dd/yyyy"
  />
</DatePicker>
```

### Light variant

Use the light variant for light backgrounds.

```svelte
<script>
  import { DatePicker, DatePickerInput } from "carbon-components-svelte";
</script>

<DatePicker light>
  <DatePickerInput labelText="Date of birth" placeholder="mm/dd/yyyy" />
</DatePicker>
```

### Extra-large size

Use the extra-large size for more prominent date pickers.

```svelte
<script>
  import { DatePicker, DatePickerInput } from "carbon-components-svelte";
</script>

<DatePicker>
  <DatePickerInput
    size="xl"
    labelText="Date of birth"
    placeholder="mm/dd/yyyy"
  />
</DatePicker>
```

### Small size

Use the small size for compact date pickers.

```svelte
<script>
  import { DatePicker, DatePickerInput } from "carbon-components-svelte";
</script>

<DatePicker>
  <DatePickerInput
    size="sm"
    labelText="Date of birth"
    placeholder="mm/dd/yyyy"
  />
</DatePicker>
```

### Invalid state

Show an invalid state when the input value is not valid.

```svelte
<script>
  import { DatePicker, DatePickerInput } from "carbon-components-svelte";
</script>

<DatePicker>
  <DatePickerInput
    invalid
    invalidText="Invalid date"
    labelText="Date of birth"
    placeholder="mm/dd/yyyy"
  />
</DatePicker>
```

### Warning state

Show a warning state to indicate potential issues with the input.

```svelte
<script>
  import { DatePicker, DatePickerInput } from "carbon-components-svelte";
</script>

<DatePicker>
  <DatePickerInput
    warn
    warnText="This info will not be stored"
    labelText="Date of birth"
    placeholder="mm/dd/yyyy"
  />
</DatePicker>
```

### Disabled state

Disable the date picker to prevent user interaction.

```svelte
<script>
  import { DatePicker, DatePickerInput } from "carbon-components-svelte";
</script>

<DatePicker>
  <DatePickerInput
    disabled
    labelText="Date of birth"
    placeholder="mm/dd/yyyy"
  />
</DatePicker>
```

### Skeleton

Show a loading state with the skeleton component.

```svelte
<script>
  import { DatePickerSkeleton } from "carbon-components-svelte";
</script>

<DatePickerSkeleton />
```

---

### Component API

#### `DatePicker` props

| Prop                   | Type                                                                                              | Description                                                                                                                                          | Default                             |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `value` (Reactive)     | `number \| string`                                                                                | Specify the date picker input value.                                                                                                                 | `""`                                |
| `valueFrom` (Reactive) | `string`                                                                                          | Specify the date picker start date value (from).<br />Only works with the "range" date picker type.                                                  | `""`                                |
| `valueTo` (Reactive)   | `string`                                                                                          | Specify the date picker end date value (to).<br />Only works with the "range" date picker type.                                                      | `""`                                |
| `datePickerType`       | `"simple" \| "single" \| "range"`                                                                 | Specify the date picker type.                                                                                                                        | `"simple"`                          |
| `dateFormat`           | `string`                                                                                          | Specify the date format                                                                                                                              | `"m/d/Y"`                           |
| `maxDate`              | `null \| string \| Date`                                                                          | Specify the maximum date.                                                                                                                            | `null`                              |
| `minDate`              | `null \| string \| Date`                                                                          | Specify the minimum date.                                                                                                                            | `null`                              |
| `locale`               | `import("flatpickr/dist/types/locale").CustomLocale \| import("flatpickr/dist/types/locale").key` | Specify the locale.                                                                                                                                  | `"en"`                              |
| `short`                | `boolean`                                                                                         | Set to `true` to use the short variant                                                                                                               | `false`                             |
| `light`                | `boolean`                                                                                         | Set to `true` to enable the light variant                                                                                                            | `false`                             |
| `portalMenu`           | `boolean \| undefined`                                                                            | Set to `true` to render the calendar in a portal to prevent clipping.<br />When inside a Modal, defaults to `true` unless explicitly set to `false`. | _undefined_                         |
| `id`                   | `string`                                                                                          | Set an id for the date picker element                                                                                                                | `ccs-${Math.random().toString(36)}` |
| `flatpickrProps`       | `import("flatpickr/dist/types/options").Options`                                                  | Override the options passed to the Flatpickr instance.<br />@see https://flatpickr.js.org/options                                                    | `{ static: true }`                  |

#### `DatePicker` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `DatePicker` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `DatePicker` dispatched events

| Event       | Detail                                                                                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `on:change` | `type EventDetail =<br /> \| string<br /> \| {<br /> selectedDates: [<br /> dateFrom: Date,<br /> dateTo?: Date,<br /> ];<br /> dateStr:<br /> \| string<br /> \| { from: string; to: string };<br /> }` |

#### `DatePicker` $$restProps

`DatePicker` spreads `$$restProps` to the `div` element.

#### `DatePickerInput` props

| Prop              | Type                       | Description                                                                                                                                        | Default                             |
| ----------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `ref` (Reactive)  | `null \| HTMLInputElement` | Obtain a reference to the input HTML element                                                                                                       | `null`                              |
| `size`            | `"sm" \| "xl"`             | Set the size of the input.                                                                                                                         | _undefined_                         |
| `type`            | `string`                   | Specify the input type                                                                                                                             | `"text"`                            |
| `placeholder`     | `string`                   | Specify the input placeholder text                                                                                                                 | `""`                                |
| `pattern`         | `string`                   | Specify the Regular Expression for the input value.<br />By default, the pattern is derived from the parent<br />`DatePicker`'s `dateFormat` prop. | _undefined_                         |
| `disabled`        | `boolean`                  | Set to `true` to disable the input                                                                                                                 | `false`                             |
| `helperText`      | `string`                   | Specify the helper text                                                                                                                            | `""`                                |
| `iconDescription` | `string`                   | Specify the ARIA label for the calendar icon                                                                                                       | `""`                                |
| `id`              | `string`                   | Set an id for the input element                                                                                                                    | `ccs-${Math.random().toString(36)}` |
| `labelText`       | `string`                   | Specify the label text                                                                                                                             | `""`                                |
| `hideLabel`       | `boolean`                  | Set to `true` to visually hide the label text                                                                                                      | `false`                             |
| `invalid`         | `boolean`                  | Set to `true` to indicate an invalid state                                                                                                         | `false`                             |
| `invalidText`     | `string`                   | Specify the invalid state text                                                                                                                     | `""`                                |
| `warn`            | `boolean`                  | Set to `true` to indicate a warning state                                                                                                          | `false`                             |
| `warnText`        | `string`                   | Specify the warning state text                                                                                                                     | `""`                                |
| `name`            | `string`                   | Set a name for the input element.                                                                                                                  | _undefined_                         |

#### `DatePickerInput` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `labelChildren` | `Record<string, never>` |

#### `DatePickerInput` forwarded events

| Event        |
| ------------ |
| `on:input`   |
| `on:keydown` |
| `on:keyup`   |
| `on:blur`    |
| `on:paste`   |

#### `DatePickerInput` $$restProps

`DatePickerInput` spreads `$$restProps` to the `input` element.

#### `DatePickerSkeleton` props

| Prop    | Type      | Description                               | Default                             |
| ------- | --------- | ----------------------------------------- | ----------------------------------- |
| `range` | `boolean` | Set to `true` to use the range variant    | `false`                             |
| `id`    | `string`  | Set an id to be used by the label element | `ccs-${Math.random().toString(36)}` |

#### `DatePickerSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `DatePickerSkeleton` $$restProps

`DatePickerSkeleton` spreads `$$restProps` to the `div` element.


## Dropdown

Dropdowns provide a select input with a dropdown menu. They support various
states, sizes, and customization options. Each item in the dropdown must have a
unique `id` property for proper functionality.

> [!NOTE] Every `items` object must have a unique "id" property.

### Default

Use the dropdown to create a select input with a dropdown menu. Each item must
have a unique `id` property.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";
</script>

<Dropdown
  labelText="Contact"
  selectedId="0"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Custom label

Use the `labelChildren` slot to provide custom label content instead of using
the `labelText` prop.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";
</script>

<Dropdown
  selectedId="0"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
>
  <strong slot="labelChildren">Custom label</strong>
</Dropdown>
```

### Custom slot

Override the default slot to customize the display of each item. Access the item
and index through the `let:` directive.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";
</script>

<Dropdown
  labelText="Contact"
  selectedId="0"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
  let:item
  let:index
>
  <div>
    <strong>{item.text}</strong>
  </div>
  <div>
    id: {item.id} - index:
    {index}
  </div>
</Dropdown>

<style>
  :global(.bx--list-box__menu-item, .bx--list-box__menu-item__option) {
    height: auto;
  }
</style>
```

### Hidden label

Hide the label while maintaining accessibility by setting the `hideLabel` prop
to `true`. The label will still be available to screen readers.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";
</script>

<Dropdown
  hideLabel
  labelText="Contact"
  selectedId="0"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Format item display text

Format the display text of items using the `itemToString` prop. This function
receives the item object and returns the formatted string.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";
</script>

<Dropdown
  itemToString={(item) => {
    return item.text + " (" + item.id + ")";
  }}
  labelText="Contact"
  selectedId="0"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>

## Multiple dropdowns Create multiple dropdowns that work together. This example
demonstrates how to manage the state of multiple dropdowns.
```

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";

  const items = [
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ];

  let dropdown1_selectedId = "0";
  let dropdown2_selectedId = "1";

  const formatSelected = (id) =>
    items.find((item) => item.id === id)?.text ?? "N/A";

  $: primary = formatSelected(dropdown1_selectedId);
  $: secondary = formatSelected(dropdown2_selectedId);
</script>

<Dropdown
  labelText="Primary contact"
  bind:selectedId={dropdown1_selectedId}
  {items}
/>

<div>Primary: {primary}</div>

<Dropdown
  invalid={dropdown1_selectedId === dropdown2_selectedId}
  invalidText="Secondary contact method must be different from the primary contact"
  labelText="Secondary contact"
  bind:selectedId={dropdown2_selectedId}
  {items}
/>

<div>Secondary: {secondary}</div>

<style>
  div {
    margin: var(--cds-layout-01) 0 var(--cds-layout-03);
  }
</style>
```

### Top direction

Display the dropdown menu above the input by setting the `direction` prop to
`"top"`. This is useful when there's limited space below the input.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";
</script>

<Dropdown
  direction="top"
  labelText="Contact"
  selectedId="0"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Light variant

Use the light variant for dropdowns on dark backgrounds by setting the `light`
prop to `true`.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";
</script>

<Dropdown
  light
  labelText="Contact"
  selectedId="0"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Portal menu

Set `portalMenu` to `true` to render the dropdown menu in a floating portal.
This prevents the menu from being clipped by parent containers with
`overflow: hidden` or z-index stacking contexts. The example below shows a
container with hidden overflow. Without `portalMenu`, the dropdown would be
clipped.

When inside a [Modal](/components/Modal#modal-with-dropdowns), `portalMenu`
defaults to `true` unless explicitly set to `false`.

```svelte
<script>
  import { Dropdown, Stack } from "carbon-components-svelte";
</script>

<Stack
  gap={4}
  style="overflow: hidden; border: 1px dashed var(--cds-border-subtle); padding: 1rem; max-height: 120px;"
>
  <div>
    This container has hidden overflow. Without <code>portalMenu</code>, the
    dropdown would be clipped.
  </div>
  <Dropdown
    portalMenu
    labelText="Preferred channel"
    selectedId="0"
    items={[
      { id: "0", text: "Slack" },
      { id: "1", text: "Email" },
      { id: "2", text: "Fax" },
    ]}
  />
</Stack>
```

### Inline variant

Display the dropdown inline with other content by setting the `type` prop to
`"inline"`. This variant removes the background and border.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";
</script>

<Dropdown
  type="inline"
  labelText="Contact"
  selectedId="0"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Extra-large size

Increase the size of the dropdown by setting the `size` prop to `"xl"`. This
provides more visual emphasis for important selections.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";
</script>

<Dropdown
  size="xl"
  labelText="Contact"
  selectedId="0"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Small size

Decrease the size of the dropdown by setting the `size` prop to `"sm"`. This is
useful for compact layouts or secondary selections.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";
</script>

<Dropdown
  size="sm"
  labelText="Contact"
  selectedId="0"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Invalid state

Indicate an invalid selection by setting the `invalid` prop to `true`. Provide
feedback to users with the `invalidText` prop.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";
</script>

<Dropdown
  invalid
  invalidText="Secondary contact method must be different from the primary contact"
  labelText="Contact"
  selectedId="0"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Warning state

Indicate a warning state by setting the `warn` prop to `true`. Provide
additional context with the `warnText` prop.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";
</script>

<Dropdown
  warn
  warnText="This contact method is not associated with your account"
  labelText="Contact"
  selectedId="0"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Disabled state

Disable the entire dropdown by setting the `disabled` prop to `true`. This
prevents user interaction with the component.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";
</script>

<Dropdown
  disabled
  labelText="Contact"
  selectedId="0"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Disabled items

Disable specific items in the dropdown by setting the `disabled` property to
`true` in the item object. This allows for more granular control over available
selections.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";
</script>

<Dropdown
  selectedId="0"
  labelText="Contact"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email", disabled: true },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Virtualized items (large lists)

Virtualization is a technique that allows only the items currently visible in
the viewport to be rendered in the DOM, improving performance for large lists.

By default, the dropdown will virtualize lists with more than 100 items.

In the example below, 10,000 items are provided to the dropdown but only 11
items (8 visible items + 3 overscan items) are rendered in the DOM.

Set `virtualize={false}` to explicitly disable virtualization, even for large
lists. Or, customize the threshold at which virtualization activates. See
[Virtualized items (custom threshold)](#virtualized-items-custom-threshold).

```svelte
<script>
  import { Dropdown, Stack } from "carbon-components-svelte";

  const items = Array.from({ length: 10_000 }, (_, i) => ({
    id: i,
    text: `Item ${i + 1}`,
  }));

  let selectedId = 1000;
  $: selectedItem = items.find((item) => item.id === selectedId);
</script>

<Stack gap={5}>
  <Dropdown
    labelText="Virtualized Dropdown (10,000 items)"
    {items}
    bind:selectedId
  />
  <div>
    <strong>Selected:</strong>
    {selectedItem?.text}
  </div>
</Stack>
```

### Virtualized items (custom overscan)

Overscanning is the process of rendering extra items above and below the
viewport to ensure smooth scrolling. The default overscan value is 3.

Specify a custom value for `overscan` to control how many extra items are
rendered above/below the viewport for smoother scrolling.

> [!NOTE] During very fast scrolling, higher overscan values may cause more
> flickering due to increased DOM updates. For fast scrolling scenarios, use a
> lower overscan value.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";

  const items = Array.from({ length: 10_000 }, (_, i) => ({
    id: i,
    text: `Item ${i + 1}`,
  }));

  let selectedId = 1000;
</script>

<Dropdown
  virtualize={{ overscan: 100 }}
  labelText="High overscan (10,000 items, overscan: 100)"
  {items}
  bind:selectedId
/>
```

### Virtualized items (custom threshold)

The threshold is the minimum number of items required before virtualization
activates. The default threshold value is 100, meaning lists with fewer than 100
items will not be virtualized and all items will be rendered normally.

Specify a custom value for `threshold` to control when virtualization activates.
Below the threshold, all items are rendered normally without virtualization.

```svelte
<script>
  import { Dropdown } from "carbon-components-svelte";

  const items = Array.from({ length: 100 }, (_, i) => ({
    id: i,
    text: `Item ${i + 1}`,
  }));

  let selectedId = 50;
</script>

<Dropdown
  virtualize={{ threshold: 200 }}
  labelText="Custom threshold (threshold: 200)"
  {items}
  bind:selectedId
/>
```

### Virtualized items (custom item height)

The default item height for virtualization is 40 pixels. When using custom slots
to render items with different heights (e.g., multi-line items with
descriptions), specify a custom `itemHeight` value to match your item's actual
height.

```svelte
<script>
  import { Dropdown, Stack } from "carbon-components-svelte";

  const items = Array.from({ length: 10_000 }, (_, i) => ({
    id: i,
    text: `Item ${i + 1}`,
    description: `Description for item ${i + 1}`,
  }));

  let selectedId = 1000;
</script>

<Dropdown
  virtualize={{ itemHeight: 60 }}
  labelText="Custom item height (60px)"
  {items}
  bind:selectedId
  let:item
>
  <Stack gap={2}>
    <strong>{item.text}</strong>
    <span>{item.description}</span>
  </Stack>
</Dropdown>
```

### Skeleton

Display a loading state using the dropdown skeleton. This provides visual
feedback while the dropdown content is being loaded.

```svelte
<script>
  import { DropdownSkeleton } from "carbon-components-svelte";
</script>

<DropdownSkeleton />
```

---

### Component API

#### `Dropdown` props

| Prop                              | Type                                                                                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Default                             |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `selectedId` (Reactive, Required) | `Item["id"]`                                                                                                                          | Specify the selected item id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | _undefined_                         |
| `open` (Reactive)                 | `boolean`                                                                                                                             | Set to `true` to open the dropdown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `false`                             |
| `ref` (Reactive)                  | `null \| HTMLButtonElement`                                                                                                           | Obtain a reference to the button HTML element                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `null`                              |
| `listRef` (Reactive)              | `null \| HTMLDivElement`                                                                                                              | Obtain a reference to the list HTML element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `null`                              |
| `items`                           | `ReadonlyArray<Item>`                                                                                                                 | Set the dropdown items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `[]`                                |
| `itemToString`                    | `(item: Item) => string`                                                                                                              | Override the display of a dropdown item.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | _undefined_                         |
| `type`                            | `"default" \| "inline"`                                                                                                               | Specify the type of dropdown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `"default"`                         |
| `direction`                       | `"bottom" \| "top"`                                                                                                                   | Specify the direction of the dropdown menu.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `"bottom"`                          |
| `size`                            | `"sm" \| "lg" \| "xl"`                                                                                                                | Specify the size of the dropdown field.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | _undefined_                         |
| `light`                           | `boolean`                                                                                                                             | Set to `true` to enable the light variant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                             |
| `disabled`                        | `boolean`                                                                                                                             | Set to `true` to disable the dropdown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `false`                             |
| `labelText`                       | `string`                                                                                                                              | Specify the title text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `""`                                |
| `invalid`                         | `boolean`                                                                                                                             | Set to `true` to indicate an invalid state                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `false`                             |
| `invalidText`                     | `string`                                                                                                                              | Specify the invalid state text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `""`                                |
| `warn`                            | `boolean`                                                                                                                             | Set to `true` to indicate a warning state                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                             |
| `warnText`                        | `string`                                                                                                                              | Specify the warning state text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `""`                                |
| `helperText`                      | `string`                                                                                                                              | Specify the helper text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `""`                                |
| `label`                           | `string`                                                                                                                              | Specify the list box label.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | _undefined_                         |
| `hideLabel`                       | `boolean`                                                                                                                             | Set to `true` to visually hide the label text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `false`                             |
| `translateWithId`                 | `(id: import("../ListBox/ListBoxMenuIcon.svelte").ListBoxMenuIconTranslationId) => string`                                            | Override the chevron icon label based on the open state.<br />Defaults to "Open menu" when closed and "Close menu" when open.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | _undefined_                         |
| `virtualize`                      | `undefined \| boolean \| { itemHeight?: number, containerHeight?: number, overscan?: number, threshold?: number, maxItems?: number }` | Enable virtualization for large lists. Virtualization renders only the items currently visible in the viewport, improving performance for large lists.<br /><br />By default, virtualization is automatically enabled for lists with more than 100 items.<br /><br />Set `virtualize={false}` to explicitly disable virtualization, even for large lists.<br /><br />Set `virtualize={true}` to explicitly enable virtualization with default settings.<br /><br />Provide an object to customize virtualization behavior:<br />- `itemHeight` (default: 40): The height in pixels of each item. Specify a custom value when using custom slots with multi-line items or different heights.<br />- `containerHeight` (default: 300): The maximum height in pixels of the dropdown container.<br />- `overscan` (default: 3): The number of extra items to render above and below the viewport for smoother scrolling. Higher values may cause more flickering during very fast scrolling.<br />- `threshold` (default: 100): The minimum number of items required before virtualization activates. Lists with fewer items will render all items normally without virtualization.<br />- `maxItems` (default: undefined): The maximum number of items to render. When undefined, all visible items are rendered. | _undefined_                         |
| `portalMenu`                      | `boolean \| undefined`                                                                                                                | Set to `true` to render the dropdown menu in a portal,<br />allowing it to escape containers with `overflow: hidden`.<br />When inside a Modal, defaults to `true` unless explicitly set to `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | _undefined_                         |
| `id`                              | `string`                                                                                                                              | Set an id for the list box component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `ccs-${Math.random().toString(36)}` |
| `name`                            | `string`                                                                                                                              | Specify a name attribute for the list box.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | _undefined_                         |

#### `Dropdown` typedefs

```ts
type DropdownItem<Id = any> = {
  id: Id;
  text: string;
  /** Whether the item is disabled */
  disabled?: boolean;
};
```

#### `Dropdown` slots

| Slot            | Detail                                            |
| --------------- | ------------------------------------------------- |
| `default`       | `{<br /> item: Item;<br /> index: number;<br />}` |
| `labelChildren` | `Record<string, never>`                           |

#### `Dropdown` forwarded events

| Event       |
| ----------- |
| `on:scroll` |

#### `Dropdown` dispatched events

| Event       | Detail                                                             |
| ----------- | ------------------------------------------------------------------ |
| `on:select` | `{<br /> selectedId: Item["id"];<br /> selectedItem: Item;<br />}` |

#### `Dropdown` $$restProps

`Dropdown` spreads `$$restProps` to the `div` element.

#### `DropdownSkeleton` props

| Prop     | Type      | Description                             | Default |
| -------- | --------- | --------------------------------------- | ------- |
| `inline` | `boolean` | Set to `true` to use the inline variant | `false` |

#### `DropdownSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `DropdownSkeleton` $$restProps

`DropdownSkeleton` spreads `$$restProps` to the `div` element.


## ExpandableTile

Expandable tiles create a collapsible content container that can show and hide
content with a smooth animation. They are ideal for managing content overflow
and progressive disclosure of information. They automatically measure content
height using a resize observer.

### Default

Create an expandable tile that shows and hides content. The component uses a
[resize observer](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)
to determine the height of the above-the-fold content.

By default, the tile is collapsed. Use the `above` and `below` slots to define
the content that appears before and after expansion.

```svelte
<script>
  import { ExpandableTile } from "carbon-components-svelte";
</script>

<ExpandableTile>
  <div slot="above">
    <div>Above the fold content here</div>
    <br />
    <br />
    <div>More above the fold content</div>
  </div>
  <div slot="below">Below the fold content here</div>
</ExpandableTile>
```

### Custom tile heights

Set custom heights for the tile content using CSS. This is useful when you need
to control the exact dimensions of the visible and hidden content.

```svelte
<script>
  import { ExpandableTile } from "carbon-components-svelte";
</script>

<ExpandableTile>
  <div slot="above" style="height: 10rem">Above the fold content here</div>
  <div slot="below" style="height: 10rem">Below the fold content here</div>
</ExpandableTile>
```

### Expanded

Display the tile in its expanded state by default by setting the `expanded` prop
to `true`.

```svelte
<script>
  import { ExpandableTile } from "carbon-components-svelte";
</script>

<ExpandableTile expanded>
  <div slot="above">Above the fold content here</div>
  <div slot="below">Below the fold content here</div>
</ExpandableTile>
```

### Light variant

Use the light variant for expandable tiles on dark backgrounds by setting the
`light` prop to `true`.

```svelte
<script>
  import { ExpandableTile } from "carbon-components-svelte";
</script>

<ExpandableTile light>
  <div slot="above">Above the fold content here</div>
  <div slot="below">Below the fold content here</div>
</ExpandableTile>
```

### With icon labels

Customize the expand/collapse button labels using the `tileExpandedLabel` and
`tileCollapsedLabel` props.

```svelte
<script>
  import { ExpandableTile } from "carbon-components-svelte";
</script>

<ExpandableTile tileExpandedLabel="View less" tileCollapsedLabel="View more">
  <div slot="above">Above the fold content here</div>
  <div slot="below">Below the fold content here</div>
</ExpandableTile>
```

### With interactive content

By default, the tile uses a `<button>` element to toggle the expand/collapse
state.

If you need to use interactive content inside the tile, set the
`hasInteractiveContent` prop to `true`. This will render the tile as a `<div>`
element to avoid invalid HTML nesting.

Only the expand/collapse toggle with affect the tile's expand/collapse state.

```svelte
<script>
  import {
    Button,
    ExpandableTile,
    OutboundLink,
    Stack,
  } from "carbon-components-svelte";
</script>

<ExpandableTile
  hasInteractiveContent
  tileExpandedLabel="View less"
  tileCollapsedLabel="View more"
>
  <Stack slot="above" gap={4} inline>
    <OutboundLink href="https://svelte.carbondesignsystem.com/">
      Native link
    </OutboundLink>
    <Button on:click={() => console.log("Hello world")}>Button</Button>
  </Stack>
  <div slot="below">Below the fold content here</div>
</ExpandableTile>
```

---

### Component API

#### `ExpandableTile` props

| Prop                       | Type                  | Description                                                                                                                                                                                                                                            | Default                             |
| -------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
| `expanded` (Reactive)      | `boolean`             | Set to `true` to expand the tile                                                                                                                                                                                                                       | `false`                             |
| `tileMaxHeight` (Reactive) | `number`              | Specify the max height of the tile (number of pixels)                                                                                                                                                                                                  | `0`                                 |
| `tilePadding` (Reactive)   | `number`              | Specify the padding of the tile (number of pixels)                                                                                                                                                                                                     | `0`                                 |
| `ref` (Reactive)           | `null \| HTMLElement` | Obtain a reference to the top-level element                                                                                                                                                                                                            | `null`                              |
| `light`                    | `boolean`             | Set to `true` to enable the light variant                                                                                                                                                                                                              | `false`                             |
| `tileCollapsedIconText`    | `string`              | Specify the icon text of the collapsed tile                                                                                                                                                                                                            | `"Interact to expand Tile"`         |
| `tileExpandedIconText`     | `string`              | Specify the icon text of the expanded tile                                                                                                                                                                                                             | `"Interact to collapse Tile"`       |
| `tileExpandedLabel`        | `string`              | Specify the icon label of the expanded tile                                                                                                                                                                                                            | `""`                                |
| `tileCollapsedLabel`       | `string`              | Specify the icon label of the collapsed tile                                                                                                                                                                                                           | `""`                                |
| `tabindex`                 | `string`              | Specify the tabindex                                                                                                                                                                                                                                   | `"0"`                               |
| `id`                       | `string`              | Set an id for the top-level div element                                                                                                                                                                                                                | `ccs-${Math.random().toString(36)}` |
| `hasInteractiveContent`    | `boolean`             | Set to `true` if the tile contains interactive content<br />(e.g., links, buttons, inputs). The tile will render as<br />a `div` instead of a `button` to avoid invalid HTML nesting,<br />and the expand/collapse toggle moves to the chevron button. | `false`                             |

#### `ExpandableTile` slots

| Slot    | Detail                  |
| ------- | ----------------------- |
| `above` | `Record<string, never>` |
| `below` | `Record<string, never>` |

#### `ExpandableTile` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:keypress`   |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `ExpandableTile` $$restProps

`ExpandableTile` spreads `$$restProps` to the `svelte:element` element.


## FileUploader

File uploaders provide a complete solution for file uploads, including a button
trigger, drag-and-drop container, and file list display. They support various
states, file validation, and customization options.

### File uploader (button-only)

Create a simple file upload button using the file uploader button. By default,
it accepts a single file. Set `multiple` to `true` to allow multiple file
selection.

```svelte
<script>
  import { FileUploaderButton } from "carbon-components-svelte";
</script>

<FileUploaderButton labelText="Add file" />
```

### Multiple files

Enable multiple file selection by setting the `multiple` prop to `true`. This
allows users to select multiple files at once.

```svelte
<script>
  import { FileUploaderButton } from "carbon-components-svelte";
</script>

<FileUploaderButton multiple labelText="Add files" />
```

### Custom button kind, size

Customize the button appearance using the `kind` and `size` props. The default
is a small primary button.

```svelte
<script>
  import { FileUploaderButton } from "carbon-components-svelte";
</script>

<FileUploaderButton kind="secondary" size="field" />
<FileUploaderButton kind="tertiary" size="default" />
<FileUploaderButton kind="danger" size="lg" />
<FileUploaderButton kind="danger-tertiary" size="xl" />
```

### Button with icon

Add an icon to the file uploader button using the `icon` prop.

```svelte
<script>
  import { FileUploaderButton } from "carbon-components-svelte";
  import Add from "carbon-icons-svelte/lib/Add.svelte";
  import DocumentAdd from "carbon-icons-svelte/lib/DocumentAdd.svelte";
</script>

<FileUploaderButton icon={Add} labelText="Add file" />
<FileUploaderButton
  icon={DocumentAdd}
  labelText="Upload document"
  kind="secondary"
/>
```

### Icon-only button

> [!NOTE] Provide an **iconDescription** for accessibility. This text will be
> used as the button's tooltip and screen reader label. Set **labelText=""** to
> render an icon-only button.

```svelte
<script>
  import { FileUploaderButton } from "carbon-components-svelte";
  import Add from "carbon-icons-svelte/lib/Add.svelte";
  import DocumentAdd from "carbon-icons-svelte/lib/DocumentAdd.svelte";
</script>

<FileUploaderButton labelText="" iconDescription="Add file" icon={Add} />
<FileUploaderButton
  labelText=""
  iconDescription="Upload document"
  icon={DocumentAdd}
  kind="secondary"
/>
```

### Icon-only button (custom tooltip position)

Control the tooltip position and alignment with `tooltipPosition` and
`tooltipAlignment`.

```svelte
<script>
  import { FileUploaderButton } from "carbon-components-svelte";
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<FileUploaderButton
  labelText=""
  tooltipPosition="right"
  tooltipAlignment="end"
  iconDescription="Add file"
  icon={Add}
/>
```

### Icon-only button (hidden tooltip)

Set `hideTooltip` to `true` to visually hide the tooltip while maintaining
accessibility for screen readers.

> [!NOTE] Use this when tooltips cause layout issues, interfere with
> interactions, or when multiple icon buttons are densely packed (e.g.,
> toolbars). The **iconDescription** remains accessible to screen readers.

```svelte
<script>
  import { FileUploaderButton, Stack } from "carbon-components-svelte";
  import Add from "carbon-icons-svelte/lib/Add.svelte";
  import DocumentAdd from "carbon-icons-svelte/lib/DocumentAdd.svelte";
</script>

<Stack orientation="horizontal" gap={2}>
  <FileUploaderButton
    labelText=""
    hideTooltip
    iconDescription="Add file"
    icon={Add}
  />
  <FileUploaderButton
    labelText=""
    hideTooltip
    iconDescription="Upload document"
    icon={DocumentAdd}
    kind="secondary"
  />
</Stack>
```

### File uploader

The file uploader combines a button trigger with a list of uploaded files. It
supports file type restrictions, multiple file selection, and various upload
states.

This example accepts multiple JPEG files and displays them in a completed state.

```svelte
<script>
  import { FileUploader } from "carbon-components-svelte";
</script>

<FileUploader
  multiple
  labelTitle="Upload files"
  buttonLabel="Add files"
  labelDescription="Only JPEG files are accepted."
  accept={[".jpg", ".jpeg"]}
  status="complete"
/>
```

### Clear files

Remove uploaded files from the file uploader in two ways:

- programmatically using the **clearFiles** accessor
- two-way binding by setting **files** to **[]**

```svelte
<script>
  import { Button, FileUploader } from "carbon-components-svelte";

  let fileUploader;
  let files = [];
</script>

<FileUploader
  bind:this={fileUploader}
  multiple
  labelTitle="Upload files"
  buttonLabel="Add files"
  status="complete"
  bind:files
/>

<br />

<Button
  kind="tertiary"
  disabled={!files.length}
  on:click={fileUploader.clearFiles}
>
  Clear (programmatic)
</Button>
<Button kind="tertiary" disabled={!files.length} on:click={() => (files = [])}>
  Clear (two-way binding)
</Button>
```

### Maximum file size

Limit the size of uploaded files using the `maxFileSize` prop. Files exceeding
the limit (in bytes) will be automatically filtered out.

The `maxFileSize` prop accepts values in bytes. File sizes use binary (base 2)
units, where 1024 bytes = 1 KiB (kibibyte), not 1000 bytes. This matches how
operating systems and file systems measure file sizes.

This example accepts files up to 1 MB (1,048,576 bytes):

```svelte
<script>
  import { FileUploader } from "carbon-components-svelte";
</script>

<FileUploader
  multiple
  maxFileSize={1024 * 1024}
  labelTitle="Upload files"
  buttonLabel="Add files"
  labelDescription="Maximum file size: 1 MB"
  status="edit"
/>
```

### File uploader (disabled state)

Disable the file uploader by setting the `disabled` prop to `true`. This
prevents user interaction with the component.

```svelte
<script>
  import { FileUploader } from "carbon-components-svelte";
</script>

<FileUploader
  disabled
  multiple
  labelTitle="Upload files"
  buttonLabel="Add files"
  labelDescription="Only JPEG files are accepted."
  accept={[".jpg", ".jpeg"]}
  status="complete"
/>
```

### Item (uploading)

Display a file upload in progress using the `uploading` status. This shows a
loading indicator and the file name.

```svelte
<script>
  import { FileUploaderItem } from "carbon-components-svelte";
</script>

<FileUploaderItem name="README.md" status="uploading" />
```

### Item (complete)

Show a successfully uploaded file using the `complete` status. This displays a
checkmark icon next to the file name.

```svelte
<script>
  import { FileUploaderItem } from "carbon-components-svelte";
</script>

<FileUploaderItem name="README.md" status="complete" />
```

### Item (edit)

Enable file deletion by setting the status to `"edit"`. Clicking the close icon
dispatches a `delete` event with the item's ID.

```svelte
<script>
  import {
    FileUploaderDropContainer,
    FileUploaderItem,
    FileUploaderSkeleton,
  } from "carbon-components-svelte";
</script>

<FileUploaderItem
  id="readme"
  name="README.md"
  status="edit"
  on:delete={(e) => {
    console.log(e.detail); // "readme"
  }}
/>

## Item (edit status, invalid state) Mark a file as invalid while keeping it
editable. This shows an error icon and allows the user to remove the file.

<FileUploaderItem
  invalid
  id="readme"
  name="README.md"
  status="edit"
  on:delete
/>

## Item (edit status, invalid state with subject, body) Provide detailed error
messages for invalid files using the `errorSubject` and `errorBody` props. This
helps users understand and resolve upload issues.

<FileUploaderItem
  invalid
  id="readme"
  name="README.md"
  errorSubject="File size exceeds 500kb limit"
  errorBody="Please select a new file."
  status="edit"
  on:delete
/>

## Item sizes Customize the size of file uploader items using the `size` prop.
The default size is "default".

<FileUploaderItem size="default" name="README.md" status="uploading" />
<FileUploaderItem size="field" name="README.md" status="uploading" />
<FileUploaderItem size="small" name="README.md" status="uploading" />

## Drop container Use the file uploader drop container for drag-and-drop file
uploads. It supports file validation and multiple file selection. This example
accepts files smaller than 1 kB and logs the selected files to the console.

<FileUploaderDropContainer
  multiple
  labelText="Drag and drop files here or click to upload"
  validateFiles={(files) => {
    return files.filter((file) => file.size < 1_024);
  }}
  on:change={(e) => {
    console.log("files", e.detail);
  }}
/>

## Skeleton Display a loading state using the file uploader skeleton. This
provides visual feedback while the file uploader content is being loaded.

<FileUploaderSkeleton />
```

---

### Component API

#### `FileUploaderButton` props

| Prop                   | Type                                                    | Description                                                                                                                                                                                                                 | Default                             |
| ---------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `files` (Reactive)     | `ReadonlyArray<File>`                                   | Obtain a reference to the uploaded files.                                                                                                                                                                                   | `[]`                                |
| `labelText` (Reactive) | `string`                                                | Specify the label text                                                                                                                                                                                                      | `"Add file"`                        |
| `ref` (Reactive)       | `null \| HTMLInputElement`                              | Obtain a reference to the input HTML element                                                                                                                                                                                | `null`                              |
| `accept`               | `ReadonlyArray<string>`                                 | Specify the accepted file types.                                                                                                                                                                                            | `[]`                                |
| `multiple`             | `boolean`                                               | Set to `true` to allow multiple files                                                                                                                                                                                       | `false`                             |
| `disabled`             | `boolean`                                               | Set to `true` to disable the input                                                                                                                                                                                          | `false`                             |
| `disableLabelChanges`  | `boolean`                                               | Set to `true` to disable label changes                                                                                                                                                                                      | `false`                             |
| `kind`                 | `import("../Button/Button.svelte").ButtonProps["kind"]` | Specify the kind of file uploader button.                                                                                                                                                                                   | `"primary"`                         |
| `size`                 | `import("../Button/Button.svelte").ButtonProps["size"]` | Specify the size of the file uploader button.                                                                                                                                                                               | `"small"`                           |
| `id`                   | `string`                                                | Set an id for the input element                                                                                                                                                                                             | `ccs-${Math.random().toString(36)}` |
| `name`                 | `string`                                                | Specify a name attribute for the input                                                                                                                                                                                      | `""`                                |
| `icon`                 | `any`                                                   | Specify the icon to render.                                                                                                                                                                                                 | _undefined_                         |
| `iconDescription`      | `string`                                                | Specify the ARIA label for the button icon.                                                                                                                                                                                 | _undefined_                         |
| `tooltipAlignment`     | `"start" \| "center" \| "end"`                          | Set the alignment of the tooltip relative to the icon.<br />Only applies to icon-only buttons.                                                                                                                              | `"center"`                          |
| `tooltipPosition`      | `"top" \| "right" \| "bottom" \| "left"`                | Set the position of the tooltip relative to the icon.                                                                                                                                                                       | `"bottom"`                          |
| `hideTooltip`          | `boolean`                                               | Set to `true` to hide the tooltip while maintaining accessibility.<br />Only applies to icon-only buttons.<br />When `true`, the tooltip is visually hidden but the `iconDescription` remains accessible to screen readers. | `false`                             |

#### `FileUploaderButton` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `labelChildren` | `Record<string, never>` |

#### `FileUploaderButton` forwarded events

| Event        |
| ------------ |
| `on:keydown` |
| `on:click`   |

#### `FileUploaderButton` dispatched events

| Event       | Detail                |
| ----------- | --------------------- |
| `on:change` | `ReadonlyArray<File>` |

#### `FileUploaderButton` $$restProps

`FileUploaderButton` spreads `$$restProps` to the `input` element.

#### `FileUploader` props

| Prop               | Type                                                    | Description                                                                                                                                                                  | Default                      |
| ------------------ | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `files` (Reactive) | `ReadonlyArray<File>`                                   | Obtain a reference to the uploaded files.                                                                                                                                    | `[]`                         |
| `status`           | `"uploading" \| "edit" \| "complete"`                   | Specify the file uploader status.                                                                                                                                            | `"uploading"`                |
| `disabled`         | `boolean`                                               | Set to `true` to disable the file uploader                                                                                                                                   | `false`                      |
| `accept`           | `ReadonlyArray<string>`                                 | Specify the accepted file types.                                                                                                                                             | `[]`                         |
| `maxFileSize`      | `number \| undefined`                                   | Specify the maximum file size in bytes.<br />Files exceeding this limit will be filtered out.<br />File sizes use binary (base 2) units: 1024 bytes = 1 KiB, not 1000 bytes. | _undefined_                  |
| `multiple`         | `boolean`                                               | Set to `true` to allow multiple files                                                                                                                                        | `false`                      |
| `clearFiles`       | `() => void`                                            | Programmatically clear the uploaded files.                                                                                                                                   | _undefined_                  |
| `labelTitle`       | `string`                                                | Specify the label title.<br />Alternatively, use the named slot "labelTitle".                                                                                                | `""`                         |
| `labelDescription` | `string`                                                | Specify the label description.<br />Alternatively, use the named slot "labelDescription".                                                                                    | `""`                         |
| `kind`             | `import("../Button/Button.svelte").ButtonProps["kind"]` | Specify the kind of file uploader button.                                                                                                                                    | `"primary"`                  |
| `size`             | `import("../Button/Button.svelte").ButtonProps["size"]` | Specify the size of the file uploader button.                                                                                                                                | `"small"`                    |
| `buttonLabel`      | `string`                                                | Specify the button label                                                                                                                                                     | `""`                         |
| `iconDescription`  | `string`                                                | Specify the ARIA label used for the status icons                                                                                                                             | `"Provide icon description"` |
| `name`             | `string`                                                | Specify a name attribute for the file button uploader input                                                                                                                  | `""`                         |

#### `FileUploader` slots

| Slot               | Detail                  |
| ------------------ | ----------------------- |
| `labelDescription` | `Record<string, never>` |
| `labelTitle`       | `Record<string, never>` |

#### `FileUploader` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:keydown`    |

#### `FileUploader` dispatched events

| Event       | Detail                |
| ----------- | --------------------- |
| `on:add`    | `ReadonlyArray<File>` |
| `on:remove` | `ReadonlyArray<File>` |
| `on:change` | `ReadonlyArray<File>` |

#### `FileUploader` $$restProps

`FileUploader` spreads `$$restProps` to the `div` element.

#### `FileUploaderDropContainer` props

| Prop               | Type                                                  | Description                                                                                           | Default                             |
| ------------------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `files` (Reactive) | `ReadonlyArray<File>`                                 | Obtain a reference to the uploaded files.                                                             | `[]`                                |
| `ref` (Reactive)   | `null \| HTMLInputElement`                            | Obtain a reference to the input HTML element                                                          | `null`                              |
| `accept`           | `ReadonlyArray<string>`                               | Specify the accepted file types.                                                                      | `[]`                                |
| `multiple`         | `boolean`                                             | Set to `true` to allow multiple files                                                                 | `false`                             |
| `validateFiles`    | `(files: ReadonlyArray<File>) => ReadonlyArray<File>` | Override the default behavior of validating uploaded files.<br />By default, files are not validated. | _undefined_                         |
| `labelText`        | `string`                                              | Specify the label text                                                                                | `"Add file"`                        |
| `role`             | `string`                                              | Specify the `role` attribute of the drop container                                                    | `"button"`                          |
| `disabled`         | `boolean`                                             | Set to `true` to disable the input                                                                    | `false`                             |
| `tabindex`         | `string`                                              | Specify `tabindex` attribute                                                                          | `"0"`                               |
| `id`               | `string`                                              | Set an id for the input element                                                                       | `ccs-${Math.random().toString(36)}` |
| `name`             | `string`                                              | Specify a name attribute for the input                                                                | `""`                                |

#### `FileUploaderDropContainer` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `labelChildren` | `Record<string, never>` |

#### `FileUploaderDropContainer` forwarded events

| Event          |
| -------------- |
| `on:dragover`  |
| `on:dragleave` |
| `on:drop`      |
| `on:keydown`   |
| `on:click`     |

#### `FileUploaderDropContainer` dispatched events

| Event       | Detail                |
| ----------- | --------------------- |
| `on:add`    | `ReadonlyArray<File>` |
| `on:change` | `ReadonlyArray<File>` |

#### `FileUploaderDropContainer` $$restProps

`FileUploaderDropContainer` spreads `$$restProps` to the `div` element.

#### `FileUploaderItem` props

| Prop              | Type                                  | Description                                      | Default                             |
| ----------------- | ------------------------------------- | ------------------------------------------------ | ----------------------------------- |
| `status`          | `"uploading" \| "edit" \| "complete"` | Specify the file uploader status.                | `"uploading"`                       |
| `size`            | `"default" \| "field" \| "small"`     | Specify the size of button skeleton.             | `"default"`                         |
| `iconDescription` | `string`                              | Specify the ARIA label used for the status icons | `""`                                |
| `invalid`         | `boolean`                             | Set to `true` to indicate an invalid state       | `false`                             |
| `errorSubject`    | `string`                              | Specify the error subject text                   | `""`                                |
| `errorBody`       | `string`                              | Specify the error body text                      | `""`                                |
| `id`              | `string`                              | Set an id for the top-level element              | `ccs-${Math.random().toString(36)}` |
| `name`            | `string`                              | Specify the file uploader name                   | `""`                                |

#### `FileUploaderItem` forwarded events

| Event           |
| --------------- |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `FileUploaderItem` dispatched events

| Event       | Detail   |
| ----------- | -------- |
| `on:delete` | `string` |

#### `FileUploaderItem` $$restProps

`FileUploaderItem` spreads `$$restProps` to the `span` element.

#### `FileUploaderSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `FileUploaderSkeleton` $$restProps

`FileUploaderSkeleton` spreads `$$restProps` to the `div` element.


## FloatingPortal

Floating portals build on [Portal](/components/Portal) by rendering content into
`document.body` and positioning it relative to an anchor element. The `anchor`
prop is required and specifies the element to position the floating content
relative to. They automatically flip direction when there is not enough space
and reposition on scroll and resize.

Use a portal when you only need to escape overflow and z-index stacking
contexts. Use floating portals when you need anchored, positioned content such
as dropdowns, popovers, or overflow menus.

In the examples below, click the button to toggle the floating content and drag
the tile to move the anchor. The floating content will track the anchor
position.

### Default

Position floating content below an anchor element.

```svelte
<script>
  import { Button, FloatingPortal, Tile } from "carbon-components-svelte";

  let anchor = null;
  let container = null;
  let open = false;
  let x = 0;
  let y = 0;
  let startX = 0;
  let startY = 0;
  let offsetX = 0;
  let offsetY = 0;

  const emptyImage = new Image();
  emptyImage.src =
    "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";

  function handleDragStart(e) {
    const rect = anchor.getBoundingClientRect();
    offsetX = e.clientX - rect.left;
    offsetY = e.clientY - rect.top;
    startX = x;
    startY = y;
    e.dataTransfer.setDragImage(emptyImage, 0, 0);
    e.dataTransfer.effectAllowed = "move";
    e.dataTransfer.setData("text/plain", "");
  }

  function handleDrag(e) {
    if ((e.clientX !== 0 || e.clientY !== 0) && container) {
      const parentRect = container.getBoundingClientRect();
      if (
        e.clientX >= parentRect.left &&
        e.clientX <= parentRect.right &&
        e.clientY >= parentRect.top &&
        e.clientY <= parentRect.bottom
      ) {
        x = e.clientX - offsetX - parentRect.left;
        y = e.clientY - offsetY - parentRect.top;
      }
    }
  }

  function handleDragEnd() {
    const moved = Math.abs(x - startX) > 5 || Math.abs(y - startY) > 5;
    if (!moved) {
      open = !open;
    }
  }
</script>

<div
  bind:this={container}
  style="position: relative; min-height: 200px; min-width: 300px;"
>
  <div
    bind:this={anchor}
    role="button"
    tabindex="0"
    draggable="true"
    style="position: absolute; left: {x}px; top: {y}px; cursor: move; user-select: none;"
    on:dragstart={handleDragStart}
    on:drag={handleDrag}
    on:dragend={handleDragEnd}
    on:keydown={(e) => e.key === "Enter" && (open = !open)}
    title="Drag to move, click to toggle"
  >
    <Tile>
      <Button on:click={() => (open = !open)}>Toggle floating content</Button>
    </Tile>
  </div>
</div>

<FloatingPortal {anchor} {open}>
  <Tile>Content</Tile>
</FloatingPortal>
```

### Direction

Set the `direction` prop to `"top"` or `"bottom"` to control the preferred
direction. The component will flip to the opposite direction if there is not
enough space.

The default direction is `"bottom"`.

```svelte
<script>
  import {
    Button,
    FloatingPortal,
    Stack,
    Tile,
  } from "carbon-components-svelte";

  let anchorTop = null;
  let anchorBottom = null;
  let containerBottom = null;
  let containerTop = null;
  let openTop = false;
  let openBottom = false;

  let xBottom = 0;
  let yBottom = 0;
  let xTop = 0;
  let yTop = 0;
  let startXBottom = 0;
  let startYBottom = 0;
  let startXTop = 0;
  let startYTop = 0;
  let offsetX = 0;
  let offsetY = 0;

  const emptyImage = new Image();
  emptyImage.src =
    "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";

  function handleDragStartBottom(e) {
    const rect = anchorBottom.getBoundingClientRect();
    offsetX = e.clientX - rect.left;
    offsetY = e.clientY - rect.top;
    startXBottom = xBottom;
    startYBottom = yBottom;
    e.dataTransfer.setDragImage(emptyImage, 0, 0);
    e.dataTransfer.effectAllowed = "move";
    e.dataTransfer.setData("text/plain", "");
  }

  function handleDragStartTop(e) {
    const rect = anchorTop.getBoundingClientRect();
    offsetX = e.clientX - rect.left;
    offsetY = e.clientY - rect.top;
    startXTop = xTop;
    startYTop = yTop;
    e.dataTransfer.setDragImage(emptyImage, 0, 0);
    e.dataTransfer.effectAllowed = "move";
    e.dataTransfer.setData("text/plain", "");
  }

  function handleDragBottom(e) {
    if ((e.clientX !== 0 || e.clientY !== 0) && containerBottom) {
      const parentRect = containerBottom.getBoundingClientRect();
      if (
        e.clientX >= parentRect.left &&
        e.clientX <= parentRect.right &&
        e.clientY >= parentRect.top &&
        e.clientY <= parentRect.bottom
      ) {
        xBottom = e.clientX - offsetX - parentRect.left;
        yBottom = e.clientY - offsetY - parentRect.top;
      }
    }
  }

  function handleDragTop(e) {
    if ((e.clientX !== 0 || e.clientY !== 0) && containerTop) {
      const parentRect = containerTop.getBoundingClientRect();
      if (
        e.clientX >= parentRect.left &&
        e.clientX <= parentRect.right &&
        e.clientY >= parentRect.top &&
        e.clientY <= parentRect.bottom
      ) {
        xTop = e.clientX - offsetX - parentRect.left;
        yTop = e.clientY - offsetY - parentRect.top;
      }
    }
  }

  function handleDragEndBottom() {
    const moved =
      Math.abs(xBottom - startXBottom) > 5 ||
      Math.abs(yBottom - startYBottom) > 5;
    if (!moved) openBottom = !openBottom;
  }

  function handleDragEndTop() {
    const moved =
      Math.abs(xTop - startXTop) > 5 || Math.abs(yTop - startYTop) > 5;
    if (!moved) openTop = !openTop;
  }
</script>

<Stack gap={5}>
  <div
    bind:this={containerBottom}
    style="position: relative; min-height: 200px; min-width: 300px;"
  >
    <div
      bind:this={anchorBottom}
      role="button"
      tabindex="0"
      draggable="true"
      style="position: absolute; left: {xBottom}px; top: {yBottom}px; cursor: move; user-select: none;"
      on:dragstart={handleDragStartBottom}
      on:drag={handleDragBottom}
      on:dragend={handleDragEndBottom}
      on:keydown={(e) => e.key === "Enter" && (openBottom = !openBottom)}
      title="Drag to move, click to toggle"
    >
      <Tile>
        <Button on:click={() => (openBottom = !openBottom)}
          >Direction: bottom (default)</Button
        >
      </Tile>
    </div>
    <FloatingPortal anchor={anchorBottom} open={openBottom} direction="bottom">
      <Tile>Content</Tile>
    </FloatingPortal>
  </div>

  <div
    bind:this={containerTop}
    style="position: relative; min-height: 200px; min-width: 300px;"
  >
    <div
      bind:this={anchorTop}
      role="button"
      tabindex="0"
      draggable="true"
      style="position: absolute; left: {xTop}px; top: {yTop}px; cursor: move; user-select: none;"
      on:dragstart={handleDragStartTop}
      on:drag={handleDragTop}
      on:dragend={handleDragEndTop}
      on:keydown={(e) => e.key === "Enter" && (openTop = !openTop)}
      title="Drag to move, click to toggle"
    >
      <Tile>
        <Button on:click={() => (openTop = !openTop)}>Direction: top</Button>
      </Tile>
    </div>
    <FloatingPortal anchor={anchorTop} open={openTop} direction="top">
      <Tile>Content</Tile>
    </FloatingPortal>
  </div>
</Stack>
```

### Escaping overflow

Because the floating content is rendered into `document.body`, it escapes parent
containers with `overflow: hidden`.

```svelte
<script>
  import {
    Button,
    FloatingPortal,
    Stack,
    Tile,
  } from "carbon-components-svelte";

  let anchor = null;
  let container = null;
  let open = false;
  let x = 0;
  let y = 0;
  let startX = 0;
  let startY = 0;
  let offsetX = 0;
  let offsetY = 0;

  const emptyImage = new Image();
  emptyImage.src =
    "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";

  function handleDragStart(e) {
    const rect = anchor.getBoundingClientRect();
    offsetX = e.clientX - rect.left;
    offsetY = e.clientY - rect.top;
    startX = x;
    startY = y;
    e.dataTransfer.setDragImage(emptyImage, 0, 0);
    e.dataTransfer.effectAllowed = "move";
    e.dataTransfer.setData("text/plain", "");
  }

  function handleDrag(e) {
    if ((e.clientX !== 0 || e.clientY !== 0) && container) {
      const parentRect = container.getBoundingClientRect();
      if (
        e.clientX >= parentRect.left &&
        e.clientX <= parentRect.right &&
        e.clientY >= parentRect.top &&
        e.clientY <= parentRect.bottom
      ) {
        x = e.clientX - offsetX - parentRect.left;
        y = e.clientY - offsetY - parentRect.top;
      }
    }
  }

  function handleDragEnd() {
    const moved = Math.abs(x - startX) > 5 || Math.abs(y - startY) > 5;
    if (!moved) open = !open;
  }
</script>

<Stack
  gap={4}
  style="overflow: hidden; border: 1px dashed var(--cds-border-subtle); padding: 1rem"
>
  <div>This container has hidden overflow.</div>
  <div
    bind:this={container}
    style="position: relative; min-height: 200px; min-width: 300px;"
  >
    <div
      bind:this={anchor}
      role="button"
      tabindex="0"
      draggable="true"
      style="position: absolute; left: {x}px; top: {y}px; cursor: move; user-select: none;"
      on:dragstart={handleDragStart}
      on:drag={handleDrag}
      on:dragend={handleDragEnd}
      on:keydown={(e) => e.key === "Enter" && (open = !open)}
      title="Drag to move, click to toggle"
    >
      <Tile>
        <Button on:click={() => (open = !open)}>Toggle floating content</Button>
      </Tile>
    </div>
  </div>
</Stack>

<FloatingPortal {anchor} {open}>
  <Tile>Content</Tile>
</FloatingPortal>
```

### Slot direction

By default, the floating content is rendered below the anchor element. However,
if there is not enough space below the anchor element, the component will
automatically flip to the opposite direction.

Use the `direction` slot prop to read the actual rendered direction after
auto-flipping for conditional logic, like styles.

```svelte
<script>
  import {
    Button,
    FloatingPortal,
    Stack,
    Tag,
    Tile,
  } from "carbon-components-svelte";

  let anchor = null;
  let container = null;
  let open = false;
  let x = 0;
  let y = 0;
  let startX = 0;
  let startY = 0;
  let offsetX = 0;
  let offsetY = 0;

  const emptyImage = new Image();
  emptyImage.src =
    "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";

  function handleDragStart(e) {
    const rect = anchor.getBoundingClientRect();
    offsetX = e.clientX - rect.left;
    offsetY = e.clientY - rect.top;
    startX = x;
    startY = y;
    e.dataTransfer.setDragImage(emptyImage, 0, 0);
    e.dataTransfer.effectAllowed = "move";
    e.dataTransfer.setData("text/plain", "");
  }

  function handleDrag(e) {
    if ((e.clientX !== 0 || e.clientY !== 0) && container) {
      const parentRect = container.getBoundingClientRect();
      if (
        e.clientX >= parentRect.left &&
        e.clientX <= parentRect.right &&
        e.clientY >= parentRect.top &&
        e.clientY <= parentRect.bottom
      ) {
        x = e.clientX - offsetX - parentRect.left;
        y = e.clientY - offsetY - parentRect.top;
      }
    }
  }

  function handleDragEnd() {
    const moved = Math.abs(x - startX) > 5 || Math.abs(y - startY) > 5;
    if (!moved) open = !open;
  }
</script>

<div
  bind:this={container}
  style="position: relative; min-height: 200px; min-width: 300px;"
>
  <div
    bind:this={anchor}
    role="button"
    tabindex="0"
    draggable="true"
    style="position: absolute; left: {x}px; top: {y}px; cursor: move; user-select: none;"
    on:dragstart={handleDragStart}
    on:drag={handleDrag}
    on:dragend={handleDragEnd}
    on:keydown={(e) => e.key === "Enter" && (open = !open)}
    title="Drag to move, click to toggle"
  >
    <Tile>
      <Button on:click={() => (open = !open)}>Toggle floating content</Button>
    </Tile>
  </div>
</div>

<FloatingPortal {anchor} {open} let:direction>
  <Tile>
    <Stack orientation="horizontal" align="center" gap={2}>
      Actual direction: <Tag size="sm">{direction}</Tag>
    </Stack>
  </Tile>
</FloatingPortal>
```

---

### Component API

#### `FloatingPortal` props

| Prop                | Type                  | Description                                                                                                                                                                | Default     |
| ------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `anchor` (Required) | `null \| HTMLElement` | Required. Specify the anchor element to position the floating content relative to.<br />When using `bind:this`, this may be `null` initially until the element is mounted. | _undefined_ |
| `ref` (Reactive)    | `null \| HTMLElement` | Obtain a reference to the floating portal element.                                                                                                                         | `null`      |
| `direction`         | `"bottom" \| "top"`   | Set the preferred direction of the floating content.<br />The component will flip to the opposite direction<br />if there is not enough space.                             | `"bottom"`  |
| `open`              | `boolean`             | Set to `true` to open the floating content.                                                                                                                                | `false`     |
| `zIndex`            | `number`              | Specify the z-index of the floating portal.<br />By default, this value supersedes the z-index<br />of modals (9000) and list box menus (9100).                            | `9200`      |

#### `FloatingPortal` slots

| Slot      | Detail                                         |
| --------- | ---------------------------------------------- |
| `default` | `{<br /> direction: "bottom" \| "top";<br />}` |

#### `FloatingPortal` $$restProps

`FloatingPortal` spreads `$$restProps` to the `Portal` component.


## FluidForm

Fluid forms provide a fluid-width form layout that adapts to their container.
They are designed for full-width form layouts and work with most Carbon input
components. Note that inline input variants cannot be used within a fluid form.

### Fluid form

Create a fluid-width form layout using the fluid form component. This example
shows a basic login form with required fields.

```svelte
<script>
  import {
    FluidForm,
    PasswordInput,
    TextInput,
  } from "carbon-components-svelte";
</script>

<FluidForm>
  <TextInput labelText="User name" placeholder="Enter user name..." required />
  <PasswordInput
    required
    type="password"
    labelText="Password"
    placeholder="Enter password..."
  />
</FluidForm>
```

### Invalid state

Handle form validation and display error states using the `invalid` and
`invalidText` props on form inputs. This example demonstrates how to show
validation errors in a fluid form.

```svelte
<script>
  import {
    FluidForm,
    PasswordInput,
    TextInput,
  } from "carbon-components-svelte";

  let password = "";
  let invalid = false;

  $: invalid = !/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{6,}$/.test(password);
</script>

<FluidForm>
  <TextInput labelText="User name" placeholder="Enter user name..." required />
  <PasswordInput
    bind:value={password}
    {invalid}
    invalidText="Your password must be at least 6 characters as well as contain at least one uppercase, one lowercase, and one number."
    required
    type="password"
    labelText="Password"
    placeholder="Enter password..."
  />
</FluidForm>
```

---

### Component API

#### `FluidForm` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `FluidForm` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:keydown`    |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:submit`     |

#### `FluidForm` $$restProps

`FluidForm` spreads `$$restProps` to the `form` element.


## Form

Forms provide a structured way to collect user input. They work with various
form controls like checkboxes, radio buttons, and select menus. Form groups help
organize related form controls with a legend.

### Form

Create a form with grouped controls using the form and form group. This example
shows a form with checkboxes, radio buttons, and a select menu.

```svelte
<script>
  import {
    Button,
    Checkbox,
    Form,
    FormGroup,
    RadioButton,
    RadioButtonGroup,
    Select,
    SelectItem,
  } from "carbon-components-svelte";
</script>

<Form on:submit>
  <FormGroup legendText="Checkboxes">
    <Checkbox id="checkbox-0" labelText="Checkbox Label" checked />
    <Checkbox id="checkbox-1" labelText="Checkbox Label" />
    <Checkbox id="checkbox-2" labelText="Checkbox Label" disabled />
  </FormGroup>
  <FormGroup legendText="Radio buttons">
    <RadioButtonGroup name="radio-button-group" selected="default-selected">
      <RadioButton
        id="radio-1"
        value="standard"
        labelText="Standard Radio Button"
      />
      <RadioButton
        id="radio-2"
        value="default-selected"
        labelText="Default Selected Radio Button"
      />
      <RadioButton
        id="radio-4"
        value="disabled"
        labelText="Disabled Radio Button"
        disabled
      />
    </RadioButtonGroup>
  </FormGroup>
  <FormGroup>
    <Select id="select-1" labelText="Select menu">
      <SelectItem
        disabled
        hidden
        value="placeholder-item"
        text="Choose an option"
      />
      <SelectItem value="option-1" text="Option 1" />
      <SelectItem value="option-2" text="Option 2" />
      <SelectItem value="option-3" text="Option 3" />
    </Select>
  </FormGroup>
  <Button type="submit">Submit</Button>
</Form>
```

### Prevent default behavior

Handle form submission by preventing the default browser behavior. Use
`e.preventDefault()` to stop the native form submission and handle the event
programmatically.

```svelte
<script>
  import { Button, Checkbox, Form } from "carbon-components-svelte";
</script>

<Form
  on:submit={(e) => {
    e.preventDefault();
    console.log("submit", e);
  }}
>
  <Checkbox id="checkbox-0" labelText="Checkbox Label" checked />
  <Button type="submit">Submit</Button>
</Form>
```

---

### Component API

#### `Form` props

| Prop             | Type                      | Description                            | Default |
| ---------------- | ------------------------- | -------------------------------------- | ------- |
| `ref` (Reactive) | `null \| HTMLFormElement` | Obtain a reference to the form element | `null`  |

#### `Form` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `Form` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:keydown`    |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:submit`     |

#### `Form` $$restProps

`Form` spreads `$$restProps` to the `form` element.

#### `FormGroup` props

| Prop          | Type      | Description                                   | Default |
| ------------- | --------- | --------------------------------------------- | ------- |
| `noMargin`    | `boolean` | Set to `true` for to remove the bottom margin | `false` |
| `invalid`     | `boolean` | Set to `true` to indicate an invalid state    | `false` |
| `message`     | `boolean` | Set to `true` to render a form requirement    | `false` |
| `messageText` | `string`  | Specify the message text                      | `""`    |
| `legendText`  | `string`  | Specify the legend text                       | `""`    |
| `legendId`    | `string`  | Specify an id for the legend element          | `""`    |

#### `FormGroup` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `FormGroup` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `FormGroup` $$restProps

`FormGroup` spreads `$$restProps` to the `fieldset` element.


## Grid

The
[Carbon grid system](https://carbondesignsystem.com/elements/2x-grid/overview/)
provides a responsive layout structure that adapts to different screen sizes.
Use row and column components to create flexible layouts. The grid supports
various spacing options and column configurations.

The system uses a responsive column structure where the total number of columns
changes based on screen size:

- **Small (sm)**: 0-671px — 4 columns
- **Medium (md)**: 672-1055px — 8 columns
- **Large (lg)**: 1056-1311px — 16 columns
- **X-Large (xlg)**: 1312-1583px — 16 columns
- **Max (max)**: 1584px and above — 16 columns

> [!NOTE] Column spans are relative to the total columns at each breakpoint. For
> example, to create a full-width column, use `sm={4} md={8} lg={16}` instead of
> the same value across all breakpoints.

### Default

Create a basic grid layout with equal-width columns. This example demonstrates
the default grid behavior.

```svelte
<script>
  import { Column, Grid, Row } from "carbon-components-svelte";
</script>

<Grid>
  <Row>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
  </Row>
</Grid>
```

### Full width

Use the full-width grid variant for layouts that span the entire viewport width.
This removes the default max-width constraint.

```svelte
<script>
  import { Column, Grid, Row } from "carbon-components-svelte";
</script>

<Grid fullWidth>
  <Row>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
  </Row>
</Grid>
```

### Narrow

Create a more compact grid layout using the narrow variant. This reduces the
spacing between columns.

```svelte
<script>
  import { Column, Grid, Row } from "carbon-components-svelte";
</script>

<Grid narrow>
  <Row>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
  </Row>
</Grid>
```

### Condensed

Use the condensed variant for even tighter spacing between columns. This is
ideal for dense data displays.

```svelte
<script>
  import { Column, Grid, Row } from "carbon-components-svelte";
</script>

<Grid condensed>
  <Row>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
  </Row>
</Grid>
```

### Responsive

Build responsive layouts by specifying different column widths for different
breakpoints. The grid automatically adjusts based on screen size.

**Key concept:** Since each breakpoint has a different total number of columns,
you need to scale your column spans proportionally. Here are common patterns:

**Full width column:**

```svelte
<script>
  import { Column } from "carbon-components-svelte";
</script>

<Column sm={4} md={8} lg={16} />
```

**Half width (50/50 split):**

```svelte
<script>
  import { Column } from "carbon-components-svelte";
</script>

<Column sm={2} md={4} lg={8} />
<Column sm={2} md={4} lg={8} />
```

**Two-thirds / One-third split:**

```svelte
<script>
  import { Column } from "carbon-components-svelte";
</script>

<Column sm={4} md={6} lg={11} />
<Column sm={4} md={2} lg={5} />
```

```svelte
<script>
  import { Column, Grid, Row } from "carbon-components-svelte";
</script>

<Grid>
  <Row>
    <Column sm={1} md={4} lg={8}>sm: 1, md: 4, lg: 8</Column>
    <Column sm={1} md={2} lg={2}>sm: 1, md: 2, lg: 2</Column>
    <Column sm={1} md={1} lg={1}>sm: 1, md: 1, lg: 1</Column>
    <Column sm={1} md={1} lg={1}>sm: 1, md: 1, lg: 1</Column>
  </Row>
</Grid>
```

### Offset columns

Create space between columns using the offset feature. This allows for more
flexible layouts without empty columns.

```svelte
<script>
  import { Column, Grid, Row } from "carbon-components-svelte";
</script>

<Grid>
  <Row>
    <Column sm={{ span: 1, offset: 3 }}>Offset 3</Column>
    <Column sm={{ span: 2, offset: 2 }}>Offset 2</Column>
    <Column sm={{ span: 3, offset: 1 }}>Offset 1</Column>
    <Column sm={{ span: 4, offset: 0 }}>Offset 0</Column>
  </Row>
</Grid>
```

### Aspect ratio columns

Maintain consistent column heights using aspect ratio columns. This ensures
content alignment across different column widths.

```svelte
<script>
  import { Column, Grid, Row } from "carbon-components-svelte";
</script>

<Grid>
  <Row>
    <Column aspectRatio="2x1">2x1</Column>
    <Column aspectRatio="2x1">2x1</Column>
  </Row>
</Grid>
```

### Padding

Add vertical padding (top/bottom) to grid elements using the `padding` prop. You
can apply padding at the grid, row, or column level to control spacing between
rows of content. This is useful for creating vertical rhythm without manually
adding margins.

```svelte
<script>
  import { Column, Grid, Row } from "carbon-components-svelte";
</script>

<div>Adding padding to Grid applies it to columns in all rows:</div>

<Grid padding>
  <Row>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
  </Row>
</Grid>

<div>Adding padding to a Row only applies to its columns:</div>

<Grid>
  <Row padding>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
  </Row>
  <Row>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
  </Row>
</Grid>

<div>Adding padding to a specific column only applies it to the column:</div>

<Grid>
  <Row>
    <Column padding>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
    <Column>Column</Column>
  </Row>
</Grid>

<style>
  div {
    margin-top: var(--cds-spacing-05);
    padding: var(--cds-spacing-05);
  }
</style>
```

### Breakpoints Reference

Understanding [breakpoints](/components/Breakpoint) is critical for creating
responsive layouts. Each breakpoint has specific pixel ranges and column counts:

- **Small (sm)**: 0-671px — 4 columns — Mobile phones
- **Medium (md)**: 672-1055px — 8 columns — Tablets, small laptops
- **Large (lg)**: 1056-1311px — 16 columns — Desktop monitors, laptops
- **X-Large (xlg)**: 1312-1583px — 16 columns — Large desktop monitors
- **Max (max)**: 1584px and above — 16 columns — Extra-large displays

When designing responsive layouts, start with mobile (sm) and work your way up
to ensure your content works well at all sizes.

---

### Component API

#### `Grid` props

| Prop            | Type      | Description                                                                                                | Default |
| --------------- | --------- | ---------------------------------------------------------------------------------------------------------- | ------- |
| `as`            | `boolean` | Set to `true` to render a custom HTML element.<br />Props are destructured as `props` in the default slot. | `false` |
| `condensed`     | `boolean` | Set to `true` to use the condensed variant                                                                 | `false` |
| `narrow`        | `boolean` | Set to `true` to use the narrow variant                                                                    | `false` |
| `fullWidth`     | `boolean` | Set to `true` to use the fullWidth variant                                                                 | `false` |
| `noGutter`      | `boolean` | Set to `true` to remove the gutter                                                                         | `false` |
| `noGutterLeft`  | `boolean` | Set to `true` to remove the left gutter                                                                    | `false` |
| `noGutterRight` | `boolean` | Set to `true` to remove the right gutter                                                                   | `false` |
| `padding`       | `boolean` | Set to `true` to add top and bottom padding to all columns                                                 | `false` |

#### `Grid` slots

| Slot      | Detail                                                                            |
| --------- | --------------------------------------------------------------------------------- |
| `default` | `{<br /> props: {<br /> class: string;<br /> [key: string]: any;<br /> };<br />}` |

#### `Grid` $$restProps

`Grid` spreads `$$restProps` to the `div` element.

#### `Row` props

| Prop            | Type      | Description                                                                                                | Default |
| --------------- | --------- | ---------------------------------------------------------------------------------------------------------- | ------- |
| `as`            | `boolean` | Set to `true` to render a custom HTML element.<br />Props are destructured as `props` in the default slot. | `false` |
| `condensed`     | `boolean` | Set to `true` to use the condensed variant                                                                 | `false` |
| `narrow`        | `boolean` | Set to `true` to use the narrow variant                                                                    | `false` |
| `noGutter`      | `boolean` | Set to `true` to remove the gutter                                                                         | `false` |
| `noGutterLeft`  | `boolean` | Set to `true` to remove the left gutter                                                                    | `false` |
| `noGutterRight` | `boolean` | Set to `true` to remove the right gutter                                                                   | `false` |
| `padding`       | `boolean` | Set to `true` to add top and bottom padding to all columns                                                 | `false` |

#### `Row` slots

| Slot      | Detail                                                                            |
| --------- | --------------------------------------------------------------------------------- |
| `default` | `{<br /> props: {<br /> class: string;<br /> [key: string]: any;<br /> };<br />}` |

#### `Row` $$restProps

`Row` spreads `$$restProps` to the `div` element.

#### `Column` props

| Prop            | Type                                                            | Description                                                                                                | Default     |
| --------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------- |
| `as`            | `boolean`                                                       | Set to `true` to render a custom HTML element.<br />Props are destructured as `props` in the default slot. | `false`     |
| `noGutter`      | `boolean`                                                       | Set to `true` to remove the gutter                                                                         | `false`     |
| `noGutterLeft`  | `boolean`                                                       | Set to `true` to remove the left gutter                                                                    | `false`     |
| `noGutterRight` | `boolean`                                                       | Set to `true` to remove the right gutter                                                                   | `false`     |
| `padding`       | `boolean`                                                       | Set to `true` to add top and bottom padding to the column                                                  | `false`     |
| `aspectRatio`   | `"2x1" \| "16x9" \| "9x16" \| "1x2" \| "4x3" \| "3x4" \| "1x1"` | Specify the aspect ratio of the column.                                                                    | _undefined_ |
| `sm`            | `ColumnBreakpoint`                                              | Set the small breakpoint.                                                                                  | _undefined_ |
| `md`            | `ColumnBreakpoint`                                              | Set the medium breakpoint.                                                                                 | _undefined_ |
| `lg`            | `ColumnBreakpoint`                                              | Set the large breakpoint.                                                                                  | _undefined_ |
| `xlg`           | `ColumnBreakpoint`                                              | Set the extra large breakpoint.                                                                            | _undefined_ |
| `max`           | `ColumnBreakpoint`                                              | Set the maximum breakpoint.                                                                                | _undefined_ |

#### `Column` typedefs

```ts
type ColumnSize = boolean | number;

type ColumnSizeDescriptor = {
  span?: ColumnSize;
  offset: number;
};

type ColumnBreakpoint = ColumnSize | ColumnSizeDescriptor;
```

#### `Column` slots

| Slot      | Detail                                                                            |
| --------- | --------------------------------------------------------------------------------- |
| `default` | `{<br /> props: {<br /> class: string;<br /> [key: string]: any;<br /> };<br />}` |

#### `Column` $$restProps

`Column` spreads `$$restProps` to the `div` element.


## Heading

Heading and section components work together to automatically manage semantic
heading hierarchy in your application. The heading component automatically
adjusts its heading level (h1–h6) based on the nesting depth of section
components, ensuring proper document structure and accessibility without manual
level management.

### Default

A top-level heading inside a section renders as an `h1` element. This provides a
semantic starting point for your document structure.

```svelte
<script>
  import { Heading, Section } from "carbon-components-svelte";
</script>

<Section>
  <Heading>Heading 1</Heading>
</Section>
```

### Nested sections

As you nest section components, the heading levels automatically increment to
maintain proper hierarchy. Each nested section increases the heading level by
one (h1 → h2 → h3, etc.). Heading levels are automatically capped at `h6` to
ensure valid HTML structure, even if you nest deeper than six levels.

```svelte
<script>
  import { Heading, Section } from "carbon-components-svelte";
</script>

<Section>
  <Heading>Heading 1</Heading>
  <Section>
    <Heading>Heading 2</Heading>
    <Section>
      <Heading>Heading 3</Heading>
      <Section>
        <Heading>Heading 4</Heading>
        <Section>
          <Heading>Heading 5</Heading>
          <Section>
            <Heading>Heading 6</Heading>
            <Section>
              <Heading>Capped at Heading 6</Heading>
            </Section>
          </Section>
        </Section>
      </Section>
    </Section>
  </Section>
</Section>
```

### Custom level

Use the `level` prop on the section to specify a custom starting heading level.
This is useful when you need to start a section at a specific level, such as
when embedding content that should begin at a higher heading level. Child
sections will continue to increment from this custom level.

```svelte
<script>
  import { Heading, Section } from "carbon-components-svelte";
</script>

<Section level={5}>
  <Heading>Starts at Heading 5</Heading>
  <Section>
    <Heading>Heading 6</Heading>
  </Section>
</Section>
```

### Custom section element

By default, the section renders a semantic `<section>` element. Use the `tag`
prop to render a different HTML element while maintaining the heading level
context functionality. This is useful when you need to use a different semantic
element (like `<div>`, `<article>`, or `<aside>`) but still want automatic
heading level management.

```svelte
<script>
  import { Heading, Section } from "carbon-components-svelte";
</script>

<Section tag="div">
  <Heading>Heading 1</Heading>
</Section>
```

---

### Component API

#### `Heading` typedefs

```ts
type SectionLevel = 1 | 2 | 3 | 4 | 5 | 6;
```

#### `Heading` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `Section` props

| Prop    | Type                          | Description                                                                                                                                                                                                                       | Default     |
| ------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `level` | `SectionLevel`                | Specify the heading level the section should start at.<br />When nested, child sections automatically increment from this level.<br />Levels are capped at 6 (h6).<br />@default 1                                                | `1`         |
| `tag`   | `keyof HTMLElementTagNameMap` | Specify the HTML tag name to render instead of the default `section` element.<br />Useful when you need to use a different semantic element while maintaining<br />the heading level context functionality.<br />@default section | `"section"` |

#### `Section` typedefs

```ts
type SectionLevel = 1 | 2 | 3 | 4 | 5 | 6;
```

#### `Section` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |


## ImageLoader

Image loaders provide a robust way to load images with built-in loading and
error states. They use the
[Image API](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/Image)
to handle image loading programmatically. They support aspect ratios, fade-in
animations, and custom loading/error states.

### Default

Load an image with the default configuration. The component handles the loading
process automatically.

```svelte
<script>
  import { ImageLoader } from "carbon-components-svelte";
</script>

<ImageLoader
  src="https://upload.wikimedia.org/wikipedia/commons/5/51/IBM_logo.svg"
/>
```

### Slots

Customize the loading and error states using named slots. This example shows how
to display a loading indicator and error message.

```svelte
<script>
  import { ImageLoader, InlineLoading } from "carbon-components-svelte";
</script>

<ImageLoader
  src="https://upload.wikimedia.org/wikipedia/commons/5/51/IBM_logo.svg"
>
  <svelte:fragment slot="loading">
    <InlineLoading />
  </svelte:fragment>
  <svelte:fragment slot="error">An error occurred.</svelte:fragment>
</ImageLoader>
```

### With aspect ratio

Maintain consistent image dimensions using aspect ratios. The component uses
[AspectRatio](/components/AspectRatio) to constrain the image.

Supported aspect ratios include `"2x1"`, `"2x3"`, `"16x9"`, `"4x3"`, `"1x1"`,
`"3x4"`, `"3x2"`, `"9x16"` and `"1x2"`.

```svelte
<script>
  import { ImageLoader } from "carbon-components-svelte";
</script>

<ImageLoader
  ratio="16x9"
  src="https://upload.wikimedia.org/wikipedia/commons/5/51/IBM_logo.svg"
/>
```

### Fade in

Enable a smooth fade-in animation when the image loads successfully. This
provides a better user experience for image loading.

```svelte
<script>
  import { Button, ImageLoader } from "carbon-components-svelte";
</script>

<Button
  kind="ghost"
  on:click={() => {
    key++;
  }}>Reload image</Button
>
{#key key}<ImageLoader
    fadeIn
    ratio="16x9"
    src="https://upload.wikimedia.org/wikipedia/commons/5/51/IBM_logo.svg"
  />{/key}
```

### Programmatic usage

Control image loading programmatically using component references. This example
demonstrates how to trigger image loading manually.

```svelte
<script>
  import { Button, ImageLoader } from "carbon-components-svelte";

  const src =
    "https://upload.wikimedia.org/wikipedia/commons/5/51/IBM_logo.svg";
  const srcError = `${src}1`;

  let imageLoader;
  let error;
</script>

<Button
  kind="ghost"
  disabled={!imageLoader || error}
  on:click={() => imageLoader.loadImage(srcError)}
>
  Simulate error
</Button>

<ImageLoader bind:this={imageLoader} bind:error fadeIn {src}>
  <svelte:fragment slot="error">
    <Button kind="ghost" on:click={() => imageLoader.loadImage(src)}>
      Error. Try again
    </Button>
  </svelte:fragment>
</ImageLoader>
```

### Dynamic image source

Update the image source dynamically using the same image loader instance. This
allows for smooth transitions between different images.

```svelte
<script>
  import { Button, ImageLoader } from "carbon-components-svelte";

  const images = [
    "https://upload.wikimedia.org/wikipedia/commons/1/1b/Svelte_Logo.svg",
    "https://upload.wikimedia.org/wikipedia/commons/b/b9/Carbon-design-system-logo.png",
  ];

  let index = 0;

  $: src = images[index];
</script>

<Button
  kind="ghost"
  on:click={() => {
    index = index === 0 ? 1 : 0;
  }}
>
  Toggle image
</Button>

<div style:margin-top="1rem" style:width="100%" style:max-width="120px">
  <ImageLoader ratio="1x1" fadeIn {src} alt={src} />
</div>
```

---

### Component API

#### `ImageLoader` props

| Prop                 | Type                                                                     | Description                                                                                                                   | Default     |
| -------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `loading` (Reactive) | `boolean`                                                                | Set to `true` when `loaded` is `true` and `error` is false.                                                                   | `false`     |
| `loaded` (Reactive)  | `boolean`                                                                | Set to `true` when the image is loaded.                                                                                       | `false`     |
| `error` (Reactive)   | `boolean`                                                                | Set to `true` if an error occurs when loading the image.                                                                      | `false`     |
| `src`                | `string`                                                                 | Specify the image source.                                                                                                     | `""`        |
| `alt`                | `string`                                                                 | Specify the image alt text.                                                                                                   | `""`        |
| `ratio`              | `"2x1" \| "16x9" \| "4x3" \| "1x1" \| "3x4" \| "3x2" \| "9x16" \| "1x2"` | Specify the aspect ratio for the image wrapper.                                                                               | _undefined_ |
| `fadeIn`             | `boolean`                                                                | Set to `true` to fade in the image on load.<br />The duration uses the `fast-02` value following Carbon guidelines on motion. | `false`     |
| `loadImage`          | `(url?: string) => void`                                                 | Method invoked to load the image provided a `src` value.<br />If no URL is provided, uses the component's `src` prop.         | _undefined_ |

#### `ImageLoader` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `error`   | `Record<string, never>` |
| `loading` | `Record<string, never>` |

#### `ImageLoader` dispatched events

| Event      | Detail |
| ---------- | ------ |
| `on:load`  | `null` |
| `on:error` | `null` |

#### `ImageLoader` $$restProps

`ImageLoader` spreads `$$restProps` to the `img` element.


## InlineLoading

Inline loading indicators provide a compact loading indicator that can be
embedded within content. They are ideal for showing progress during inline
operations like form submissions or data updates.

### Default

Display a basic loading indicator with the default configuration.

```svelte
<script>
  import { InlineLoading } from "carbon-components-svelte";
</script>

<InlineLoading />
```

### With description

Add a descriptive text to provide context about the loading operation.

```svelte
<script>
  import { InlineLoading } from "carbon-components-svelte";
</script>

<InlineLoading description="Loading metrics..." />
```

### Status states

The component supports different status states to indicate progress:

- **active**: Shows an animated loading indicator
- **inactive**: Displays a static state
- **finished**: Shows a success state
- **error**: Displays an error state

```svelte
<script>
  import { InlineLoading } from "carbon-components-svelte";
</script>

<InlineLoading status="active" description="Submitting..." />
<InlineLoading status="inactive" description="Cancelling..." />
<InlineLoading status="finished" description="Success" />
<InlineLoading status="error" description="An error occurred" />
```

### UX example

See how to integrate the loading indicator in a real-world scenario.

```svelte
<script>
  import { Button, ButtonSet, InlineLoading } from "carbon-components-svelte";
  import { onDestroy } from "svelte";

  const descriptionMap = {
    active: "Submitting...",
    finished: "Success",
    inactive: "Cancelling...",
  };

  const stateMap = {
    active: "finished",
    inactive: "dormant",
    finished: "dormant",
  };

  let timeout = undefined;
  let state = "dormant"; // "dormant" | "active" | "finished" | "inactive"

  function reset(incomingState) {
    if (typeof timeout === "number") {
      clearTimeout(timeout);
    }

    if (incomingState) {
      timeout = setTimeout(() => {
        state = incomingState;
      }, 2000);
    }
  }

  onDestroy(reset);

  $: reset(stateMap[state]);
</script>

<ButtonSet>
  <Button
    kind="ghost"
    disabled={state === "dormant" || state === "finished"}
    on:click={() => (state = "inactive")}
  >
    Cancel
  </Button>
  {#if state !== "dormant"}
    <InlineLoading status={state} description={descriptionMap[state]} />
  {:else}
    <Button on:click={() => (state = "active")}>Submit</Button>
  {/if}
</ButtonSet>
```

---

### Component API

#### `InlineLoading` props

| Prop              | Type                                              | Description                                                                                                           | Default     |
| ----------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------- |
| `status`          | `"active" \| "inactive" \| "finished" \| "error"` | Set the loading status.                                                                                               | `"active"`  |
| `description`     | `string`                                          | Set the loading description.                                                                                          | _undefined_ |
| `iconDescription` | `string`                                          | Specify a description for the loading icon.<br />Defaults to the `status` prop for the "error" and "finished" states. | _undefined_ |
| `successDelay`    | `number`                                          | Specify the timeout delay (ms) after `status` is set to "success"                                                     | `1500`      |

#### `InlineLoading` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `InlineLoading` dispatched events

| Event        | Detail |
| ------------ | ------ |
| `on:success` | `null` |

#### `InlineLoading` $$restProps

`InlineLoading` spreads `$$restProps` to the `div` element.


## InlineNotification

Inline notifications display contextual messages inline with content. They
support various types of notifications (error, warning, success, info) and can
include actions. Use them to provide feedback or important information to users.

See
[detailed usage](https://carbondesignsystem.com/components/notification/usage).  
See also: [ToastNotification](ToastNotification)

### Default

Display a basic error notification with title and subtitle by default.

```svelte
<script>
  import { InlineNotification } from "carbon-components-svelte";
</script>

<InlineNotification
  title="Error:"
  subtitle="An internal server error occurred."
/>
```

### Prevent default close behavior

The component is controlled, allowing you to prevent the default close behavior
using `e.preventDefault()`.

```svelte
<script>
  import { InlineNotification } from "carbon-components-svelte";
</script>

<InlineNotification
  title="Error"
  subtitle="An internal server error occurred."
  on:close={(e) => {
    e.preventDefault();
    // custom close logic (e.g., transitions)
  }}
/>

## Reusable notification Control the notification visibility by binding to the
`open` prop. This allows you to show, hide, and reuse the same notification
component with different messages. The `open` prop defaults to `true`.
```

```svelte
<script>
  import {
    Button,
    ButtonSet,
    InlineNotification,
    Stack,
  } from "carbon-components-svelte";

  let open = false;
  let kind = "error";
  let title = "Error:";
  let subtitle = "An internal server error occurred.";

  function showError() {
    kind = "error";
    title = "Error:";
    subtitle = "An internal server error occurred.";
    open = true;
  }

  function showSuccess() {
    kind = "success";
    title = "Success:";
    subtitle = "Your settings have been saved.";
    open = true;
  }

  function showWarning() {
    kind = "warning";
    title = "Warning:";
    subtitle = "Please review your changes before continuing.";
    open = true;
  }
</script>

<Stack gap={5}>
  <ButtonSet>
    <Button on:click={showSuccess}>Show success</Button>
    <Button kind="ghost" on:click={showWarning}>Show warning</Button>
    <Button kind="danger-ghost" on:click={showError}>Show error</Button>
  </ButtonSet>

  <InlineNotification bind:open {kind} {title} {subtitle} />
</Stack>
```

### Slottable title and subtitle

Customize the notification content using slots for more flexibility.

```svelte
<script>
  import { InlineNotification } from "carbon-components-svelte";
</script>

<InlineNotification>
  <strong slot="titleChildren">Error: </strong>
  <strong slot="subtitleChildren">An internal server error occurred.</strong>
</InlineNotification>
```

### Optional title and subtitle

Title and subtitle are optional and only render when provided.

```svelte
<script>
  import { InlineNotification } from "carbon-components-svelte";
</script>

<InlineNotification subtitle="An internal server error occurred." />
<InlineNotification title="An error occurred." />
```

### Accessible icon descriptions

Make notifications more accessible by providing custom descriptions for icons.

```svelte
<script>
  import { InlineNotification } from "carbon-components-svelte";
</script>

<InlineNotification
  title="错误"
  subtitle="发生内部服务器错误"
  statusIconDescription="错误图标"
  closeButtonDescription="关闭通知"
/>
```

### Hidden close button

Create a persistent notification by hiding the close button.

```svelte
<script>
  import { InlineNotification } from "carbon-components-svelte";
</script>

<InlineNotification
  hideCloseButton
  kind="warning"
  title="Scheduled maintenance:"
  subtitle="Maintenance will last 2-4 hours."
/>
```

### With actions

Add interactive elements to notifications using the actions slot.

```svelte
<script>
  import {
    InlineNotification,
    NotificationActionButton,
  } from "carbon-components-svelte";
</script>

<InlineNotification
  kind="warning"
  title="Scheduled maintenance:"
  subtitle="Maintenance will last 2-4 hours."
>
  <svelte:fragment slot="actions">
    <NotificationActionButton>Learn more</NotificationActionButton>
  </svelte:fragment>
</InlineNotification>
```

### Action button as link

The notification action button accepts an `href` prop to render as a link
instead of a button.

```svelte
<script>
  import {
    InlineNotification,
    NotificationActionButton,
  } from "carbon-components-svelte";
</script>

<InlineNotification
  kind="info"
  title="New features available:"
  subtitle="Check out what's new in this release."
>
  <svelte:fragment slot="actions">
    <NotificationActionButton
      href="https://github.com/carbon-design-system/carbon-components-svelte/releases"
      target="_blank">View release notes</NotificationActionButton
    >
  </svelte:fragment>
</InlineNotification>
```

### Notification variants

The component supports different notification types:

```svelte
<script>
  import { InlineNotification } from "carbon-components-svelte";
</script>

<InlineNotification
  kind="error"
  title="Error:"
  subtitle="An internal server error occurred."
/>
<InlineNotification
  kind="info"
  title="New updates:"
  subtitle="Restart to get the latest updates."
/>
<InlineNotification
  kind="info-square"
  title="New updates:"
  subtitle="Restart to get the latest updates."
/>
<InlineNotification
  kind="success"
  title="Success:"
  subtitle="Your settings have been saved."
/>
<InlineNotification
  kind="warning"
  title="Scheduled maintenance:"
  subtitle="Maintenance will last 2-4 hours."
/>
<InlineNotification
  kind="warning-alt"
  title="Scheduled maintenance:"
  subtitle="Maintenance will last 2-4 hours."
/>
```

### Low contrast

Use low contrast variants for less prominent notifications.

```svelte
<script>
  import { InlineNotification } from "carbon-components-svelte";
</script>

<InlineNotification
  lowContrast
  kind="error"
  title="Error:"
  subtitle="An internal server error occurred."
/>
<InlineNotification
  lowContrast
  kind="info"
  title="New updates:"
  subtitle="Restart to get the latest updates."
/>
<InlineNotification
  lowContrast
  kind="info-square"
  title="New updates:"
  subtitle="Restart to get the latest updates."
/>
<InlineNotification
  lowContrast
  kind="success"
  title="Success:"
  subtitle="Your settings have been saved."
/>
<InlineNotification
  lowContrast
  kind="warning"
  title="Scheduled maintenance:"
  subtitle="Maintenance will last 2-4 hours."
/>
<InlineNotification
  lowContrast
  kind="warning-alt"
  title="Scheduled maintenance:"
  subtitle="Maintenance will last 2-4 hours."
/>
```

---

### Component API

#### `InlineNotification` props

| Prop                     | Type                                                                            | Description                                                             | Default                |
| ------------------------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------- |
| `open` (Reactive)        | `boolean`                                                                       | Set to `true` to show the notification, `false` to hide it.             | `true`                 |
| `kind`                   | `"error" \| "info" \| "info-square" \| "success" \| "warning" \| "warning-alt"` | Specify the kind of notification.                                       | `"error"`              |
| `lowContrast`            | `boolean`                                                                       | Set to `true` to use the low contrast variant                           | `false`                |
| `timeout`                | `number`                                                                        | Set the timeout duration (ms) to hide the notification after opening it | `0`                    |
| `role`                   | `string`                                                                        | Set the `role` attribute                                                | `"alert"`              |
| `title`                  | `string`                                                                        | Specify the title text                                                  | `""`                   |
| `subtitle`               | `string`                                                                        | Specify the subtitle text                                               | `""`                   |
| `hideCloseButton`        | `boolean`                                                                       | Set to `true` to hide the close button                                  | `false`                |
| `statusIconDescription`  | `string`                                                                        | Specify the ARIA label for the status icon.                             | `${kind} icon`         |
| `closeButtonDescription` | `string`                                                                        | Specify the ARIA label for the close button                             | `"Close notification"` |

#### `InlineNotification` slots

| Slot               | Detail                  |
| ------------------ | ----------------------- |
| `default`          | `Record<string, never>` |
| `actions`          | `Record<string, never>` |
| `subtitleChildren` | `Record<string, never>` |
| `titleChildren`    | `Record<string, never>` |

#### `InlineNotification` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `InlineNotification` dispatched events

| Event      | Detail                             |
| ---------- | ---------------------------------- |
| `on:close` | `{<br /> timeout: boolean;<br />}` |

#### `InlineNotification` $$restProps

`InlineNotification` spreads `$$restProps` to the `div` element.

#### `NotificationActionButton` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `NotificationActionButton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `NotificationActionButton` $$restProps

`NotificationActionButton` spreads `$$restProps` to the `Button` component.


## Link

Links provide styled hyperlinks with various customization options. They support
different sizes, states, and can include icons. The outbound link variant
automatically handles external links with proper security attributes.

### Default

Create a basic link with the default styling.

```svelte
<script>
  import { Link } from "carbon-components-svelte";
</script>

<Link href="https://www.carbondesignsystem.com/">Carbon Design System</Link>
```

### Opens in new tab

For external links that open in a new tab, the component automatically adds
security attributes (`rel="noopener noreferrer"`). You can override the `rel`
attribute if needed.

```svelte
<script>
  import { Link } from "carbon-components-svelte";
</script>

<Link href="https://www.carbondesignsystem.com/" target="_blank">
  Carbon Design System
</Link>
```

### Outbound link

Use the outbound link as a convenient alternative for external links.

```svelte
<script>
  import { OutboundLink } from "carbon-components-svelte";
</script>

<OutboundLink href="https://www.carbondesignsystem.com/">
  Carbon Design System
</OutboundLink>
```

### Inline variant

Create links that flow naturally with surrounding text.

```svelte
<script>
  import { Link } from "carbon-components-svelte";
</script>

<div>
  Visit the
  <Link inline href="https://www.carbondesignsystem.com/">
    Carbon Design System
  </Link>.
</div>
```

### Link with icon

Add icons to links for better visual context. Note that `inline` must be `false`
when using icons.

```svelte
<script>
  import { Link } from "carbon-components-svelte";
  import Carbon from "carbon-icons-svelte/lib/Carbon.svelte";
</script>

<div>
  Visit the
  <Link href="https://www.carbondesignsystem.com/" icon={Carbon}>
    Carbon Design System
  </Link>.
</div>
```

### Size variants

The component supports different sizes to match your design needs:

```svelte
<script>
  import { Link } from "carbon-components-svelte";
</script>

<Link size="lg" href="https://www.carbondesignsystem.com/">Large link</Link>
<br />
<Link href="https://www.carbondesignsystem.com/">Default link</Link>
<br />
<Link size="sm" href="https://www.carbondesignsystem.com/">Small link</Link>
```

### Disabled state

Disabled links render as plain text while maintaining accessibility.

```svelte
<script>
  import { Link } from "carbon-components-svelte";
</script>

<Link disabled href="https://www.carbondesignsystem.com/">Disabled link</Link>
```

### Visited styles

Show visited state styling for links.

```svelte
<script>
  import { Link } from "carbon-components-svelte";
</script>

<Link visited href="https://www.carbondesignsystem.com/">Visited link</Link>
```

---

### Component API

#### `Link` props

| Prop             | Type                        | Description                                                | Default     |
| ---------------- | --------------------------- | ---------------------------------------------------------- | ----------- |
| `ref` (Reactive) | `null \| HTMLAnchorElement` | Obtain a reference to the top-level HTML element           | `null`      |
| `size`           | `"sm" \| "lg"`              | Specify the size of the link.                              | _undefined_ |
| `href`           | `string`                    | Specify the href value.                                    | _undefined_ |
| `inline`         | `boolean`                   | Set to `true` to use the inline variant                    | `false`     |
| `icon`           | `any`                       | Specify the icon to render.<br />`inline` must be `false`. | _undefined_ |
| `disabled`       | `boolean`                   | Set to `true` to disable the checkbox                      | `false`     |
| `visited`        | `boolean`                   | Set to `true` to allow visited styles                      | `false`     |

#### `Link` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |
| `icon`    | `Record<string, never>` |

#### `Link` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `Link` $$restProps

`Link` spreads `$$restProps` to the `a` element.

#### `OutboundLink` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `OutboundLink` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `OutboundLink` $$restProps

`OutboundLink` spreads `$$restProps` to the `Link` component.


## Loading

Loading indicators provide a full-screen or inline loading indicator. They are
ideal for showing progress during page loads or data fetching operations.

### Default

Display a loading indicator with a semi-transparent overlay that covers the
entire viewport.

```svelte
<script>
  import { Loading } from "carbon-components-svelte";
</script>

<Loading />
```

### No overlay

Show a loading indicator without the overlay, allowing interaction with the
underlying content.

```svelte
<script>
  import { Loading } from "carbon-components-svelte";
</script>

<Loading withOverlay={false} />
```

### Small size

Display a more compact loading indicator.

```svelte
<script>
  import { Loading } from "carbon-components-svelte";
</script>

<Loading withOverlay={false} small />
```

---

### Component API

#### `Loading` props

| Prop          | Type      | Description                                           | Default     |
| ------------- | --------- | ----------------------------------------------------- | ----------- |
| `small`       | `boolean` | Set to `true` to use the small variant                | `false`     |
| `active`      | `boolean` | Set to `false` to disable the active state            | `true`      |
| `withOverlay` | `boolean` | Set to `false` to disable the overlay                 | `true`      |
| `description` | `string`  | Specify the description to describe the loading state | `"loading"` |

#### `Loading` $$restProps

`Loading` spreads `$$restProps` to the `div` element.


## LocalStorage

Local storage provides a reactive wrapper around the
[Window.localStorage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).
It is useful for persisting user preferences and application state across page
reloads.

The component listens for the
[storage event](https://developer.mozilla.org/en-US/docs/Web/API/Window/storage_event),
so changes made in one browser tab are automatically synchronized to other tabs
with the same key.

### Basic example

See how the component maintains state across page reloads. Toggle the switch and
refresh the page to see the persisted state.

```svelte
<script>
  import { LocalStorage, Toggle } from "carbon-components-svelte";

  let toggled = false;
  let events = [];

  $: document.documentElement.setAttribute("theme", toggled ? "g100" : "white");
</script>

<LocalStorage
  key="dark-mode"
  bind:value={toggled}
  on:save={() => {
    events = [...events, { event: "on:save" }];
  }}
  on:update={({ detail }) => {
    events = [...events, { event: "on:update", detail }];
  }}
/>

<Toggle size="sm" labelText="Dark mode" bind:toggled />

<br />

<pre>{JSON.stringify(events, null, 2)}</pre>
```

### Reactive key

The `key` prop is also reactive, allowing you to dynamically switch between
different storage keys. This is useful for managing per-user settings or
multiple contexts.

In this example, each user has their own theme preference stored under a
separate key. When you switch users, the component automatically loads that
user's saved preference.

```svelte
<script>
  import {
    LocalStorage,
    RadioButton,
    RadioButtonGroup,
  } from "carbon-components-svelte";

  let selectedUser = "user-1";
  let theme = "white";

  $: storageKey = `local-storage-reactive-example-${selectedUser}`;
</script>

<div style:margin-bottom="var(--cds-layout-01)">
  Try selecting different users and changing their theme preferences. Each
  user's preference is stored separately and persists across page reloads.
</div>

<LocalStorage key={storageKey} bind:value={theme} />

<RadioButtonGroup legendText="Select user" bind:selected={selectedUser}>
  <RadioButton labelText="User 1" value="user-1" />
  <RadioButton labelText="User 2" value="user-2" />
  <RadioButton labelText="User 3" value="user-3" />
</RadioButtonGroup>

<br />

<RadioButtonGroup legendText="Theme preference" bind:selected={theme}>
  <RadioButton labelText="White" value="white" />
  <RadioButton labelText="Gray 10" value="g10" />
  <RadioButton labelText="Gray 80" value="g80" />
  <RadioButton labelText="Gray 90" value="g90" />
  <RadioButton labelText="Gray 100" value="g100" />
</RadioButtonGroup>

<div
  style="margin-top: var(--cds-layout-01)"
  style:margin-bottom="var(--cds-layout-01)"
>
  <div>
    <strong>Current key:</strong>
    {storageKey}
  </div>
  <div>
    <strong>Current theme:</strong>
    {theme}
  </div>
</div>
```

### Clear item, clear all

The component provides methods to manage stored data:

- `clearItem`: Remove a specific key-value pair
- `clearAll`: Remove all stored data

Use `bind:this` to access these methods. In this example, try toggling the
switch, refreshing the page, then clearing the storage.

```svelte
<script>
  import { Button, LocalStorage, Toggle } from "carbon-components-svelte";

  let storage;
  let toggled = false;

  $: document.documentElement.setAttribute("theme", toggled ? "g100" : "white");
</script>

<LocalStorage bind:this={storage} bind:value={toggled} />

<Toggle size="sm" labelText="Dark mode" bind:toggled />

<br />
<br />

<Button size="small" on:click={storage.clearAll}>Clear storage</Button>
```

---

### Component API

#### `LocalStorage` props

| Prop               | Type         | Description                                                     | Default               |
| ------------------ | ------------ | --------------------------------------------------------------- | --------------------- |
| `value` (Reactive) | `any`        | Provide a value to persist.                                     | `""`                  |
| `key`              | `string`     | Specify the local storage key.                                  | `"local-storage-key"` |
| `clearItem`        | `() => void` | Remove the persisted key value from the browser's local storage | _undefined_           |
| `clearAll`         | `() => void` | Clear all key values from the browser's local storage           | _undefined_           |

#### `LocalStorage` dispatched events

| Event       | Detail                                             | Description                                                                                                                     |
| ----------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `on:save`   | `null`                                             |                                                                                                                                 |
| `on:update` | `{<br /> prevValue: any;<br /> value: any;<br />}` | Fires when the stored value changes, either from a bound value update or when localStorage is modified from another tab/window. |


## Modal

Modals provide a focused dialog for user interactions, confirmations, or data
entry. They support various sizes, states, and customization options to create
accessible and user-friendly modal experiences.

**Modal vs ComposedModal**

The modal is an all-in-one component configured through props, making it ideal
for standard modal dialogs. For more complex layouts or fine-grained control,
use [ComposedModal](/components/ComposedModal) instead.

**Focus behavior**

When the modal opens, focus is set using the following priority:

1. The element matching `selectorPrimaryFocus` (default:
   `[data-modal-primary-focus]`)
2. The first input, textarea, or select (for transactional modals with form
   fields)
3. The primary action button (for confirmation modals), or the cancel button
   (for destructive modals with `danger={true}`)
4. The close button (for passive modals or modals without a primary button)

After closing the modal, focus is returned to the element that triggered the
modal.

### Default

Display a modal dialog with a header, content area, and footer by default.

Create a basic modal dialog with primary and secondary actions. This variant is
ideal for confirming user actions or gathering input.

```svelte
<script>
  import { Button, Modal } from "carbon-components-svelte";

  let open = false;
</script>

<Button on:click={() => (open = true)}>Create database</Button>

<Modal
  bind:open
  modalHeading="Create database"
  primaryButtonText="Confirm"
  secondaryButtonText="Cancel"
  on:click:button--secondary={() => (open = false)}
  on:open
  on:close
  on:submit
>
  <p>Create a new Cloudant database in the US South region.</p>
</Modal>
```

### With Portal

Wrap the modal in a portal to escape parent containers with `overflow: hidden`
or z-index stacking contexts. This ensures the modal appears above all content
and isn't clipped by parent boundaries.

```svelte
<script>
  import { Button, Modal, Portal, Stack } from "carbon-components-svelte";

  let open = false;
</script>

<Stack gap={5} style="overflow: hidden; position: relative; height: 200px;">
  <p>
    This container hides overflowing content. Without a portal, the modal would
    be clipped.
  </p>
  <div>
    <Button on:click={() => (open = true)}>Open modal</Button>
  </div>
  <Portal>
    <Modal
      bind:open
      modalHeading="Modal in Portal"
      primaryButtonText="Confirm"
      secondaryButtonText="Cancel"
      on:click:button--secondary={() => (open = false)}
    >
      <p>
        This modal is rendered in a portal, escaping the parent container's
        overflow constraints and ensuring it appears above all other content.
      </p>
    </Modal>
  </Portal>
</Stack>
```

### Modal with dropdowns

When components with menus are used inside a modal, such as a combo box,
dropdown, multi-select, date picker, or overflow menu, these components
automatically render their menus in a floating portal when inside a modal, so
menus are positioned relative to their trigger and are not clipped by the
modal's overflow or z-index stacking.

Set `portalMenu={false}` on these components to opt out. In this example, the
modal itself is wrapped in a portal.

```svelte
<script>
  import {
    Button,
    ComboBox,
    Dropdown,
    Modal,
    MultiSelect,
    Portal,
    Stack,
  } from "carbon-components-svelte";

  let open = false;

  const contactItems = [
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
    { id: "3", text: "Teams" },
    { id: "4", text: "Phone" },
  ];
</script>

<Button on:click={() => (open = true)}>Open modal</Button>

<Portal>
  <Modal
    bind:open
    size="sm"
    modalHeading="Add a contact"
    primaryButtonText="Add"
    secondaryButtonText="Cancel"
    on:click:button--secondary={() => (open = false)}
  >
    <Stack gap={4}>
      <ComboBox
        light
        labelText="Contact method"
        placeholder="Select contact method"
        items={contactItems}
      />
      <Dropdown
        labelText="Preferred channel"
        selectedId="0"
        items={contactItems}
      />
      <MultiSelect
        labelText="Notification methods"
        label="Select methods..."
        items={contactItems}
      />
    </Stack>
  </Modal>
</Portal>
```

### Custom focus

Use `selectorPrimaryFocus` to override the default and target a specific element
when the automatic first-input focus is not desired.

```svelte
<script>
  import { Button, Modal, Stack, TextInput } from "carbon-components-svelte";

  let open = false;
</script>

<Button on:click={() => (open = true)}>Create database</Button>

<Modal
  bind:open
  modalHeading="Create database"
  primaryButtonText="Confirm"
  secondaryButtonText="Cancel"
  selectorPrimaryFocus="#advanced-options"
  on:click:button--secondary={() => (open = false)}
  on:open
  on:close
  on:submit
>
  <Stack gap={3}>
    <p>Create a new Cloudant database in the US South region.</p>
    <TextInput
      id="db-name"
      labelText="Database name"
      placeholder="Enter database name..."
    />
    <Button id="advanced-options" kind="ghost" size="small">
      Advanced options
    </Button>
  </Stack>
</Modal>
```

### Danger modal

Display critical actions or destructive operations with the danger variant. This
style emphasizes the severity of the action.

By default, the cancel button receives focus instead of the critical button to
prevent accidental destructive actions.

```svelte
<script>
  import { Button, Modal } from "carbon-components-svelte";

  let open = false;
</script>

<Button kind="danger" on:click={() => (open = true)}>Delete all</Button>

<Modal
  danger
  bind:open
  modalHeading="Delete all instances"
  primaryButtonText="Delete"
  secondaryButtonText="Cancel"
  on:click:button--secondary={() => (open = false)}
  on:open
  on:close
  on:submit
>
  <p>This is a permanent action and cannot be undone.</p>
</Modal>
```

### Passive modal

Create a non-interactive modal for displaying information. This variant lacks
action buttons and focuses on content presentation. Since there is no primary
button, the close button will receive focus when the modal opens.

```svelte
<script>
  import { Button, Modal } from "carbon-components-svelte";

  let open = false;
</script>

<Button kind="tertiary" on:click={() => (open = true)}>Learn more</Button>

<Modal passiveModal bind:open modalHeading="IBM Cloudant" on:open on:close>
  <p>
    IBM Cloudant is a distributed, secure database with global availability and
    zero vendor lock-in used to build web and mobile apps at scale.
  </p>
</Modal>
```

### With form submission

Connect the modal's primary button to a form using the `formId` prop. This
enables native form submission even though the button is outside the form
element. Clicking the primary button or pressing Enter will trigger the form's
submit event.

```svelte
<script>
  import { Button, Modal, Stack, TextInput } from "carbon-components-svelte";

  let open = false;
  let name = "";
  let email = "";

  function handleSubmit() {
    console.log("Form submitted:", { name, email });
    open = false;
  }
</script>

<Button on:click={() => (open = true)}>Create account</Button>

<Modal
  bind:open
  modalHeading="Create account"
  primaryButtonText="Submit"
  secondaryButtonText="Cancel"
  hasForm
  formId="account-form"
  on:click:button--secondary={() => (open = false)}
>
  <form id="account-form" on:submit|preventDefault={handleSubmit}>
    <Stack gap={5}>
      <TextInput bind:value={name} labelText="Name" placeholder="Enter name" />
      <TextInput
        bind:value={email}
        labelText="Email"
        type="email"
        placeholder="Enter email"
      />
    </Stack>
  </form>
</Modal>
```

### Has scrolling content

Enable vertical scrolling for modals with lengthy content. This ensures all
content remains accessible while maintaining a reasonable modal height.

```svelte
<script>
  import { Button, Modal } from "carbon-components-svelte";

  let open = false;
</script>

<Button on:click={() => (open = true)}>Create database</Button>

<Modal bind:open passiveModal modalHeading="About Cloudant" hasScrollingContent>
  <p>
    Cloudant is a fully managed, distributed database optimized for heavy
    workloads and fast-growing web and mobile apps, IBM Cloudant is available as
    an IBM Cloud® service with a 99.99% SLA.
  </p>
  <br />
  <p>
    The database elastically scales throughput and storage, and its API and
    replication protocols are compatible with Apache CouchDB for hybrid or
    multicloud architectures.
  </p>
</Modal>
```

### Multiple modals

Stack multiple modals for complex workflows. Each modal maintains its own state
and focus management.

```svelte
<script>
  import { Button, Modal } from "carbon-components-svelte";

  let openCreate = false;
  let openDelete = false;
</script>

<Button on:click={() => (openCreate = true)}>Create database</Button>
<Button kind="danger-tertiary" on:click={() => (openDelete = true)}>
  Delete database
</Button>

<Modal
  bind:open={openCreate}
  modalHeading="Create database"
  primaryButtonText="Confirm"
  secondaryButtonText="Cancel"
  on:click:button--secondary={() => (openCreate = false)}
  on:open
  on:close
  on:submit
>
  <p>Create a new Cloudant database in the US South region.</p>
</Modal>

<Modal
  danger
  bind:open={openDelete}
  modalHeading="Delete database"
  primaryButtonText="Delete"
  secondaryButtonText="Cancel"
  on:click:button--secondary={() => (openDelete = false)}
  on:open
  on:close
  on:submit
>
  <p>This is a permanent action and cannot be undone.</p>
</Modal>
```

### Multiple secondary buttons

Add up to two secondary actions using the `secondaryButtons` prop. This provides
more flexibility than the single `secondaryButtonText` option.

```svelte
<script>
  import { Button, Modal } from "carbon-components-svelte";

  let open = false;
</script>

<Button on:click={() => (open = true)}>Create database</Button>

<Modal
  bind:open
  modalHeading="Create database"
  primaryButtonText="Confirm"
  secondaryButtons={[{ text: "Cancel" }, { text: "Edit" }]}
  on:click:button--secondary={({ detail }) => {
    if (detail.text === "Cancel") open = false;
    if (detail.text === "Edit") console.log("Edit");
  }}
  on:open
  on:close
  on:submit
>
  <p>Create a new Cloudant database in the US South region.</p>
</Modal>
```

### Extra-small size

Use the extra-small size for compact notifications by setting `size` to `"xs"`.
This is ideal for simple confirmations.

```svelte
<script>
  import { Button, Modal } from "carbon-components-svelte";

  let open = false;
</script>

<Button on:click={() => (open = true)}>Create database</Button>

<Modal
  size="xs"
  bind:open
  modalHeading="Create database"
  primaryButtonText="Confirm"
  secondaryButtonText="Cancel"
  on:click:button--secondary
  on:open
  on:close
  on:submit
>
  <p>Create a new Cloudant database in the US South region.</p>
</Modal>
```

### Small size

Use the small size for simple confirmations by setting `size` to `"sm"`. This
provides a more focused dialog.

```svelte
<script>
  import { Button, Modal } from "carbon-components-svelte";

  let open = false;
</script>

<Button on:click={() => (open = true)}>Create database</Button>

<Modal
  size="sm"
  bind:open
  modalHeading="Create database"
  primaryButtonText="Confirm"
  secondaryButtonText="Cancel"
  on:click:button--secondary
  on:open
  on:close
  on:submit
>
  <p>Create a new Cloudant database in the US South region.</p>
</Modal>
```

### Large size

Use the large size for complex content by setting `size` to `"lg"`. This
provides more space for detailed information.

```svelte
<script>
  import { Button, Modal } from "carbon-components-svelte";

  let open = false;
</script>

<Button on:click={() => (open = true)}>Create database</Button>

<Modal
  size="lg"
  bind:open
  modalHeading="Create database"
  primaryButtonText="Confirm"
  secondaryButtonText="Cancel"
  on:click:button--secondary
  on:open
  on:close
  on:submit
>
  <p>Create a new Cloudant database in the US South region.</p>
</Modal>
```

### Prevent default close behavior

The modal dispatches a cancelable `close` event, allowing you to prevent the
modal from closing using `e.preventDefault()`. The event includes a `trigger`
property indicating what triggered the close attempt: `"escape-key"`,
`"outside-click"`, or `"close-button"`.

```svelte
<script>
  import { Button, InlineNotification, Modal } from "carbon-components-svelte";

  let open = false;
  let hasUnsavedChanges = true;
  let showWarning = false;
</script>

<Button
  on:click={() => {
    open = true;
    hasUnsavedChanges = true;
    showWarning = false;
  }}>Open modal with unsaved changes</Button
>

<Modal
  bind:open
  modalHeading="Edit profile"
  primaryButtonText="Save"
  secondaryButtonText="Discard changes"
  on:click:button--secondary={() => {
    hasUnsavedChanges = false;
    open = false;
  }}
  on:close={(e) => {
    console.log("Close triggered by:", e.detail.trigger);
    if (hasUnsavedChanges) {
      e.preventDefault();
      showWarning = true;
    }
  }}
  on:submit={() => {
    hasUnsavedChanges = false;
    open = false;
  }}
>
  {#if showWarning}
    <InlineNotification
      kind="warning"
      title="Unsaved changes"
      subtitle="Please save or discard your changes before closing."
      hideCloseButton
    />
  {/if}
  <p>You have unsaved changes. Click "Save" to apply them.</p>
</Modal>
```

### Prevent close on outside click

Disable closing the modal when clicking outside by setting
`preventCloseOnClickOutside` to `true`. This is useful for transactional modals
where explicit user action is required.

```svelte
<script>
  import { Button, Modal } from "carbon-components-svelte";

  let open = false;
</script>

<Button on:click={() => (open = true)}>Create database</Button>

<Modal
  preventCloseOnClickOutside
  bind:open
  modalHeading="Create database"
  primaryButtonText="Confirm"
  secondaryButtonText="Cancel"
  on:click:button--secondary
  on:open
  on:close
  on:submit
>
  <p>Create a new Cloudant database in the US South region.</p>
</Modal>
```

### Button with icon

Enhance modal buttons with icons for better visual context and clarity. This
example shows how to add icons to modal actions.

```svelte
<script>
  import { Button, Modal } from "carbon-components-svelte";
  import Send from "carbon-icons-svelte/lib/Send.svelte";

  let open = false;
</script>

<Button on:click={() => (open = true)}>Create database</Button>

<Modal
  bind:open
  modalHeading="Invite someone"
  primaryButtonText="Send invitation"
  primaryButtonIcon={Send}
  secondaryButtonText="Cancel"
>
  <p>Do you really want to invite someone?</p>
</Modal>
```

---

### Component API

#### `Modal` props

| Prop                         | Type                                     | Description                                                                                                                                                   | Default                             |
| ---------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `open` (Reactive)            | `boolean`                                | Set to `true` to open the modal                                                                                                                               | `false`                             |
| `ref` (Reactive)             | `null \| HTMLDivElement`                 | Obtain a reference to the top-level HTML element                                                                                                              | `null`                              |
| `size`                       | `"xs" \| "sm" \| "lg"`                   | Set the size of the modal.                                                                                                                                    | _undefined_                         |
| `danger`                     | `boolean`                                | Set to `true` to use the danger variant                                                                                                                       | `false`                             |
| `alert`                      | `boolean`                                | Set to `true` to enable alert mode                                                                                                                            | `false`                             |
| `passiveModal`               | `boolean`                                | Set to `true` to use the passive variant                                                                                                                      | `false`                             |
| `modalHeading`               | `string`                                 | Specify the modal heading.                                                                                                                                    | _undefined_                         |
| `modalLabel`                 | `string`                                 | Specify the modal label.                                                                                                                                      | _undefined_                         |
| `modalAriaLabel`             | `string`                                 | Specify the ARIA label for the modal.                                                                                                                         | _undefined_                         |
| `iconDescription`            | `string`                                 | Specify the ARIA label for the close icon                                                                                                                     | `"Close the modal"`                 |
| `hasForm`                    | `boolean`                                | Set to `true` if the modal contains form elements                                                                                                             | `false`                             |
| `formId`                     | `string`                                 | Specify the ID of a form element to associate with the primary button.<br />This enables the primary button to submit the form from outside the form element. | _undefined_                         |
| `hasScrollingContent`        | `boolean`                                | Set to `true` if the modal contains scrolling content                                                                                                         | `false`                             |
| `primaryButtonText`          | `string`                                 | Specify the primary button text                                                                                                                               | `""`                                |
| `primaryButtonDisabled`      | `boolean`                                | Set to `true` to disable the primary button                                                                                                                   | `false`                             |
| `primaryButtonIcon`          | `any`                                    | Specify the primary button icon.                                                                                                                              | _undefined_                         |
| `shouldSubmitOnEnter`        | `boolean`                                | Set to `true` for the "submit" and "click:button--primary" events<br />to be dispatched when pressing "Enter".                                                | `true`                              |
| `secondaryButtonText`        | `string`                                 | Specify the secondary button text                                                                                                                             | `""`                                |
| `secondaryButtons`           | `[{ text: string; }, { text: string; }]` | 2-tuple prop to render two secondary buttons for a 3 button modal.<br />Supersedes `secondaryButtonText`.                                                     | `[]`                                |
| `selectorPrimaryFocus`       | `string`                                 | Specify a selector to be focused when opening the modal                                                                                                       | `"[data-modal-primary-focus]"`      |
| `preventCloseOnClickOutside` | `boolean`                                | Set to `true` to prevent the modal from closing when clicking outside                                                                                         | `false`                             |
| `id`                         | `string`                                 | Set an id for the top-level element                                                                                                                           | `ccs-${Math.random().toString(36)}` |

#### `Modal` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |
| `heading` | `Record<string, never>` |
| `label`   | `Record<string, never>` |

#### `Modal` forwarded events

| Event           |
| --------------- |
| `on:keydown`    |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `Modal` dispatched events

| Event                        | Detail                                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------------------------- |
| `on:close`                   | `{<br /> trigger:<br /> \| "escape-key"<br /> \| "outside-click"<br /> \| "close-button";<br />}` |
| `on:transitionend`           | `{<br /> open: boolean;<br />}`                                                                   |
| `on:click:button--secondary` | `{<br /> text: string;<br />}`                                                                    |
| `on:submit`                  | `null`                                                                                            |
| `on:click:button--primary`   | `null`                                                                                            |
| `on:open`                    | `null`                                                                                            |

#### `Modal` $$restProps

`Modal` spreads `$$restProps` to the `div` element.


## MultiSelect

Multi-selects provide a dropdown interface for selecting multiple options using
checkboxes. They support filtering, custom formatting, and various states. Each
item must have a unique `id` property for proper functionality.

> [!NOTE] Every `items` object must have a unique "id" property.

### Default

Create a basic multi-select dropdown with three contact methods. By default,
items are ordered alphabetically.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Format item display text

Format the display text of items using the `itemToString` prop. This example
appends the item ID in parentheses.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  itemToString={(item) => {
    return item.text + " (" + item.id + ")";
  }}
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
  sortItem={() => {}}
/>

## Custom slot Override the default slot to customize item rendering. This
example shows how to access and use the item and index values.
```

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
  let:item
  let:index
>
  <div>
    <strong>{item.text}</strong>
  </div>
  <div>
    id: {item.id} - index:
    {index}
  </div>
</MultiSelect>

<style>
  :global(.bx--list-box__menu-item, .bx--list-box__menu-item__option) {
    height: auto;
  }

  :global(.bx--checkbox-label-text) {
    display: block;
  }
</style>
```

### No alphabetical ordering

Prevent automatic alphabetical ordering by passing a no-op function to
`sortItem`. This maintains the original order of items.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
  sortItem={() => {}}
/>
```

### Filterable

Enable filtering by setting `filterable` to `true`. This example includes a
placeholder text for the filter input.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  spellcheck="false"
  filterable
  labelText="Contact"
  placeholder="Filter contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Initial selected items

Pre-select items by passing an array of item IDs to `selectedIds`. This example
pre-selects Slack and Email.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  selectedIds={["0", "1"]}
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Multiple multi-select dropdowns

This example demonstrates how to manage multiple dropdowns in a form with
coordinated state.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";

  const items = [
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ];

  let multiselect1_selectedIds = ["0"];
  let multiselect2_selectedIds = ["1", "2"];

  const formatSelected = (i) =>
    i.length === 0
      ? "N/A"
      : i.map((id) => items.find((item) => item.id === id).text).join(", ");

  $: primary = formatSelected(multiselect1_selectedIds);
  $: secondary = formatSelected(multiselect2_selectedIds);
</script>

<MultiSelect
  labelText="Primary contact"
  bind:selectedIds={multiselect1_selectedIds}
  label="Select contact methods..."
  {items}
/>

<div>Primary: {primary}</div>

<MultiSelect
  labelText="Secondary contact"
  bind:selectedIds={multiselect2_selectedIds}
  label="Select contact methods..."
  {items}
/>

<div>Secondary: {secondary}</div>

<style>
  div {
    margin: var(--cds-layout-01) 0 var(--cds-layout-03);
  }
</style>
```

### Format checkbox values

Customize checkbox attributes using the `itemToInput` prop. This example sets a
consistent name for all checkboxes.

Use the `itemToInput` prop to customize the user-selectable checkbox values.
This will also override the underlying hidden inputs used for form submission.

```js
itemToInput={(item) => {
  return {
    name: `Contact_${item.id}`,
    value: item.id
  }
}}
```

The above function sets the `name` attribute to `Contact_0` (respective to each
item's `id`) for every hidden input that renders, along with each respective
item's `id` set to the `value` attribute.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  itemToInput={(item) => ({ name: "contact", value: item.id })}
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Top direction

Display the dropdown menu above the input by setting `direction` to `"top"`.
This is useful when space below is limited.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  direction="top"
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Hidden label

Hide the label visually while maintaining accessibility by setting `hideLabel`
to `true`. The label is still available to screen readers.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  labelText="Contact"
  label="Select contact methods..."
  hideLabel
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Light variant

Use the light variant for dark backgrounds by setting `light` to `true`. This
provides better contrast in dark themes.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  light
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Portal menu

Set `portalMenu` to `true` to render the dropdown menu in a floating portal.
This prevents the menu from being clipped by parent containers with
`overflow: hidden` or z-index stacking contexts. The example below shows a
container with hidden overflow. Without `portalMenu`, the dropdown would be
clipped.

When inside a [Modal](/components/Modal#modal-with-dropdowns), `portalMenu`
defaults to `true` unless explicitly set to `false`.

```svelte
<script>
  import { MultiSelect, Stack } from "carbon-components-svelte";
</script>

<Stack
  gap={4}
  style="overflow: hidden; border: 1px dashed var(--cds-border-subtle); padding: 1rem; max-height: 120px;"
>
  <div>
    This container has hidden overflow. Without <code>portalMenu</code>, the
    dropdown would be clipped.
  </div>
  <MultiSelect
    portalMenu
    labelText="Notification methods"
    label="Select methods..."
    items={[
      { id: "0", text: "Slack" },
      { id: "1", text: "Email" },
      { id: "2", text: "Fax" },
    ]}
  />
</Stack>
```

### Inline variant

Display the dropdown inline with other content by setting `type` to `"inline"`.
This removes the background and border.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  type="inline"
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Extra-large size

Use the extra-large size for prominent selections by setting `size` to `"xl"`.
This provides more visual emphasis.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  size="xl"
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Small size

Use the small size for compact layouts by setting `size` to `"sm"`. This is
ideal for secondary selections.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  size="sm"
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Invalid state

Indicate an invalid selection by setting `invalid` to `true`. This example shows
a required field error.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  invalid
  invalidText="A contact method is required"
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Warning state

Indicate a warning state by setting `warn` to `true`. This example shows a
warning about unassociated accounts.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  warn
  warnText="One or more contact methods are not associated with your account"
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Disabled state

Disable the entire dropdown by setting `disabled` to `true`. This prevents all
user interaction.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  disabled
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email" },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Disabled items

Disable specific items using the `disabled` property in the `items` prop. This
example disables the Email option.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";
</script>

<MultiSelect
  labelText="Contact"
  label="Select contact methods..."
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email", disabled: true },
    { id: "2", text: "Fax" },
  ]}
/>
```

### Virtualized items (large lists)

Virtualization is a technique that allows only the items currently visible in
the viewport to be rendered in the DOM, improving performance for large lists.

By default, the multi-select will virtualize lists with more than 100 items.

In the example below, 10,000 items are provided to the multi-select but only 11
items (8 visible items + 3 overscan items) are rendered in the DOM.

Set `virtualize={false}` to explicitly disable virtualization, even for large
lists. Or, customize the threshold at which virtualization activates. See
[Virtualized items (custom threshold)](#virtualized-items-custom-threshold).

```svelte
<script>
  import { MultiSelect, Stack } from "carbon-components-svelte";

  const items = Array.from({ length: 10_000 }, (_, i) => ({
    id: i,
    text: `Item ${i + 1}`,
  }));

  let selectedIds = [1000];
  $: selectedItems = items.filter((item) => selectedIds.includes(item.id));
</script>

<Stack gap={5}>
  <MultiSelect
    filterable
    labelText="Virtualized MultiSelect (10,000 items)"
    {items}
    bind:selectedIds
  />
  <div>
    <strong>Selected:</strong>
    {selectedItems.map((item) => item.text).join(", ")}
  </div>
</Stack>
```

### Virtualized items (custom overscan)

Overscanning is the process of rendering extra items above and below the
viewport to ensure smooth scrolling. The default overscan value is 3.

Specify a custom value for `overscan` to control how many extra items are
rendered above/below the viewport for smoother scrolling.

> [!NOTE] During very fast scrolling, higher overscan values may cause more
> flickering due to increased DOM updates. For fast scrolling scenarios, use a
> lower overscan value.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";

  const items = Array.from({ length: 10_000 }, (_, i) => ({
    id: i,
    text: `Item ${i + 1}`,
  }));

  let selectedIds = [1000];
</script>

<MultiSelect
  virtualize={{ overscan: 100 }}
  filterable
  labelText="High overscan (10,000 items, overscan: 100)"
  {items}
  bind:selectedIds
/>
```

### Virtualized items (custom threshold)

The threshold is the minimum number of items required before virtualization
activates. The default threshold value is 100, meaning lists with fewer than 100
items will not be virtualized and all items will be rendered normally.

Specify a custom value for `threshold` to control when virtualization activates.
Below the threshold, all items are rendered normally without virtualization.

```svelte
<script>
  import { MultiSelect } from "carbon-components-svelte";

  const items = Array.from({ length: 100 }, (_, i) => ({
    id: i,
    text: `Item ${i + 1}`,
  }));

  let selectedIds = [50];
</script>

<MultiSelect
  virtualize={{ threshold: 200 }}
  filterable
  labelText="Custom threshold (threshold: 200)"
  {items}
  bind:selectedIds
/>
```

### Virtualized items (custom item height)

The default item height for virtualization is 40 pixels. When using custom slots
to render items with different heights (e.g., multi-line items with
descriptions), specify a custom `itemHeight` value to match your item's actual
height.

```svelte
<script>
  import { MultiSelect, Stack } from "carbon-components-svelte";

  const items = Array.from({ length: 10_000 }, (_, i) => ({
    id: i,
    text: `Item ${i + 1}`,
    description: `Description for item ${i + 1}`,
  }));

  let selectedIds = [1000];
</script>

<MultiSelect
  virtualize={{ itemHeight: 60 }}
  filterable
  labelText="Custom item height (60px)"
  {items}
  bind:selectedIds
  let:item
>
  <Stack gap={2}>
    <strong>{item.text}</strong>
    <span>{item.description}</span>
  </Stack>
</MultiSelect>
```

---

### Component API

#### `MultiSelect` props

| Prop                        | Type                                                                                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Default                             |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `selectedIds` (Reactive)    | `ReadonlyArray<Item["id"]>`                                                                                                           | Set the selected ids.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `[]`                                |
| `value` (Reactive)          | `string`                                                                                                                              | Specify the multiselect value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `""`                                |
| `open` (Reactive)           | `boolean`                                                                                                                             | Set to `true` to open the dropdown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `false`                             |
| `inputRef` (Reactive)       | `null \| HTMLInputElement`                                                                                                            | Obtain a reference to the input HTML element                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `null`                              |
| `multiSelectRef` (Reactive) | `null \| HTMLDivElement`                                                                                                              | Obtain a reference to the outer div element                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `null`                              |
| `fieldRef` (Reactive)       | `null \| HTMLDivElement`                                                                                                              | Obtain a reference to the field box element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `null`                              |
| `selectionRef` (Reactive)   | `null \| HTMLDivElement`                                                                                                              | Obtain a reference to the selection element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `null`                              |
| `highlightedId` (Reactive)  | `null \| Item["id"]`                                                                                                                  | Id of the highlighted ListBoxMenuItem.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `null`                              |
| `listRef` (Reactive)        | `null \| HTMLDivElement`                                                                                                              | Obtain a reference to the list HTML element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `null`                              |
| `items`                     | `ReadonlyArray<Item>`                                                                                                                 | Set the multiselect items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `[]`                                |
| `itemToString`              | `(item: Item) => any`                                                                                                                 | Override the display of a multiselect item.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | _undefined_                         |
| `itemToInput`               | `(item: Item) => { name?: string; labelText?: any; title?: string; value?: string }`                                                  | Override the item name, title, labelText, or value passed to the user-selectable checkbox input as well as the hidden inputs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | _undefined_                         |
| `size`                      | `"sm" \| "lg" \| "xl"`                                                                                                                | Set the size of the combobox.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | _undefined_                         |
| `type`                      | `"default" \| "inline"`                                                                                                               | Specify the type of multiselect.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `"default"`                         |
| `direction`                 | `"bottom" \| "top"`                                                                                                                   | Specify the direction of the multiselect dropdown menu.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `"bottom"`                          |
| `selectionFeedback`         | `"top" \| "fixed" \| "top-after-reopen"`                                                                                              | Specify the selection feedback after selecting items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `"top-after-reopen"`                |
| `disabled`                  | `boolean`                                                                                                                             | Set to `true` to disable the dropdown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `false`                             |
| `filterable`                | `boolean`                                                                                                                             | Set to `true` to filter items                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `false`                             |
| `filterItem`                | `(item: Item, value: string) => boolean`                                                                                              | Override the filtering logic.<br />The default filtering is an exact string comparison.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | _undefined_                         |
| `light`                     | `boolean`                                                                                                                             | Set to `true` to enable the light variant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                             |
| `locale`                    | `string`                                                                                                                              | Specify the locale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `"en"`                              |
| `placeholder`               | `string`                                                                                                                              | Specify the placeholder text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `""`                                |
| `sortItem`                  | `((a: Item, b: Item) => Item) \| (() => void)`                                                                                        | Override the sorting logic.<br />The default sorting compare the item text value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | _undefined_                         |
| `translateWithId`           | `(id: import("../ListBox/ListBoxMenuIcon.svelte").ListBoxMenuIconTranslationId) => string`                                            | Override the chevron icon label based on the open state.<br />Defaults to "Open menu" when closed and "Close menu" when open.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | _undefined_                         |
| `translateWithIdSelection`  | `(id: import("../ListBox/ListBoxSelection.svelte").ListBoxSelectionTranslationId) => string`                                          | Override the label of the clear button when the input has a selection.<br />Defaults to "Clear selected item" and "Clear all items" if more than one item is selected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | _undefined_                         |
| `labelText`                 | `string`                                                                                                                              | Specify the label text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `""`                                |
| `useTitleInItem`            | `boolean`                                                                                                                             | Set to `true` to pass the item to `itemToString` in the checkbox                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `false`                             |
| `invalid`                   | `boolean`                                                                                                                             | Set to `true` to indicate an invalid state                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `false`                             |
| `invalidText`               | `string`                                                                                                                              | Specify the invalid state text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `""`                                |
| `warn`                      | `boolean`                                                                                                                             | Set to `true` to indicate a warning state                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                             |
| `warnText`                  | `string`                                                                                                                              | Specify the warning state text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `""`                                |
| `helperText`                | `string`                                                                                                                              | Specify the helper text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `""`                                |
| `label`                     | `string`                                                                                                                              | Specify the list box label                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `""`                                |
| `hideLabel`                 | `boolean`                                                                                                                             | Set to `true` to visually hide the label text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `false`                             |
| `id`                        | `string`                                                                                                                              | Set an id for the list box component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `ccs-${Math.random().toString(36)}` |
| `name`                      | `string`                                                                                                                              | Specify a name attribute for the select.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | _undefined_                         |
| `virtualize`                | `undefined \| boolean \| { itemHeight?: number, containerHeight?: number, overscan?: number, threshold?: number, maxItems?: number }` | Enable virtualization for large lists. Virtualization renders only the items currently visible in the viewport, improving performance for large lists.<br /><br />By default, virtualization is automatically enabled for lists with more than 100 items.<br /><br />Set `virtualize={false}` to explicitly disable virtualization, even for large lists.<br /><br />Set `virtualize={true}` to explicitly enable virtualization with default settings.<br /><br />Provide an object to customize virtualization behavior:<br />- `itemHeight` (default: 40): The height in pixels of each item. Specify a custom value when using custom slots with multi-line items or different heights.<br />- `containerHeight` (default: 300): The maximum height in pixels of the dropdown container.<br />- `overscan` (default: 3): The number of extra items to render above and below the viewport for smoother scrolling. Higher values may cause more flickering during very fast scrolling.<br />- `threshold` (default: 100): The minimum number of items required before virtualization activates. Lists with fewer items will render all items normally without virtualization.<br />- `maxItems` (default: undefined): The maximum number of items to render. When undefined, all visible items are rendered. | _undefined_                         |
| `portalMenu`                | `boolean \| undefined`                                                                                                                | Set to `true` to render the dropdown menu in a portal,<br />allowing it to escape containers with `overflow: hidden`.<br />When inside a Modal, defaults to `true` unless explicitly set to `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | _undefined_                         |

#### `MultiSelect` typedefs

```ts
type MultiSelectItemText = string;

type MultiSelectItem<Id = any> = {
  id: Id;
  text: MultiSelectItemText;
  /** Whether the item is disabled */
  disabled?: boolean;
};
```

#### `MultiSelect` slots

| Slot            | Detail                                            |
| --------------- | ------------------------------------------------- |
| `default`       | `{<br /> item: Item;<br /> index: number;<br />}` |
| `labelChildren` | `Record<string, never>`                           |

#### `MultiSelect` forwarded events

| Event        |
| ------------ |
| `on:clear`   |
| `on:keydown` |
| `on:input`   |
| `on:keyup`   |
| `on:focus`   |
| `on:paste`   |
| `on:scroll`  |

#### `MultiSelect` dispatched events

| Event       | Detail                                                                                        |
| ----------- | --------------------------------------------------------------------------------------------- |
| `on:select` | `{<br /> selectedIds: Item["id"][];<br /> selected: Item[];<br /> unselected: Item[];<br />}` |
| `on:blur`   | `type EventDetail =<br /> \| FocusEvent<br /> \| CustomEvent<FocusEvent>`                     |

#### `MultiSelect` $$restProps

`MultiSelect` spreads `$$restProps` to the `input` element.


## NotificationQueue

Notification queues provide an imperative API for managing toast notifications.
They handle positioning, deduplication, and overflow management, making it easy
to display notifications from anywhere in your application.

The queue uses the underlying [ToastNotification](ToastNotification) to display
notifications.

### Basic usage

Use `bind:this` to get a reference to the queue instance, then call `add()` to
show notifications. The queue automatically manages positioning and removes
notifications when they timeout or are closed.

```svelte
<script>
  import {
    Button,
    ButtonSet,
    NotificationQueue,
  } from "carbon-components-svelte";

  let queue;
</script>

<NotificationQueue bind:this={queue} />

<ButtonSet>
  <Button
    on:click={() => {
      queue.add({
        kind: "success",
        title: "Success",
        subtitle: "Your changes have been saved.",
        timeout: 3000,
      });
    }}
  >
    Show success
  </Button>
  <Button
    kind="tertiary"
    on:click={() => {
      queue.add({
        kind: "error",
        title: "Error",
        subtitle: "An error occurred while processing your request.",
        timeout: 3000,
      });
    }}
  >
    Show error
  </Button>
  <Button
    kind="tertiary"
    on:click={() => {
      queue.add({
        kind: "info",
        title: "Information",
        subtitle: "New updates are available.",
        timeout: 3000,
      });
    }}
  >
    Show info
  </Button>
  <Button
    kind="tertiary"
    on:click={() => {
      queue.add({
        kind: "warning",
        title: "Warning",
        subtitle: "This is a warning notification.",
        timeout: 3000,
      });
    }}
  >
    Show warning
  </Button>
</ButtonSet>
```

### Positioning

Configure the queue position using the position prop. Notifications can appear
at the top-right (default) or bottom-right of the screen.

The `top-right` position assumes usage of the [UIShell](/components/UIShell)
component. Customize the position using [offset props](#custom-offsets).

```svelte
<script>
  import {
    Button,
    ButtonSet,
    NotificationQueue,
  } from "carbon-components-svelte";

  let topQueue;
  let bottomQueue;
</script>

<NotificationQueue bind:this={topQueue} position="top-right" />
<NotificationQueue bind:this={bottomQueue} position="bottom-right" />

<ButtonSet>
  <Button
    on:click={() => {
      topQueue.add({
        kind: "success",
        title: "Top right",
      });
    }}
  >
    Add top right
  </Button>
  <Button
    on:click={() => {
      bottomQueue.add({
        kind: "info",
        title: "Bottom right",
      });
    }}
  >
    Add bottom right
  </Button>
</ButtonSet>
```

### Deduplication

By default, the `id` prop is optional; a unique id will be generated for the
notification. The queue
[keys](https://svelte.dev/docs/svelte/each#Keyed-each-blocks) notifications by
`id` for performance reasons.

Notifications are deduplicated by `id`. If you add a notification with an `id`
that already exists in the queue, the call is ignored. This prevents duplicate
notifications from appearing.

```svelte
<script>
  import {
    Button,
    ButtonSet,
    NotificationQueue,
  } from "carbon-components-svelte";

  let queue;
  let count = 0;
</script>

<NotificationQueue bind:this={queue} />

<ButtonSet>
  <Button
    on:click={() => {
      queue.add({
        id: "id",
        kind: "warning",
        title: "Duplicate notification",
        subtitle:
          "This notification has the same id. Click the button multiple times.",
      });
    }}
  >
    Add duplicate
  </Button>
  <Button
    on:click={() => {
      queue.add({
        id: "id-" + count++,
        kind: "info",
        title: "Unique notification",
        subtitle: "This has a unique id, so it will always appear.",
      });
    }}
  >
    Add unique
  </Button>
</ButtonSet>
```

### Max notifications

By default, the queue displays a maximum of 3 notifications. When the limit is
exceeded, the oldest notification is automatically removed.

This limit can be customized using the `maxNotifications` prop.

```svelte
<script>
  import { Button, NotificationQueue } from "carbon-components-svelte";

  let queue;
  let count = 0;
</script>

<NotificationQueue bind:this={queue} maxNotifications={3} />

<Button
  on:click={() => {
    count++;
    queue.add({
      kind: "success",
      title: "Notification " + count,
    });
  }}
>
  Add notification
</Button>
```

### Remove and clear

Use `remove(id)` to programmatically remove a specific notification, or
`clear()` to remove all notifications at once.

```svelte
<script>
  import {
    Button,
    ButtonSet,
    NotificationQueue,
  } from "carbon-components-svelte";

  let queue;
  let notificationIds = [];
</script>

<NotificationQueue bind:this={queue} />

<ButtonSet>
  <Button
    on:click={() => {
      const id = queue.add({
        kind: "info",
        title: "Removable notification",
        subtitle: "This notification can be removed programmatically.",
        timeout: 0,
      });
      notificationIds = [...notificationIds, id];
    }}
  >
    Add notification
  </Button>
  <Button
    on:click={() => {
      if (notificationIds.length > 0) {
        const id = notificationIds[notificationIds.length - 1];
        queue.remove(id);
        notificationIds = notificationIds.slice(0, -1);
      }
    }}
  >
    Remove last
  </Button>
  <Button
    on:click={() => {
      queue.clear();
      notificationIds = [];
    }}
  >
    Clear all
  </Button>
</ButtonSet>
```

### Custom offsets

Customize the queue position using `offsetTop`, `offsetBottom`, and
`offsetRight` props. This is useful for positioning notifications below headers
or adjusting spacing.

```svelte
<script>
  import { Button, NotificationQueue } from "carbon-components-svelte";

  let queue;
</script>

<NotificationQueue
  bind:this={queue}
  position="top-right"
  offsetTop="5rem"
  offsetRight="2rem"
/>

<Button
  on:click={() => {
    queue.add({
      kind: "success",
      title: "Custom offset",
    });
  }}
>
  Add notification
</Button>
```

### Persistent notifications

Create persistent notifications that do not auto-dismiss by omitting the
`timeout` prop and hiding the close button using `hideCloseButton`.

These notifications remain visible until they are programmatically removed.

```svelte
<script>
  import {
    Button,
    ButtonSet,
    NotificationQueue,
  } from "carbon-components-svelte";

  let queue;
</script>

<NotificationQueue bind:this={queue} />

<ButtonSet>
  <Button
    on:click={() => {
      queue.add({
        kind: "warning",
        title: "Persistent notification",
        subtitle:
          "This notification has no close button and will not auto-dismiss.",
        hideCloseButton: true,
      });
    }}
  >
    Add persistent
  </Button>
  <Button
    on:click={() => {
      queue.add({
        kind: "info",
        title: "Auto-dismiss notification",
        subtitle:
          "This notification has no close button but will auto-dismiss after 3 seconds.",
        hideCloseButton: true,
        timeout: 3000,
      });
    }}
  >
    Add auto-dismiss
  </Button>
  <Button
    on:click={() => {
      queue.clear();
    }}
  >
    Clear all
  </Button>
</ButtonSet>
```

---

### Component API

#### `NotificationQueue` props

| Prop               | Type                                         | Description                                                                                                                                                                         | Default       |
| ------------------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `position`         | `"top-right" \| "bottom-right"`              | Specify the position of the notification queue.                                                                                                                                     | `"top-right"` |
| `offsetTop`        | `string`                                     | Specify the top offset (CSS value)                                                                                                                                                  | `"3rem"`      |
| `offsetBottom`     | `string`                                     | Specify the bottom offset (CSS value)                                                                                                                                               | `"1rem"`      |
| `offsetRight`      | `string`                                     | Specify the right offset (CSS value)                                                                                                                                                | `"1rem"`      |
| `zIndex`           | `number`                                     | Specify the z-index of the notification queue.<br />By default, this matches the z-index of modals.                                                                                 | `9000`        |
| `maxNotifications` | `number`                                     | Specify the maximum number of notifications to display.<br />When this limit is exceeded, the oldest notification is automatically removed.                                         | `3`           |
| `add`              | `(notification: NotificationData) => string` | Add a notification to the queue.<br />If a notification with the same id exists, the call is ignored.<br />Returns the notification id (either the provided id or a generated one). | _undefined_   |
| `remove`           | `(id: string) => boolean`                    | Remove a notification by id.<br />Returns true if the notification was found and removed, false otherwise.                                                                          | _undefined_   |
| `clear`            | `() => any`                                  | Clear all notifications.                                                                                                                                                            | _undefined_   |

#### `NotificationQueue` typedefs

```ts
type NotificationData = {
  /** Optional id for deduplication */
  id?: string;
  kind?:
    | "error"
    | "info"
    | "info-square"
    | "success"
    | "warning"
    | "warning-alt";
  title?: string;
  subtitle?: string;
  caption?: string;
  timeout?: number;
  lowContrast?: boolean;
  closeButtonDescription?: string;
  statusIconDescription?: string;
  hideCloseButton?: boolean;
};
```


## NumberInput

Number inputs provide a controlled input for numerical values. They support
validation, step values, and various states to ensure accurate data entry.

### Default

Create a basic number input with increment and decrement controls. The input
accepts numerical values and provides visual feedback.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput labelText="Clusters" value={0} />
```

### No value

Allow empty values by setting both `allowEmpty` to `true` and `value` to `null`.
The `allowEmpty` prop enables the empty state, while `value={null}` represents
no value.

```svelte
<script>
  import { Button, NumberInput } from "carbon-components-svelte";

  let value = null;
</script>

<NumberInput allowEmpty bind:value />

<div style="margin: var(--cds-layout-01) 0">
  <Button on:click={() => (value = null)}>Set to null</Button>
  <Button on:click={() => (value = 0)}>Set to 0</Button>
</div>

<strong>Value:</strong>
{value}
```

### Helper text

Add descriptive text below the input using the `helperText` prop. This helps
users understand the expected input.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput
  labelText="Clusters"
  value={0}
  helperText="Clusters provisioned in your region"
/>
```

### Minimum and maximum values

Constrain input values using `min` and `max` props. When the value falls outside
the specified range, the input automatically shows an invalid visual state.
Provide `invalidText` to display an error message.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput
  min={4}
  max={20}
  value={4}
  invalidText="Number must be between 4 and 20."
  helperText="Clusters provisioned in your region"
  labelText="Clusters (4 min, 20 max)"
/>
```

### Step value

Control the increment/decrement step size using the `step` prop. This example
uses a step of 0.1.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput
  value={1}
  helperText="Step of 0.1"
  step={0.1}
  labelText="Clusters"
/>
```

### Step start value

Configure a starting point for stepping when the input is empty or zero using
`stepStartValue`. When the user clicks increment or decrement, the value jumps
directly to `stepStartValue` instead of stepping from zero.

This is useful when zero is not within the `min`/`max` range, or when there is a
more sensible default (e.g., the current year when asking for a year). Combined
with `allowEmpty`, it ensures the user must interact with the input before
submitting a value.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput
  stepStartValue={2026}
  allowEmpty
  min={2026}
  max={2100}
  labelText="Year"
/>
```

### Preserve decimal input

Preserve decimal input formatting like "1.0", "2.00", or "3." by setting
`allowDecimal` to `true`. This uses `type="text"` with `inputmode="decimal"`
instead of `type="number"`, allowing trailing zeros and decimal points to be
preserved while typing. This is useful for financial data or precise decimal
entry.

```svelte
<script>
  import {
    Button,
    ButtonSet,
    NumberInput,
    Stack,
  } from "carbon-components-svelte";

  let value = 1.5;
</script>

<Stack gap={4}>
  <NumberInput
    allowDecimal
    allowEmpty
    bind:value
    step={0.01}
    labelText="Amount"
  />

  <ButtonSet>
    <Button on:click={() => (value = null)}>Set to null</Button>
    <Button on:click={() => (value = 0)}>Set to 0</Button>
    <Button on:click={() => (value = 1.23)}>Set to 1.23</Button>
  </ButtonSet>

  <div>
    <strong>Value:</strong>
    {value}
  </div>
</Stack>
```

### Locale formatting

Format numbers according to a locale using the `locale` prop with a BCP 47
language tag. The display value is formatted on blur using `Intl.NumberFormat`.
When `locale` is set, the input uses `type="text"` with `inputmode="decimal"`.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput locale="de-DE" value={1234.5} labelText="Amount (German)" />
```

### Locale with format options

Combine `locale` with `formatOptions` for additional formatting control like
decimal precision.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput
  locale="en-US"
  formatOptions={{ minimumFractionDigits: 2, maximumFractionDigits: 2 }}
  value={1234.5}
  labelText="Price"
/>
```

### Custom validation

Use the `validate` prop to provide custom validation logic. The function
receives the raw input string and optional locale. Return `false` to mark
invalid, `true` to force valid (overriding auto bounds checks), or `undefined`
to use built-in validation.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput
  validate={(raw) => {
    const num = Number(raw);
    return Number.isNaN(num) ? undefined : num % 2 === 0;
  }}
  invalidText="Must be an even number"
  labelText="Even number"
  value={0}
/>

## Blur event Use `on:blur` to listen for when the input loses focus. The event
detail includes the current parsed `value` and the original `FocusEvent`.

<NumberInput
  on:blur={(e) => {
    console.log(e.detail.value); // number | null
    console.log(e.detail.event); // FocusEvent
  }}
/>

## Stepper click event Use `on:click:stepper` to listen for stepper button
clicks. The event detail includes the updated `value` and the `direction`
(`"up"` or `"down"`). This event only fires on button clicks, not arrow key
presses.

<NumberInput
  on:click:stepper={(e) => {
    console.log(e.detail.value); // number
    console.log(e.detail.direction); // "up" | "down"
  }}
/>

## Stepper blur event Use `on:blur:stepper` to listen for when a stepper button
loses focus. The event detail includes the current `value`, the `direction`, and
the original `FocusEvent`.

<NumberInput
  on:blur:stepper={(e) => {
    console.log(e.detail.value); // number | null
    console.log(e.detail.direction); // "up" | "down"
    console.log(e.detail.event); // FocusEvent
  }}
/>
```

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";

  let value = 0;
  let clickStepperEvents = [];
  let blurEvents = [];
  let blurStepperEvents = [];
</script>

<NumberInput
  bind:value
  labelText="Clusters"
  on:click:stepper={(e) => {
    clickStepperEvents = [
      ...clickStepperEvents,
      "value: " + e.detail.value + ", direction: " + e.detail.direction,
    ];
  }}
  on:blur={(e) => {
    blurEvents = [...blurEvents, "value: " + e.detail.value];
  }}
  on:blur:stepper={(e) => {
    blurStepperEvents = [
      ...blurStepperEvents,
      "value: " + e.detail.value + ", direction: " + e.detail.direction,
    ];
  }}
/>

<div style="margin-top: var(--cds-layout-01)">
  <strong>click:stepper events:</strong>
  <pre>{clickStepperEvents.join("\n") || "(none)"}</pre>
</div>

<div style="margin-top: var(--cds-layout-01)">
  <strong>blur events:</strong>
  <pre>{blurEvents.join("\n") || "(none)"}</pre>
</div>

<div style="margin-top: var(--cds-layout-01)">
  <strong>blur:stepper events:</strong>
  <pre>{blurStepperEvents.join("\n") || "(none)"}</pre>
</div>
```

### Hidden label

Hide the label visually while maintaining accessibility by setting `hideLabel`
to `true`. The label is still available to screen readers.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput hideLabel labelText="Clusters" value={0} />
```

### Extra-large size

Use the extra-large size for prominent inputs by setting `size` to `"xl"`. This
provides more visual emphasis.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput size="xl" labelText="Clusters" value={0} />
```

### Small size

Use the small size for compact layouts by setting `size` to `"sm"`. This is
ideal for secondary inputs.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput size="sm" labelText="Clusters" value={0} />
```

### Light variant

Use the light variant for dark backgrounds by setting `light` to `true`. This
provides better contrast in dark themes.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput light labelText="Clusters" value={0} />
```

### Invalid state

Indicate an invalid value by setting `invalid` to `true`. This example shows a
validation error.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput
  invalid
  invalidText="Invalid value"
  labelText="Clusters"
  value={0}
/>
```

### Warning state

Indicate a warning state by setting `warn` to `true`. This example shows a
warning about the input value.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput
  warn
  warnText="A high number may impact initial rollout"
  labelText="Clusters"
  value={25}
/>
```

### Disabled state

Disable the input by setting `disabled` to `true`. This prevents all user
interaction.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput disabled labelText="Clusters" value={0} />
```

### Read-only state

Make the input read-only by setting `readonly` to `true`. This allows viewing
but prevents editing.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput readonly labelText="Clusters" value={0} />
```

### Hidden steppers

Hide the increment/decrement controls by setting `hideSteppers` to `true`. This
provides a simpler input interface.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput hideSteppers labelText="Clusters" value={0} />
```

### Disable wheel

Prevent the scroll wheel from changing the input value by setting `disableWheel`
to `true`. This is useful in forms where accidental scroll changes are
undesirable.

```svelte
<script>
  import { NumberInput } from "carbon-components-svelte";
</script>

<NumberInput disableWheel labelText="Clusters" value={0} />
```

### Skeleton

Show a loading state using the number input skeleton. This is useful while data
is being fetched.

```svelte
<script>
  import { NumberInputSkeleton } from "carbon-components-svelte";
</script>

<NumberInputSkeleton />
```

### Skeleton without label

Show a loading state without a label by setting `hideLabel` to `true`. This
maintains layout consistency.

```svelte
<script>
  import { NumberInputSkeleton } from "carbon-components-svelte";
</script>

<NumberInputSkeleton hideLabel />
```

---

### Component API

#### `NumberInput` props

| Prop               | Type                                                                   | Description                                                                                                                                                                                          | Default                                                                |
| ------------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `value` (Reactive) | `null \| number`                                                       | Specify the input value.<br />Use `null` to denote "no value".                                                                                                                                       | `null`                                                                 |
| `ref` (Reactive)   | `null \| HTMLInputElement`                                             | Obtain a reference to the input HTML element                                                                                                                                                         | `null`                                                                 |
| `size`             | `"sm" \| "xl"`                                                         | Set the size of the input.                                                                                                                                                                           | _undefined_                                                            |
| `step`             | `number`                                                               | Specify the step increment                                                                                                                                                                           | `1`                                                                    |
| `max`              | `number`                                                               | Specify the maximum value.                                                                                                                                                                           | _undefined_                                                            |
| `min`              | `number`                                                               | Specify the minimum value.                                                                                                                                                                           | _undefined_                                                            |
| `stepStartValue`   | `number`                                                               | Provide the value stepping should begin at when the input is empty.                                                                                                                                  | _undefined_                                                            |
| `light`            | `boolean`                                                              | Set to `true` to enable the light variant                                                                                                                                                            | `false`                                                                |
| `readonly`         | `boolean`                                                              | Set to `true` for the input to be read-only                                                                                                                                                          | `false`                                                                |
| `allowEmpty`       | `boolean`                                                              | Set to `true` to allow for an empty value                                                                                                                                                            | `false`                                                                |
| `allowDecimal`     | `boolean`                                                              | Set to `true` to preserve decimal input formatting.<br />When enabled, uses type="text" with inputmode="decimal" instead of type="number".                                                           | `false`                                                                |
| `locale`           | `string`                                                               | Specify a BCP 47 locale for number formatting.<br />When set, forces type="text" with inputmode="decimal"<br />and formats the display value using Intl.NumberFormat.                                | _undefined_                                                            |
| `formatOptions`    | `Intl.NumberFormatOptions`                                             | Specify Intl.NumberFormat options when `locale` is set.                                                                                                                                              | _undefined_                                                            |
| `disabled`         | `boolean`                                                              | Set to `true` to disable the input                                                                                                                                                                   | `false`                                                                |
| `hideSteppers`     | `boolean`                                                              | Set to `true` to hide the input stepper buttons                                                                                                                                                      | `false`                                                                |
| `disableWheel`     | `boolean`                                                              | Set to `true` to prevent the scroll wheel from changing the input value                                                                                                                              | `false`                                                                |
| `validate`         | `(value: string, locale: string \| undefined) => boolean \| undefined` | Custom validation function.<br />Receives the current raw input string and locale.<br />Return `true` to force valid, `false` to force invalid,<br />or `undefined` to defer to built-in validation. | _undefined_                                                            |
| `invalid`          | `boolean`                                                              | Set to `true` to indicate an invalid state                                                                                                                                                           | `false`                                                                |
| `invalidText`      | `string`                                                               | Specify the invalid state text                                                                                                                                                                       | `""`                                                                   |
| `warn`             | `boolean`                                                              | Set to `true` to indicate a warning state                                                                                                                                                            | `false`                                                                |
| `warnText`         | `string`                                                               | Specify the warning state text                                                                                                                                                                       | `""`                                                                   |
| `helperText`       | `string`                                                               | Specify the helper text                                                                                                                                                                              | `""`                                                                   |
| `labelText`        | `string`                                                               | Specify the label text                                                                                                                                                                               | `""`                                                                   |
| `hideLabel`        | `boolean`                                                              | Set to `true` to visually hide the label text                                                                                                                                                        | `false`                                                                |
| `translateWithId`  | `(id: NumberInputTranslationId) => string`                             | Override the default translation ids.                                                                                                                                                                | _undefined_                                                            |
| `translationIds`   | `{ increment: "increment"; decrement: "decrement" }`                   | Default translation ids.                                                                                                                                                                             | `{<br /> increment: "increment",<br /> decrement: "decrement",<br />}` |
| `id`               | `string`                                                               | Set an id for the input element                                                                                                                                                                      | `ccs-${Math.random().toString(36)}`                                    |
| `name`             | `string`                                                               | Specify a name attribute for the input.                                                                                                                                                              | _undefined_                                                            |

#### `NumberInput` typedefs

```ts
type NumberInputTranslationId = "increment" | "decrement";
```

#### `NumberInput` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `labelChildren` | `Record<string, never>` |

#### `NumberInput` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:keydown`    |
| `on:keyup`      |
| `on:focus`      |
| `on:paste`      |

#### `NumberInput` dispatched events

| Event              | Detail                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| `on:change`        | `null \| number`                                                                                  |
| `on:input`         | `null \| number`                                                                                  |
| `on:click:stepper` | `{<br /> value: null \| number;<br /> direction: "up" \| "down";<br />}`                          |
| `on:blur`          | `{<br /> event: FocusEvent;<br /> value: null \| number;<br />}`                                  |
| `on:blur:stepper`  | `{<br /> event: FocusEvent;<br /> value: null \| number;<br /> direction: "up" \| "down";<br />}` |

#### `NumberInput` $$restProps

`NumberInput` spreads `$$restProps` to the `input` element.

#### `NumberInputSkeleton` props

| Prop        | Type      | Description                          | Default |
| ----------- | --------- | ------------------------------------ | ------- |
| `hideLabel` | `boolean` | Set to `true` to hide the label text | `false` |

#### `NumberInputSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `NumberInputSkeleton` $$restProps

`NumberInputSkeleton` spreads `$$restProps` to the `div` element.


## OrderedList

Ordered lists provide a structured way to display numbered lists of items. They
support nested lists, native browser styles, and expressive typography for
enhanced visual hierarchy.

> [!TIP] Consider using the [RecursiveList](/components/RecursiveList#ordered)
> component for rendering tree structured data.

### Default

Create a basic ordered list by wrapping list item components within the ordered
list.

```svelte
<script>
  import { ListItem, OrderedList } from "carbon-components-svelte";
</script>

<OrderedList>
  <ListItem>Ordered list item</ListItem>
  <ListItem>Ordered list item</ListItem>
  <ListItem>Ordered list item</ListItem>
</OrderedList>
```

### With links

Add interactive elements like link components within list items.

```svelte
<script>
  import { Link, ListItem, OrderedList } from "carbon-components-svelte";
</script>

<OrderedList>
  <ListItem>
    <Link href="#">Ordered list item</Link>
  </ListItem>
  <ListItem>
    <Link href="#">Ordered list item</Link>
  </ListItem>
  <ListItem>
    <Link href="#">Ordered list item</Link>
  </ListItem>
</OrderedList>
```

### Nested

Set the `nested` prop to `true` to create hierarchical lists with proper
indentation and numbering.

```svelte
<script>
  import { ListItem, OrderedList } from "carbon-components-svelte";
</script>

<OrderedList>
  <ListItem>
    Ordered list level 1
    <OrderedList nested>
      <ListItem>Ordered list level 2</ListItem>
      <ListItem>
        Ordered list level 3
        <OrderedList nested>
          <ListItem>Ordered list level 3</ListItem>
          <ListItem>Ordered list level 3</ListItem>
        </OrderedList>
      </ListItem>
    </OrderedList>
  </ListItem>
  <ListItem>Ordered list level 1</ListItem>
  <ListItem>Ordered list level 1</ListItem>
</OrderedList>
```

### Native list styles

Enable native browser list styles by setting the `native` prop to `true`. This
is useful for large lists where the list number may overlap with the list item
text.

```svelte
<script>
  import { ListItem, OrderedList } from "carbon-components-svelte";
</script>

<OrderedList native>
  <ListItem>
    Ordered list level 1
    <OrderedList nested>
      <ListItem>Ordered list level 2</ListItem>
      <ListItem>
        Ordered list level 3
        <OrderedList nested>
          <ListItem>Ordered list level 3</ListItem>
          <ListItem>Ordered list level 3</ListItem>
        </OrderedList>
      </ListItem>
    </OrderedList>
  </ListItem>
  <ListItem>Ordered list level 1</ListItem>
  <ListItem>Ordered list level 1</ListItem>
</OrderedList>
```

### Expressive styles

Use Carbon's expressive typesetting by setting the `expressive` prop to `true`.

```svelte
<script>
  import { Link, ListItem, OrderedList } from "carbon-components-svelte";
</script>

<OrderedList expressive>
  <ListItem><Link size="lg" href="#">Ordered list item</Link></ListItem>
  <ListItem>Ordered list item</ListItem>
  <ListItem>Ordered list item</ListItem>
</OrderedList>
```

---

### Component API

#### `OrderedList` props

| Prop         | Type      | Description                                          | Default |
| ------------ | --------- | ---------------------------------------------------- | ------- |
| `nested`     | `boolean` | Set to `true` to use the nested variant              | `false` |
| `native`     | `boolean` | Set to `true` to use native list styles              | `false` |
| `expressive` | `boolean` | Set to `true` to use Carbon's expressive typesetting | `false` |

#### `OrderedList` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `OrderedList` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `OrderedList` $$restProps

`OrderedList` spreads `$$restProps` to the `ol` element.

#### `ListItem` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ListItem` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `ListItem` $$restProps

`ListItem` spreads `$$restProps` to the `li` element.


## OverflowMenu

Overflow menus provide a compact way to display a list of actions or options.
They render as a button that opens a dropdown menu when clicked, making them
ideal for secondary actions or overflow content.

### Default

Create a basic overflow menu by wrapping overflow menu item components within
the overflow menu.

```svelte
<script>
  import { OverflowMenu, OverflowMenuItem } from "carbon-components-svelte";
</script>

<OverflowMenu>
  <OverflowMenuItem text="Manage credentials" />
  <OverflowMenuItem
    href="https://cloud.ibm.com/docs/api-gateway/"
    target="_blank"
    text="API documentation"
  />
  <OverflowMenuItem danger text="Delete service" />
</OverflowMenu>
```

### Portal menu

Set `portalMenu` to `true` to render the menu in a floating portal. This
prevents the menu from being clipped by parent containers with
`overflow: hidden` or z-index stacking contexts. The example below shows a
container with hidden overflow. Without `portalMenu`, the menu would be clipped.

When inside a [Modal](/components/Modal), `portalMenu` defaults to `true` unless
explicitly set to `false`.

```svelte
<script>
  import {
    OverflowMenu,
    OverflowMenuItem,
    Stack,
  } from "carbon-components-svelte";
</script>

<Stack
  gap={4}
  style="overflow: hidden; border: 1px dashed var(--cds-border-subtle); padding: 1rem; max-height: 120px;"
>
  <div>
    This container has hidden overflow. Without <code>portalMenu</code>, the
    menu would be clipped.
  </div>
  <OverflowMenu portalMenu>
    <OverflowMenuItem text="Edit" />
    <OverflowMenuItem text="Duplicate" />
    <OverflowMenuItem danger text="Delete" />
  </OverflowMenu>
</Stack>
```

### Flipped

Set `flipped` to `true` to position the menu to the left of the button.

```svelte
<script>
  import { OverflowMenu, OverflowMenuItem } from "carbon-components-svelte";
</script>

<OverflowMenu flipped>
  <OverflowMenuItem text="Manage credentials" />
  <OverflowMenuItem
    href="https://cloud.ibm.com/docs/api-gateway/"
    target="_blank"
    text="API documentation"
  />
  <OverflowMenuItem danger text="Delete service" />
</OverflowMenu>
```

### Menu direction

Set `direction` to `"top"` to position the menu above the button.

```svelte
<script>
  import { OverflowMenu, OverflowMenuItem } from "carbon-components-svelte";
</script>

<OverflowMenu flipped direction="top">
  <OverflowMenuItem text="Manage credentials" />
  <OverflowMenuItem
    href="https://cloud.ibm.com/docs/api-gateway/"
    target="_blank"
    text="API documentation"
  />
  <OverflowMenuItem danger text="Delete service" />
</OverflowMenu>
```

### Light variant

Enable the light variant by setting `light` to `true`.

```svelte
<script>
  import { OverflowMenu, OverflowMenuItem } from "carbon-components-svelte";
</script>

<OverflowMenu light>
  <OverflowMenuItem text="Manage credentials" />
  <OverflowMenuItem
    href="https://cloud.ibm.com/docs/api-gateway/"
    target="_blank"
    text="API documentation"
  />
  <OverflowMenuItem danger text="Delete service" />
</OverflowMenu>
```

### Extra-large size

Set `size` to `"xl"` for an extra-large overflow menu.

```svelte
<script>
  import { OverflowMenu, OverflowMenuItem } from "carbon-components-svelte";
</script>

<OverflowMenu size="xl">
  <OverflowMenuItem text="Manage credentials" />
  <OverflowMenuItem
    href="https://cloud.ibm.com/docs/api-gateway/"
    target="_blank"
    text="API documentation"
  />
  <OverflowMenuItem danger text="Delete service" />
</OverflowMenu>
```

### Small size

Set `size` to `"sm"` for a small overflow menu.

```svelte
<script>
  import { OverflowMenu, OverflowMenuItem } from "carbon-components-svelte";
</script>

<OverflowMenu size="sm">
  <OverflowMenuItem text="Manage credentials" />
  <OverflowMenuItem
    href="https://cloud.ibm.com/docs/api-gateway/"
    target="_blank"
    text="API documentation"
  />
  <OverflowMenuItem danger text="Delete service" />
</OverflowMenu>
```

### Custom primary focus

Set `primaryFocus` to `true` on a menu item to focus it when opening the
dropdown.

```svelte
<script>
  import { OverflowMenu, OverflowMenuItem } from "carbon-components-svelte";
</script>

<OverflowMenu>
  <OverflowMenuItem text="Manage credentials" />
  <OverflowMenuItem
    href="https://cloud.ibm.com/docs/api-gateway/"
    target="_blank"
    text="API documentation"
  />
  <OverflowMenuItem primaryFocus danger text="Delete service" />
</OverflowMenu>
```

### Custom trigger icon

Replace the default vertical overflow menu icon with a custom icon.

```svelte
<script>
  import { OverflowMenu, OverflowMenuItem } from "carbon-components-svelte";
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<OverflowMenu icon={Add}>
  <OverflowMenuItem text="Manage credentials" />
  <OverflowMenuItem
    href="https://cloud.ibm.com/docs/api-gateway/"
    target="_blank"
    text="API documentation"
  />
  <OverflowMenuItem danger text="Delete service" />
</OverflowMenu>
```

### Custom trigger slot

Use the `menu` slot to customize the trigger button content.

```svelte
<script>
  import { OverflowMenu, OverflowMenuItem } from "carbon-components-svelte";
</script>

<OverflowMenu style="width: auto;">
  <div slot="menu" style="padding: 1rem; color: red;">Custom trigger</div>
  <OverflowMenuItem text="Manage credentials" />
  <OverflowMenuItem
    href="https://cloud.ibm.com/docs/api-gateway/"
    target="_blank"
    text="API documentation"
  />
  <OverflowMenuItem danger text="Delete service" />
</OverflowMenu>
```

### Disabled items

Set `disabled` to `true` to disable menu items. Use `hasDivider` to add visual
separation between items.

```svelte
<script>
  import { OverflowMenu, OverflowMenuItem } from "carbon-components-svelte";
</script>

<OverflowMenu>
  <OverflowMenuItem text="Create key" />
  <OverflowMenuItem text="Import key" />
  <OverflowMenuItem text="Revoke key" disabled />
  <OverflowMenuItem text="Duplicate key" disabled />
  <OverflowMenuItem
    hasDivider
    href="https://cloud.ibm.com/docs/api-gateway/"
    target="_blank"
    text="API documentation"
  />
  <OverflowMenuItem hasDivider danger text="Delete service" />
</OverflowMenu>
```

### Prevent menu from closing

Use `preventDefault()` on individual overflow menu item click events to prevent
the menu from closing when that item is clicked. This is useful for scenarios
where you want to keep the menu open after performing an action.

```svelte
<script>
  import { OverflowMenu, OverflowMenuItem } from "carbon-components-svelte";

  let copying = false;
  let copied = false;

  async function copyToClipboard() {
    if (copying) return;
    copying = true;
    copied = false;
    await navigator.clipboard.writeText("Sample text to copy");
    copied = true;
    setTimeout(() => {
      copied = false;
    }, 2000);

    copying = false;
  }
</script>

<OverflowMenu size="field">
  <OverflowMenuItem
    text={copied ? "Copied!" : "Copy page"}
    disabled={copying}
    on:click={(e) => {
      // Prevent menu from closing for this item.
      e.preventDefault();
      copyToClipboard();
    }}
  />
  <OverflowMenuItem text="Close menu" />
</OverflowMenu>
```

---

### Component API

#### `OverflowMenu` props

| Prop                   | Type                        | Description                                                                                                                                                                                 | Default                             |
| ---------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `open` (Reactive)      | `boolean`                   | Set to `true` to open the menu                                                                                                                                                              | `false`                             |
| `icon` (Reactive)      | `any`                       | Specify the icon to render.                                                                                                                                                                 | `OverflowMenuVertical`              |
| `buttonRef` (Reactive) | `null \| HTMLButtonElement` | Obtain a reference to the trigger button element                                                                                                                                            | `null`                              |
| `menuRef` (Reactive)   | `null \| HTMLUListElement`  | Obtain a reference to the overflow menu element                                                                                                                                             | `null`                              |
| `size`                 | `"sm" \| "xl"`              | Specify the size of the overflow menu.                                                                                                                                                      | _undefined_                         |
| `direction`            | `"top" \| "bottom"`         | Specify the direction of the overflow menu relative to the button.                                                                                                                          | `"bottom"`                          |
| `light`                | `boolean`                   | Set to `true` to enable the light variant                                                                                                                                                   | `false`                             |
| `flipped`              | `boolean`                   | Set to `true` to flip the menu relative to the button                                                                                                                                       | `false`                             |
| `menuOptionsClass`     | `string`                    | Specify the menu options class.                                                                                                                                                             | _undefined_                         |
| `iconClass`            | `string`                    | Specify the icon class.                                                                                                                                                                     | _undefined_                         |
| `iconDescription`      | `string`                    | Specify the ARIA label for the icon                                                                                                                                                         | `"Open and close list of options"`  |
| `id`                   | `string`                    | Set an id for the button element                                                                                                                                                            | `ccs-${Math.random().toString(36)}` |
| `portalMenu`           | `boolean \| undefined`      | Set to `true` to render the menu in a portal,<br />allowing it to escape containers with `overflow: hidden`.<br />When inside a Modal, defaults to `true` unless explicitly set to `false`. | _undefined_                         |

#### `OverflowMenu` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |
| `menu`    | `Record<string, never>` |

#### `OverflowMenu` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:keydown`    |

#### `OverflowMenu` dispatched events

| Event      | Detail                                                |
| ---------- | ----------------------------------------------------- |
| `on:close` | `{<br /> index?: number;<br /> text?: string;<br />}` |

#### `OverflowMenu` $$restProps

`OverflowMenu` spreads `$$restProps` to the `button` element.

#### `OverflowMenuItem` props

| Prop                      | Type                                             | Description                                                                                                                                             | Default                             |
| ------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `primaryFocus` (Reactive) | `boolean`                                        | Set to `true` if the item should be focused when opening the menu                                                                                       | `false`                             |
| `ref` (Reactive)          | `null \| HTMLAnchorElement \| HTMLButtonElement` | Obtain a reference to the HTML element                                                                                                                  | `null`                              |
| `text`                    | `string`                                         | Specify the item text.<br />Alternatively, use the default slot.                                                                                        | `"Provide text"`                    |
| `href`                    | `string`                                         | Specify the `href` attribute if the item is a link                                                                                                      | `""`                                |
| `target`                  | `HTMLAnchorElement["target"]`                    | Specify the `target` attribute if the item is a link                                                                                                    | `""`                                |
| `rel`                     | `HTMLAnchorElement["rel"]`                       | Specify the `rel` attribute if the item is a link.<br />By default, `noopener noreferrer` is added if<br />`target="_blank"` unless `rel` is specified. | _undefined_                         |
| `disabled`                | `boolean`                                        | Set to `true` to disable the item                                                                                                                       | `false`                             |
| `hasDivider`              | `boolean`                                        | Set to `true` to include a divider                                                                                                                      | `false`                             |
| `danger`                  | `boolean`                                        | Set to `true` to use the danger variant                                                                                                                 | `false`                             |
| `requireTitle`            | `boolean`                                        | Set to `false` to omit the button `title` attribute                                                                                                     | `true`                              |
| `id`                      | `string`                                         | Set an id for the top-level element                                                                                                                     | `ccs-${Math.random().toString(36)}` |

#### `OverflowMenuItem` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `OverflowMenuItem` forwarded events

| Event        |
| ------------ |
| `on:keydown` |

#### `OverflowMenuItem` dispatched events

| Event      | Detail       |
| ---------- | ------------ |
| `on:click` | `MouseEvent` |

#### `OverflowMenuItem` $$restProps

`OverflowMenuItem` spreads `$$restProps` to the `li` element.


## Pagination

Pagination provides navigation controls for large data sets. It displays the
current page, total items, and allows users to change page size and navigate
between pages.

### Default

Create a basic pagination component with default page size options.

```svelte
<script>
  import { Pagination } from "carbon-components-svelte";
</script>

<Pagination totalItems={102} pageSizes={[10, 15, 20]} />
```

### Current page

Set the current page using the `page` prop.

```svelte
<script>
  import { Pagination } from "carbon-components-svelte";
</script>

<Pagination totalItems={102} page={4} />
```

### Custom page sizes

Specify custom page sizes and set a default page size.

```svelte
<script>
  import { Pagination } from "carbon-components-svelte";
</script>

<Pagination totalItems={102} pageSizes={[16, 36, 99]} pageSize={36} />
```

### Dynamic page sizes

Set `dynamicPageSizes` to `true` to automatically filter out redundant page
sizes based on `totalItems`. Page sizes larger than needed to display all items
on a single page are hidden.

For example, with a total of 9 items and page sizes of `[5, 10, 15]`, the page
sizes will be `[5, 10]`. This is because 10 is already larger than the total
number of items.

```svelte
<script>
  import { Pagination } from "carbon-components-svelte";
</script>

<Pagination totalItems={9} pageSizes={[5, 10, 15]} dynamicPageSizes />
```

### Unknown pages

Set `pagesUnknown` to `true` when the total number of pages is unknown. This
renders the item range text without factoring in the total number of pages.

```svelte
<script>
  import { Pagination } from "carbon-components-svelte";
</script>

<Pagination pagesUnknown />
```

### Page window

The number of native select items rendered is derived from `totalItems`. For
large datasets, this can impact performance. Use `pageWindow` to control the
number of rendered items.

```svelte
<script>
  import { Pagination } from "carbon-components-svelte";
</script>

<Pagination totalItems={100_000} pageSizes={[10, 15, 20]} />
```

### Hidden page input

Disable the page input by setting `pageInputDisabled` to `true`.

```svelte
<script>
  import { Pagination } from "carbon-components-svelte";
</script>

<Pagination totalItems={102} pageInputDisabled />
```

### Hidden page size

Disable the page size selector by setting `pageSizeInputDisabled` to `true`.

```svelte
<script>
  import { Pagination } from "carbon-components-svelte";
</script>

<Pagination totalItems={102} pageSizeInputDisabled />
```

### Skeleton

Use the pagination skeleton to show a loading state.

```svelte
<script>
  import { PaginationSkeleton } from "carbon-components-svelte";
</script>

<PaginationSkeleton />
```

---

### Component API

#### `Pagination` props

| Prop                    | Type                                                  | Description                                                                                                                                                                                                                                                                                                                                         | Default                             |
| ----------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `page` (Reactive)       | `number`                                              | Specify the current page index                                                                                                                                                                                                                                                                                                                      | `1`                                 |
| `pageSize` (Reactive)   | `number`                                              | Specify the number of items to display in a page                                                                                                                                                                                                                                                                                                    | `10`                                |
| `totalItems`            | `number`                                              | Specify the total number of items                                                                                                                                                                                                                                                                                                                   | `0`                                 |
| `pageWindow`            | `number`                                              | If `totalItems` is a large number, it can affect the<br />rendering performance of this component since its value<br />is used to calculate the number of pages in the native<br />select dropdown. This value creates a small window of<br />pages rendered around the current page. By default,<br />a maximum of 1000 select items are rendered. | `1000`                              |
| `disabled`              | `boolean`                                             | Set to `true` to disable the pagination                                                                                                                                                                                                                                                                                                             | `false`                             |
| `forwardText`           | `string`                                              | Specify the forward button text                                                                                                                                                                                                                                                                                                                     | `"Next page"`                       |
| `backwardText`          | `string`                                              | Specify the backward button text                                                                                                                                                                                                                                                                                                                    | `"Previous page"`                   |
| `itemsPerPageText`      | `string`                                              | Specify the items per page text                                                                                                                                                                                                                                                                                                                     | `"Items per page:"`                 |
| `itemText`              | `(min: number, max: number) => string`                | Override the item text.                                                                                                                                                                                                                                                                                                                             | _undefined_                         |
| `itemRangeText`         | `(min: number, max: number, total: number) => string` | Override the item range text.                                                                                                                                                                                                                                                                                                                       | _undefined_                         |
| `pageInputDisabled`     | `boolean`                                             | Set to `true` to disable the page input                                                                                                                                                                                                                                                                                                             | `false`                             |
| `pageSizeInputDisabled` | `boolean`                                             | Set to `true` to disable the page size input                                                                                                                                                                                                                                                                                                        | `false`                             |
| `pageSizes`             | `ReadonlyArray<number>`                               | Specify the available page sizes.                                                                                                                                                                                                                                                                                                                   | `[10]`                              |
| `dynamicPageSizes`      | `boolean`                                             | Set to `true` to dynamically filter page sizes based on total items.<br />Page sizes larger than needed to display all items on a single page are hidden.                                                                                                                                                                                           | `false`                             |
| `pagesUnknown`          | `boolean`                                             | Set to `true` if the number of pages is unknown                                                                                                                                                                                                                                                                                                     | `false`                             |
| `pageText`              | `(page: number) => string`                            | Override the page text.                                                                                                                                                                                                                                                                                                                             | _undefined_                         |
| `pageRangeText`         | `(current: number, total: number) => string`          | Override the page range text.                                                                                                                                                                                                                                                                                                                       | _undefined_                         |
| `id`                    | `string`                                              | Set an id for the top-level element                                                                                                                                                                                                                                                                                                                 | `ccs-${Math.random().toString(36)}` |

#### `Pagination` dispatched events

| Event                       | Detail                                                   | Description                                                                     |
| --------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `on:change`                 | `{<br /> page?: number;<br /> pageSize?: number;<br />}` | Dispatched when the user changes the page or page size through any interaction. |
| `on:click:button--previous` | `{<br /> page: number;<br />}`                           | Dispatched when the user clicks the previous page button.                       |
| `on:click:button--next`     | `{<br /> page: number;<br />}`                           | Dispatched when the user clicks the next page button.                           |
| `on:update`                 | `{<br /> pageSize: number;<br /> page: number;<br />}`   | Dispatched reactively whenever the page or page size changes.                   |

#### `Pagination` $$restProps

`Pagination` spreads `$$restProps` to the `div` element.

#### `PaginationSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `PaginationSkeleton` $$restProps

`PaginationSkeleton` spreads `$$restProps` to the `div` element.


## PaginationNav

Pagination nav provides a compact navigation interface for paginated content. It
displays page numbers and navigation buttons, with support for overflow menus
when there are many pages.

### Default

Create a basic pagination navigation with default settings.

```svelte
<script>
  import { PaginationNav } from "carbon-components-svelte";
</script>

<PaginationNav />
```

### Reactive example

Use the `page` prop to bind to the current page number.

```svelte
<script>
  import { Button, PaginationNav } from "carbon-components-svelte";

  let page = 2;
</script>

<PaginationNav bind:page />

<div style="margin: var(--cds-layout-01) 0">
  <Button on:click={() => (page = 1)} disabled={page === 0}>
    Set page to 1
  </Button>
</div>

<strong>page:</strong>
{page}
```

### Total pages

Specify the total number of pages using the `total` prop.

```svelte
<script>
  import { PaginationNav } from "carbon-components-svelte";
</script>

<PaginationNav total={3} />
```

### Loop navigation

Set `loop` to `true` to enable circular navigation between pages.

```svelte
<script>
  import { PaginationNav } from "carbon-components-svelte";
</script>

<PaginationNav total={3} loop />
```

### Visible pages

Control the number of visible page numbers with the `shown` prop.

```svelte
<script>
  import { PaginationNav } from "carbon-components-svelte";
</script>

<PaginationNav total={100} shown={5} />
```

### Custom button text

Customize the navigation button text using `forwardText` and `backwardText`.

```svelte
<script>
  import { PaginationNav } from "carbon-components-svelte";
</script>

<PaginationNav forwardText="Next" backwardText="Previous" />
```

### Tooltip position

Set the tooltip position relative to the navigation buttons using
`tooltipPosition`.

```svelte
<script>
  import { PaginationNav } from "carbon-components-svelte";
</script>

<PaginationNav tooltipPosition="outside" total={3} loop />
```

---

### Component API

#### `PaginationNav` props

| Prop              | Type                                                              | Description                                                         | Default           |
| ----------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------- |
| `page` (Reactive) | `number`                                                          | Specify the current page index                                      | `1`               |
| `total`           | `number`                                                          | Specify the total number of pages                                   | `10`              |
| `shown`           | `number`                                                          | Specify the total number of pages to show                           | `10`              |
| `loop`            | `boolean`                                                         | Set to `true` to loop the navigation                                | `false`           |
| `forwardText`     | `string`                                                          | Specify the forward button text                                     | `"Next page"`     |
| `backwardText`    | `string`                                                          | Specify the backward button text                                    | `"Previous page"` |
| `tooltipPosition` | `"top" \| "right" \| "bottom" \| "left" \| "outside" \| "inside"` | Set the position of the tooltip relative to the pagination buttons. | `"bottom"`        |

#### `PaginationNav` dispatched events

| Event                       | Detail                         | Description                        |
| --------------------------- | ------------------------------ | ---------------------------------- |
| `on:change`                 | `{<br /> page: number;<br />}` | Fires after every user interaction |
| `on:click:button--previous` | `{<br /> page: number;<br />}` |                                    |
| `on:click:button--next`     | `{<br /> page: number;<br />}` |                                    |

#### `PaginationNav` $$restProps

`PaginationNav` spreads `$$restProps` to the `nav` element.


## PasswordInput

Password inputs provide a secure text input field with a visibility toggle for
password entry. They include features for validation, warnings, and
accessibility.

### Default

Create a basic password input with a label and placeholder.

```svelte
<script>
  import { PasswordInput } from "carbon-components-svelte";
</script>

<PasswordInput labelText="Password" placeholder="Enter password..." />
```

### Custom tooltip alignment

Customize the tooltip alignment and position of the visibility toggle through
the `tooltipAlignment` and `tooltipPosition` props.

```svelte
<script>
  import { PasswordInput } from "carbon-components-svelte";
</script>

<PasswordInput
  tooltipAlignment="start"
  tooltipPosition="left"
  labelText="Password"
  placeholder="Enter password..."
/>
```

### Password is visible

Set prop `type` to `"text"` to toggle password visibility.

```svelte
<script>
  import { PasswordInput } from "carbon-components-svelte";
</script>

<PasswordInput
  labelText="Password"
  type="text"
  placeholder="Enter password..."
  value="as_lta0890sdfpo__!9901"
/>
```

### Hidden label

Visually hide the label while maintaining accessibility.

```svelte
<script>
  import { PasswordInput } from "carbon-components-svelte";
</script>

<PasswordInput hideLabel labelText="Password" placeholder="Enter password..." />
```

### Light variant

Enable the light variant for use on dark backgrounds.

```svelte
<script>
  import { PasswordInput } from "carbon-components-svelte";
</script>

<PasswordInput light labelText="Password" placeholder="Enter password..." />
```

### Inline

Display the input with an inline label layout.

```svelte
<script>
  import { PasswordInput } from "carbon-components-svelte";
</script>

<PasswordInput inline labelText="Password" placeholder="Enter password..." />
```

### Extra-large size

Use the extra-large size variant for increased visibility.

```svelte
<script>
  import { PasswordInput } from "carbon-components-svelte";
</script>

<PasswordInput size="xl" labelText="Password" placeholder="Enter password..." />
```

### Small size

Use the small size variant for compact layouts.

```svelte
<script>
  import { PasswordInput } from "carbon-components-svelte";
</script>

<PasswordInput size="sm" labelText="Password" placeholder="Enter password..." />
```

### Invalid state

Display an error message when the input is invalid.

```svelte
<script>
  import { PasswordInput } from "carbon-components-svelte";
</script>

<PasswordInput
  invalid
  invalidText="Incorrect user name or password."
  labelText="Password"
  placeholder="Enter password..."
/>
```

### Warning state

Show a warning message for non-critical issues.

```svelte
<script>
  import { PasswordInput } from "carbon-components-svelte";
</script>

<PasswordInput
  warn
  warnText="Password has been reset."
  labelText="Password"
  placeholder="Enter password..."
/>
```

### Disabled state

Disable the input to prevent user interaction.

```svelte
<script>
  import { PasswordInput } from "carbon-components-svelte";
</script>

<PasswordInput disabled labelText="Password" placeholder="Enter password..." />
```

### Read-only state

Set the input to read-only to display a value that cannot be modified. The
visibility toggle still works to show or hide the password.

```svelte
<script>
  import { PasswordInput } from "carbon-components-svelte";
</script>

<PasswordInput
  readonly
  labelText="Password"
  placeholder="Enter password..."
  value="mySecretPassword123"
/>
```

### With helper text

Add helper text to provide additional context or instructions.

```svelte
<script>
  import { PasswordInput } from "carbon-components-svelte";
</script>

<PasswordInput
  helperText="Your password should be hard to guess"
  labelText="Password"
  placeholder="Enter password..."
/>
```

---

### Component API

#### `PasswordInput` props

| Prop                | Type                                     | Description                                            | Default                             |
| ------------------- | ---------------------------------------- | ------------------------------------------------------ | ----------------------------------- |
| `value` (Reactive)  | `number \| string`                       | Specify the input value.                               | `""`                                |
| `type` (Reactive)   | `"text" \| "password"`                   | Set to `"text"` to toggle the password visibility.     | `"password"`                        |
| `ref` (Reactive)    | `null \| HTMLInputElement`               | Obtain a reference to the input HTML element           | `null`                              |
| `size`              | `"sm" \| "xl"`                           | Set the size of the input.                             | _undefined_                         |
| `placeholder`       | `string`                                 | Specify the placeholder text                           | `""`                                |
| `hidePasswordLabel` | `string`                                 | Specify the hide password label text                   | `"Hide password"`                   |
| `showPasswordLabel` | `string`                                 | Specify the show password label text                   | `"Show password"`                   |
| `tooltipAlignment`  | `"start" \| "center" \| "end"`           | Set the alignment of the tooltip relative to the icon. | `"center"`                          |
| `tooltipPosition`   | `"top" \| "right" \| "bottom" \| "left"` | Set the position of the tooltip relative to the icon.  | `"bottom"`                          |
| `light`             | `boolean`                                | Set to `true` to enable the light variant              | `false`                             |
| `disabled`          | `boolean`                                | Set to `true` to disable the input                     | `false`                             |
| `helperText`        | `string`                                 | Specify the helper text                                | `""`                                |
| `labelText`         | `string`                                 | Specify the label text                                 | `""`                                |
| `hideLabel`         | `boolean`                                | Set to `true` to visually hide the label text          | `false`                             |
| `invalid`           | `boolean`                                | Set to `true` to indicate an invalid state             | `false`                             |
| `invalidText`       | `string`                                 | Specify the text for the invalid state                 | `""`                                |
| `warn`              | `boolean`                                | Set to `true` to indicate a warning state              | `false`                             |
| `warnText`          | `string`                                 | Specify the warning state text                         | `""`                                |
| `inline`            | `boolean`                                | Set to `true` to use inline version                    | `false`                             |
| `id`                | `string`                                 | Set an id for the input element                        | `ccs-${Math.random().toString(36)}` |
| `name`              | `string`                                 | Specify a name attribute for the input.                | _undefined_                         |

#### `PasswordInput` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `labelChildren` | `Record<string, never>` |

#### `PasswordInput` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:change`     |
| `on:input`      |
| `on:keydown`    |
| `on:keyup`      |
| `on:focus`      |
| `on:blur`       |
| `on:paste`      |

#### `PasswordInput` $$restProps

`PasswordInput` spreads `$$restProps` to the `input` element.


## Popover

Popovers provide a floating container that displays content relative to a
trigger element. They support various alignments, caret indicators, and visual
variants.

### Default

Create a basic popover with absolute positioning.

```svelte
<script>
  import { Popover } from "carbon-components-svelte";
</script>

<div>
  Parent
  <Popover open>Content</Popover>
</div>
```

### Relative position

Set `relative` to `true` to position the popover relative to its parent element.

```svelte
<script>
  import { Popover } from "carbon-components-svelte";
</script>

<div>
  Parent
  <Popover relative open>Content</Popover>
</div>
```

### Close on outside click

Enable automatic closing when clicking outside the popover using
`closeOnOutsideClick`.

```svelte
<script>
  import { Popover } from "carbon-components-svelte";
</script>

<div>
  Parent
  <Popover
    open
    closeOnOutsideClick
    on:click:outside={() => {
      console.log("on:click:outside");
    }}
  >
    Content
  </Popover>
</div>
```

### Popover alignment

Customize the popover alignment using the `align` prop. Valid values include:
`"top" | "top-left" | "top-right" | "bottom" | "bottom-left" | "bottom-right" | "left" | "left-bottom" | "left-top" | "right" | "right-bottom" | "right-top"`.

The default `align` value is `"top"`.

```svelte
<script>
  import { Popover, Stack } from "carbon-components-svelte";
</script>

<Stack gap={10}>
  <div>
    Parent
    <Popover open align="top-left">top-left</Popover>
  </div>
  <div>
    Parent
    <Popover open align="top-right">top-right</Popover>
  </div>
  <div>
    Parent
    <Popover open align="bottom">bottom</Popover>
  </div>
  <div>
    Parent
    <Popover open align="bottom-left">bottom-left</Popover>
  </div>
  <div>
    Parent
    <Popover open align="bottom-right">
      <div>bottom-right</div>
    </Popover>
  </div>
  <div>
    Parent
    <Popover open align="left">left</Popover>
  </div>
  <div>
    Parent
    <Popover open align="left-bottom">left-bottom</Popover>
  </div>
  <div>
    Parent
    <Popover open align="left-right">left-right</Popover>
  </div>
  <div>
    Parent
    <Popover open align="right">right</Popover>
  </div>
  <div>
    Parent
    <Popover open align="right-bottom">right-bottom</Popover>
  </div>
  <div>
    Parent
    <Popover open align="right-top">right-top</Popover>
  </div>
</Stack>
```

### With caret

Add a caret indicator to the popover using the `caret` prop.

```svelte
<script>
  import { Popover } from "carbon-components-svelte";
</script>

<div>
  Parent
  <Popover caret open>Content</Popover>
</div>
```

### Custom caret alignment

By default, the caret is aligned "top". Possible `align` values include `"top"`,
`"top-left"`, `"top-right"`, `"bottom"`, `"bottom-left"`, `"bottom-right"`,
`"left"`, `"left-bottom"`, `"left-top"`, `"right"`, `"right-bottom"` or
`"right-top"`.

```svelte
<script>
  import { Popover } from "carbon-components-svelte";
</script>

<div>
  Parent
  <Popover caret align="top-left" open>Content</Popover>
</div>
```

### Light variant

Enable the light variant for use on dark backgrounds.

```svelte
<script>
  import { Popover } from "carbon-components-svelte";
</script>

<div>
  Parent
  <Popover light open>Content</Popover>
</div>
```

### High contrast variant

Enable the high contrast variant for improved visibility.

```svelte
<script>
  import { Popover } from "carbon-components-svelte";
</script>

<div>
  Parent
  <Popover highContrast open>Content</Popover>
</div>
```

### External element

Use the `open` prop to manage state with an external element, like a button.

```svelte
<script>
  import { Button, Popover } from "carbon-components-svelte";

  let open = true;
  let ref = null;
</script>

<div bind:this={ref} style:position="relative">
  <Button on:click={() => (open = !open)}>Toggle popover</Button>
  <Popover
    bind:open
    align="bottom-left"
    on:click:outside={({ detail }) => {
      console.log("on:click:outside");
      open = ref.contains(detail.target);
    }}
  >
    Content
  </Popover>
</div>
```

---

### Component API

#### `Popover` props

| Prop                  | Type                                                                                                                                                                     | Description                                            | Default |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------- |
| `open` (Reactive)     | `boolean`                                                                                                                                                                | Set to `true` to display the popover                   | `false` |
| `closeOnOutsideClick` | `boolean`                                                                                                                                                                | Set to `true` to close the popover on an outside click | `false` |
| `caret`               | `boolean`                                                                                                                                                                | Set to `true` render a caret                           | `false` |
| `align`               | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right" \| "left" \| "left-bottom" \| "left-top" \| "right" \| "right-bottom" \| "right-top"` | Specify the alignment of the caret.                    | `"top"` |
| `light`               | `boolean`                                                                                                                                                                | Set to `true` to enable the light variant              | `false` |
| `highContrast`        | `boolean`                                                                                                                                                                | Set to `true` to enable the high contrast variant      | `false` |
| `relative`            | `boolean`                                                                                                                                                                | Set to `true` to use a relative position               | `false` |

#### `Popover` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `Popover` dispatched events

| Event              | Detail                                |
| ------------------ | ------------------------------------- |
| `on:click:outside` | `{<br /> target: HTMLElement;<br />}` |

#### `Popover` $$restProps

`Popover` spreads `$$restProps` to the `div` element.


## Portal

Portals render their content directly into `document.body`, allowing you to
escape parent overflow constraints and z-index stacking contexts.

For anchored, positioned content (e.g., dropdowns, popovers, overflow menus),
use [FloatingPortal](/components/FloatingPortal) instead.

### Default Portal

Render content in a portal. This is useful for modals, tooltips, and menus that
need to escape parent containers.

```svelte
<script>
  import { Portal } from "carbon-components-svelte";
</script>

<div>
  <div>This is rendered inside the div</div>
  <br />
  <Portal>This is rendered outside of the div</Portal>
</div>
```

### Multiple Portals

Each portal instance is independent and creates its own element in
`document.body`. Each portal is automatically cleaned up when it is removed.

```svelte
<script>
  import { Button, ButtonSet, Portal } from "carbon-components-svelte";

  let showPortal1 = false;
  let showPortal2 = false;
</script>

<ButtonSet>
  <Button on:click={() => (showPortal1 = !showPortal1)}>
    {showPortal1 ? "Unmount portal 1" : "Mount portal 1"}
  </Button>
  <Button on:click={() => (showPortal2 = !showPortal2)}>
    {showPortal2 ? "Unmount portal 2" : "Mount portal 2"}
  </Button>
</ButtonSet>

{#if showPortal1}
  <Portal>Portal content 1</Portal>
{/if}

{#if showPortal2}
  <Portal>Portal content 2</Portal>
{/if}
```

### Custom Tag

Use the `tag` prop to specify a custom HTML element. By default, the portal uses
a `div` element.

```svelte
<script>
  import { Portal } from "carbon-components-svelte";
</script>

<Portal tag="section">This portal uses a section tag.</Portal>
```

### Modal with Portal

Wrap the modal in a portal to escape parent containers with `overflow: hidden`
or z-index stacking contexts. This ensures the modal appears above all content
and isn't clipped by parent boundaries.

```svelte
<script>
  import { Button, Modal, Portal, Stack } from "carbon-components-svelte";

  let open = false;
</script>

<Stack gap={5} style="overflow: hidden; position: relative; height: 200px;">
  <p>
    This container hides overflowing content. Without a portal, the modal would
    be clipped.
  </p>
  <div>
    <Button on:click={() => (open = true)}>Open modal</Button>
  </div>
  <Portal>
    <Modal
      bind:open
      modalHeading="Modal in Portal"
      primaryButtonText="Confirm"
      secondaryButtonText="Cancel"
      on:click:button--secondary={() => (open = false)}
    >
      <p>
        This modal is rendered in a portal, escaping the parent container's
        overflow constraints and ensuring it appears above all other content.
      </p>
    </Modal>
  </Portal>
</Stack>
```

---

### Component API

#### `Portal` props

| Prop             | Type                          | Description                               | Default |
| ---------------- | ----------------------------- | ----------------------------------------- | ------- |
| `ref` (Reactive) | `null \| HTMLElement`         | Obtain a reference to the portal element. | `null`  |
| `tag`            | `keyof HTMLElementTagNameMap` | Specify the tag name.                     | `"div"` |

#### `Portal` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `Portal` $$restProps

`Portal` spreads `$$restProps` to the `svelte:element` element.


## ProgressBar

Progress bars provide a visual indicator of progress for operations such as file
uploads or data processing. They support determinate and indeterminate states,
various sizes, and status indicators.

### Default

Create an indeterminate progress bar that continuously animates.

```svelte
<script>
  import { ProgressBar } from "carbon-components-svelte";
</script>

<ProgressBar helperText="Loading..." />
```

### Small size

Use the small size variant for compact layouts.

```svelte
<script>
  import { ProgressBar } from "carbon-components-svelte";
</script>

<ProgressBar size="sm" helperText="Loading..." />
```

### Percentage

Display progress as a percentage using the `value` prop.

```svelte
<script>
  import { ProgressBar } from "carbon-components-svelte";
</script>

<ProgressBar
  value={40}
  labelText="Upload status"
  helperText="40 MB of 100 MB"
/>
```

### Finished status

Show completion status with a checkmark icon.

```svelte
<script>
  import { ProgressBar } from "carbon-components-svelte";
</script>

<ProgressBar
  value={100}
  status="finished"
  labelText="Upload file"
  helperText="Upload complete"
/>
```

### Error status

Indicate errors with an error icon and red styling.

```svelte
<script>
  import { ProgressBar } from "carbon-components-svelte";
</script>

<ProgressBar
  value={0}
  status="error"
  labelText="Upload file"
  helperText="Invalid file format"
/>
```

### Custom max value

Set a custom maximum value for the progress bar.

```svelte
<script>
  import { ProgressBar } from "carbon-components-svelte";
</script>

<ProgressBar
  value={40}
  max={200}
  labelText="Upload status"
  helperText="40 MB of 200 MB"
/>
```

### Hidden label

Visually hide the label while maintaining accessibility.

```svelte
<script>
  import { ProgressBar } from "carbon-components-svelte";
</script>

<ProgressBar
  hideLabel
  value={40}
  labelText="Upload status"
  helperText="40 MB of 100 MB"
/>
```

### Inline variant

Use the inline variant to display progress without helper text.

```svelte
<script>
  import { ProgressBar } from "carbon-components-svelte";
</script>

<ProgressBar
  kind="inline"
  value={40}
  labelText="Upload status"
  helperText="40 MB of 100 MB"
/>
```

### Indented variant

Use the indented variant for a more compact layout.

```svelte
<script>
  import { ProgressBar } from "carbon-components-svelte";
</script>

<ProgressBar
  kind="indented"
  value={40}
  labelText="Upload status"
  helperText="40 MB of 100 MB"
/>
```

### Indented status variant

Combine the indented variant with status indicators.

```svelte
<script>
  import { ProgressBar } from "carbon-components-svelte";
</script>

<ProgressBar
  kind="indented"
  status="finished"
  value={40}
  labelText="Upload file"
  helperText="Upload complete"
/>
```

### UX example

Demonstrate a complete upload flow with start and end states.

```svelte
<script>
  import { Button, ButtonSet, ProgressBar } from "carbon-components-svelte";

  let max = 328;
  let value = 0;
  let status = "active";

  $: helperText =
    value > 0 ? `${value.toFixed(0)}MB of ${max}MB` : "Press start";
  $: if (value === max) {
    helperText = "Done";
    status = "finished";
  }
</script>

<ProgressBar labelText="Upload status" {value} {max} {helperText} {status} />

<ButtonSet style="margin-top: var(--cds-spacing-08)">
  <Button
    disabled={value > 0}
    on:click={() => {
      const interval = setInterval(() => {
        const delta = Math.random() * 10;

        if (value + delta < max) {
          value += delta;
        } else {
          value = max;
          clearInterval(interval);
        }
      }, 30);
    }}
  >
    Start
  </Button>
  <Button
    kind="tertiary"
    disabled={value !== max}
    on:click={() => {
      value = 0;
      status = "active";
    }}
  >
    Reset
  </Button>
</ButtonSet>
```

---

### Component API

#### `ProgressBar` props

| Prop         | Type                                  | Description                                   | Default                             |
| ------------ | ------------------------------------- | --------------------------------------------- | ----------------------------------- |
| `value`      | `number`                              | Specify the current value.                    | _undefined_                         |
| `max`        | `number`                              | Specify the maximum value                     | `100`                               |
| `kind`       | `"default" \| "inline" \| "indented"` | Specify the kind of progress bar.             | `"default"`                         |
| `status`     | `"active" \| "finished" \| "error"`   | Specify the status.                           | `"active"`                          |
| `size`       | `"sm" \| "md"`                        | Specify the size.                             | `"md"`                              |
| `labelText`  | `string`                              | Specify the label text                        | `""`                                |
| `hideLabel`  | `boolean`                             | Set to `true` to visually hide the label text | `false`                             |
| `helperText` | `string`                              | Specify the helper text                       | `""`                                |
| `id`         | `string`                              | Set an id for the progress bar element        | `ccs-${Math.random().toString(36)}` |

#### `ProgressBar` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `labelChildren` | `Record<string, never>` |

#### `ProgressBar` $$restProps

`ProgressBar` spreads `$$restProps` to the `div` element.


## ProgressIndicator

Progress indicators provide a visual representation of progress through a
sequence of steps. They support horizontal and vertical layouts, step completion
states, and interactive navigation.

### Default

Create a horizontal progress indicator with four steps.

```svelte
<script>
  import { ProgressIndicator, ProgressStep } from "carbon-components-svelte";
</script>

<ProgressIndicator currentIndex={2}>
  <ProgressStep
    complete
    label="Step 1"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    complete
    label="Step 2"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    complete
    label="Step 3"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    label="Step 4"
    description="The progress indicator will listen for clicks on the steps"
  />
</ProgressIndicator>
```

### Prevent change on click

Disable automatic step selection when clicking completed steps.

```svelte
<script>
  import { ProgressIndicator, ProgressStep } from "carbon-components-svelte";
</script>

<ProgressIndicator preventChangeOnClick currentIndex={2}>
  <ProgressStep
    complete
    label="Step 1"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    complete
    label="Step 2"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    complete
    label="Step 3"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    label="Step 4"
    description="The progress indicator will listen for clicks on the steps"
  />
</ProgressIndicator>
```

### Programmatic usage

Update the current step programmatically while maintaining step completion
rules.

```svelte
<script>
  import {
    Button,
    ProgressIndicator,
    ProgressStep,
  } from "carbon-components-svelte";

  let currentIndex = 1;
  let thirdStepCurrent = false;
</script>

<ProgressIndicator bind:currentIndex>
  <ProgressStep
    complete
    label="Step 1"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    complete
    label="Step 2"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    complete
    bind:current={thirdStepCurrent}
    label="Step 3"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    label="Step 4"
    description="The progress indicator will listen for clicks on the steps"
  />
</ProgressIndicator>

<div style="margin: var(--cds-layout-02) 0">
  <Button
    kind={currentIndex === 2 ? "secondary" : "primary"}
    on:click={() => {
      currentIndex = currentIndex === 2 ? 0 : 2;
    }}
  >
    Set currentIndex to
    {currentIndex === 2 ? 0 : 2}
  </Button>
</div>

<h3>Current index: {currentIndex}</h3>

<div>Is the third step currently selected? {thirdStepCurrent}</div>
```

### Invalid step

Mark a step as invalid to indicate an error state.

```svelte
<script>
  import { ProgressIndicator, ProgressStep } from "carbon-components-svelte";
</script>

<ProgressIndicator>
  <ProgressStep
    complete
    label="Step 1"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    invalid
    label="Step 2"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    label="Step 3"
    description="The progress indicator will listen for clicks on the steps"
  />
</ProgressIndicator>
```

### Disabled steps

Disable specific steps to prevent user interaction.

```svelte
<script>
  import { ProgressIndicator, ProgressStep } from "carbon-components-svelte";
</script>

<ProgressIndicator>
  <ProgressStep
    complete
    label="Step 1"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    disabled
    label="Step 2"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    disabled
    label="Step 3"
    description="The progress indicator will listen for clicks on the steps"
  />
</ProgressIndicator>
```

### Spaced-equally

Distribute steps evenly across the available space.

```svelte
<script>
  import { ProgressIndicator, ProgressStep } from "carbon-components-svelte";
</script>

<ProgressIndicator spaceEqually>
  <ProgressStep
    label="Really long label"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    label="Really long label"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    label="Really long label"
    description="The progress indicator will listen for clicks on the steps"
  />
</ProgressIndicator>
```

### Vertical

Display steps in a vertical layout.

```svelte
<script>
  import { ProgressIndicator, ProgressStep } from "carbon-components-svelte";
</script>

<ProgressIndicator vertical>
  <ProgressStep
    label="Really long label"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    label="Really long label"
    description="The progress indicator will listen for clicks on the steps"
  />
  <ProgressStep
    label="Really long label"
    description="The progress indicator will listen for clicks on the steps"
  />
</ProgressIndicator>
```

### Skeleton

Show a loading state with the specified number of steps.

```svelte
<script>
  import { ProgressIndicatorSkeleton } from "carbon-components-svelte";
</script>

<ProgressIndicatorSkeleton />
```

### Skeleton (vertical)

Show a vertical loading state with the specified number of steps.

```svelte
<script>
  import { ProgressIndicatorSkeleton } from "carbon-components-svelte";
</script>

<ProgressIndicatorSkeleton vertical />
```

---

### Component API

#### `ProgressIndicator` props

| Prop                      | Type      | Description                                                                                    | Default |
| ------------------------- | --------- | ---------------------------------------------------------------------------------------------- | ------- |
| `currentIndex` (Reactive) | `number`  | Specify the current step index                                                                 | `0`     |
| `vertical`                | `boolean` | Set to `true` to use the vertical variant                                                      | `false` |
| `spaceEqually`            | `boolean` | Set to `true` to specify whether the progress steps should be split equally in size in the div | `false` |
| `preventChangeOnClick`    | `boolean` | Set to `true` to prevent `currentIndex` from updating                                          | `false` |

#### `ProgressIndicator` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ProgressIndicator` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `ProgressIndicator` dispatched events

| Event       | Detail   |
| ----------- | -------- |
| `on:change` | `number` |

#### `ProgressIndicator` $$restProps

`ProgressIndicator` spreads `$$restProps` to the `ul` element.

#### `ProgressStep` props

| Prop                 | Type      | Description                                | Default                             |
| -------------------- | --------- | ------------------------------------------ | ----------------------------------- |
| `current` (Reactive) | `boolean` | Set to `true` to use the current variant   | `false`                             |
| `complete`           | `boolean` | Set to `true` for the complete variant     | `false`                             |
| `disabled`           | `boolean` | Set to `true` to disable the progress step | `false`                             |
| `invalid`            | `boolean` | Set to `true` to indicate an invalid state | `false`                             |
| `description`        | `string`  | Specify the step description               | `""`                                |
| `label`              | `string`  | Specify the step label                     | `""`                                |
| `secondaryLabel`     | `string`  | Specify the step secondary label           | `""`                                |
| `id`                 | `string`  | Set an id for the top-level element        | `ccs-${Math.random().toString(36)}` |

#### `ProgressStep` slots

| Slot      | Detail                                                                |
| --------- | --------------------------------------------------------------------- |
| `default` | `{<br /> props: {<br /> class: "bx--progress-label";<br /> };<br />}` |

#### `ProgressStep` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:keydown`    |

#### `ProgressStep` $$restProps

`ProgressStep` spreads `$$restProps` to the `li` element.

#### `ProgressIndicatorSkeleton` props

| Prop       | Type      | Description                               | Default |
| ---------- | --------- | ----------------------------------------- | ------- |
| `vertical` | `boolean` | Set to `true` to use the vertical variant | `false` |
| `count`    | `number`  | Specify the number of steps to render     | `4`     |

#### `ProgressIndicatorSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `ProgressIndicatorSkeleton` $$restProps

`ProgressIndicatorSkeleton` spreads `$$restProps` to the `ul` element.


## RadioButton

Radio buttons provide a selection control that allows users to choose a single
option from a set. They support both individual and grouped usage, with options
for horizontal and vertical layouts.

### Default

Create a group of radio buttons with a shared name and legend.

See [Standalone usage](#standalone-usage) for individual usage or
[Implicit grouping](#implicit-grouping) to group multiple standalone radio
buttons by name without using a radio button group.

```svelte
<script>
  import { RadioButton, RadioButtonGroup } from "carbon-components-svelte";
</script>

<RadioButtonGroup
  legendText="Storage tier (disk)"
  name="plan"
  selected="standard"
>
  <RadioButton labelText="Free (1 GB)" value="free" />
  <RadioButton labelText="Standard (10 GB)" value="standard" />
  <RadioButton labelText="Pro (128 GB)" value="pro" />
</RadioButtonGroup>
```

### Standalone usage

Use a radio button individually with a bindable `checked` prop for simple use
cases.

```svelte
<script>
  import { Button, RadioButton } from "carbon-components-svelte";

  let agreedToTerms = false;
</script>

<div style:display="flex">
  <RadioButton
    bind:checked={agreedToTerms}
    labelText="I agree to the terms and conditions"
    name="terms"
    value="agreed"
  />
</div>

<div style:margin="var(--cds-layout-02) 0">
  <Button
    size="small"
    kind="secondary"
    disabled={!agreedToTerms}
    on:click={() => (agreedToTerms = !agreedToTerms)}
  >
    Reset
  </Button>
</div>
```

### Implicit grouping

Multiple standalone radio button components sharing the same `name` attribute
automatically form a group and synchronize their checked state. This allows you
to create radio button groups without using a radio button group.

```svelte
<script>
  import { RadioButton, Stack } from "carbon-components-svelte";

  const options = [
    { value: "option1", label: "Option 1" },
    { value: "option2", label: "Option 2" },
    { value: "option3", label: "Option 3" },
  ];

  let checked = options.map(() => false);

  $: selected = options.find((_, i) => checked[i]);
</script>

<Stack gap={3}>
  <Stack orientation="horizontal">
    {#each options as option, i}
      <RadioButton
        bind:checked={checked[i]}
        value={option.value}
        labelText={option.label}
        name="implicit-group"
      />
    {/each}
  </Stack>

  <span>
    Selected:
    <strong>{selected?.label ?? "None"}</strong>
  </span>
</Stack>
```

### Hidden legend

Visually hide the legend while maintaining accessibility.

```svelte
<script>
  import { RadioButton, RadioButtonGroup } from "carbon-components-svelte";
</script>

<RadioButtonGroup
  hideLegend
  legendText="Storage tier (disk)"
  name="plan-legend"
  selected="standard"
>
  <RadioButton labelText="Free (1 GB)" value="free" />
  <RadioButton labelText="Standard (10 GB)" value="standard" />
  <RadioButton labelText="Pro (128 GB)" value="pro" />
</RadioButtonGroup>
```

### Custom label content

Use the `labelChildren` slot to provide custom label content instead of using
the `labelText` prop.

```svelte
<script>
  import {
    RadioButton,
    RadioButtonGroup,
    Stack,
    Tooltip,
  } from "carbon-components-svelte";
</script>

<RadioButtonGroup name="plan-legend-slot" selected="standard">
  <Stack slot="legendChildren" orientation="horizontal">
    Storage tier (disk)
    <Tooltip>
      <p>Storage tiers may vary based on geolocation.</p>
    </Tooltip>
  </Stack>
  <RadioButton labelText="Free (1 GB)" value="free" />
  <RadioButton labelText="Standard (10 GB)" value="standard" />
  <RadioButton labelText="Pro (128 GB)" value="pro" />
</RadioButtonGroup>
```

### Reactive example

Bind and update the selected value programmatically.

```svelte
<script>
  import {
    Button,
    RadioButton,
    RadioButtonGroup,
  } from "carbon-components-svelte";

  const plans = ["Free (1 GB)", "Standard (10 GB)", "Pro (128 GB)"];

  let plan = plans[1];
</script>

<RadioButtonGroup
  legendText="Storage tier (disk)"
  name="plan"
  bind:selected={plan}
>
  {#each plans as value (value)}
    <RadioButton labelText={value} {value} />
  {/each}
</RadioButtonGroup>

<div style="margin: var(--cds-layout-03) 0">
  {#each plans as value (value)}
    <Button
      size="small"
      kind="secondary"
      disabled={plan === value}
      on:click={() => (plan = value)}
    >
      Select "{value}"
    </Button>
  {/each}
</div>

Selected plan:
<strong>{plan}</strong>
```

### Left-aligned label text

Position labels to the left of the radio buttons.

```svelte
<script>
  import { RadioButton, RadioButtonGroup } from "carbon-components-svelte";
</script>

<RadioButtonGroup
  labelPosition="left"
  legendText="Storage tier (disk)"
  name="plan-left-aligned"
  selected="standard"
>
  <RadioButton labelText="Free (1 GB)" value="free" />
  <RadioButton labelText="Standard (10 GB)" value="standard" />
  <RadioButton labelText="Pro (128 GB)" value="pro" />
</RadioButtonGroup>
```

### Disabled buttons

Disable specific radio buttons to prevent selection.

```svelte
<script>
  import { RadioButton, RadioButtonGroup } from "carbon-components-svelte";
</script>

<RadioButtonGroup
  labelPosition="left"
  legendText="Storage tier (disk)"
  name="plan-disabled"
  selected="standard"
>
  <RadioButton disabled labelText="Free (1 GB)" value="free" />
  <RadioButton labelText="Standard (10 GB)" value="standard" />
  <RadioButton disabled labelText="Pro (128 GB)" value="pro" />
</RadioButtonGroup>
```

### Helper text

Use `helperText` to provide additional context or instructions below the radio
button group.

```svelte
<script>
  import { RadioButton, RadioButtonGroup } from "carbon-components-svelte";
</script>

<RadioButtonGroup
  legendText="Notification preferences"
  name="plan-helper"
  selected="email"
  helperText="You can change this setting at any time"
>
  <RadioButton labelText="Email" value="email" />
  <RadioButton labelText="SMS" value="sms" />
  <RadioButton labelText="Push notifications" value="push" />
</RadioButtonGroup>
```

### Vertical orientation

Display radio buttons in a vertical layout.

```svelte
<script>
  import { RadioButton, RadioButtonGroup } from "carbon-components-svelte";
</script>

<RadioButtonGroup
  orientation="vertical"
  legendText="Storage tier (disk)"
  name="plan-vertical"
  selected="standard"
>
  <RadioButton labelText="Free (1 GB)" value="free" />
  <RadioButton labelText="Standard (10 GB)" value="standard" />
  <RadioButton labelText="Pro (128 GB)" value="pro" />
</RadioButtonGroup>
```

### Skeleton

Show a loading state for horizontal radio buttons.

```svelte
<script>
  import {
    RadioButtonGroup,
    RadioButtonSkeleton,
  } from "carbon-components-svelte";
</script>

<RadioButtonGroup legendText="Storage tier (disk)">
  <RadioButtonSkeleton />
  <RadioButtonSkeleton />
  <RadioButtonSkeleton />
</RadioButtonGroup>
```

### Skeleton (vertical)

Show a loading state for vertical radio buttons.

```svelte
<script>
  import {
    RadioButtonGroup,
    RadioButtonSkeleton,
  } from "carbon-components-svelte";
</script>

<RadioButtonGroup orientation="vertical" legendText="Storage tier (disk)">
  <RadioButtonSkeleton />
  <RadioButtonSkeleton />
  <RadioButtonSkeleton />
</RadioButtonGroup>
```

---

### Component API

#### `RadioButtonGroup` props

| Prop                  | Type                         | Description                                                                       | Default        |
| --------------------- | ---------------------------- | --------------------------------------------------------------------------------- | -------------- |
| `selected` (Reactive) | `Value \| undefined`         | Set the selected radio button value.                                              | _undefined_    |
| `disabled`            | `boolean`                    | Set to `true` to disable the radio buttons                                        | `false`        |
| `required`            | `boolean`                    | Set to `true` to require the selection of a radio button.                         | _undefined_    |
| `name`                | `string`                     | Specify a name attribute for the radio button inputs.                             | _undefined_    |
| `legendText`          | `string`                     | Specify the legend text.<br />Alternatively, use the named slot "legendChildren". | `""`           |
| `hideLegend`          | `boolean`                    | Set to `true` to visually hide the legend                                         | `false`        |
| `helperText`          | `string`                     | Specify the helper text                                                           | `""`           |
| `labelPosition`       | `"right" \| "left"`          | Specify the label position.                                                       | `"right"`      |
| `orientation`         | `"horizontal" \| "vertical"` | Specify the orientation of the radio buttons.                                     | `"horizontal"` |
| `id`                  | `string`                     | Set an id for the container div element.                                          | _undefined_    |

#### `RadioButtonGroup` slots

| Slot             | Detail                  |
| ---------------- | ----------------------- |
| `default`        | `Record<string, never>` |
| `legendChildren` | `Record<string, never>` |

#### `RadioButtonGroup` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `RadioButtonGroup` dispatched events

| Event       | Detail  |
| ----------- | ------- |
| `on:change` | `Value` |

#### `RadioButtonGroup` $$restProps

`RadioButtonGroup` spreads `$$restProps` to the `div` element.

#### `RadioButton` props

| Prop                 | Type                       | Description                                                                                                                                                                                                       | Default                             |
| -------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `checked` (Reactive) | `boolean`                  | Set to `true` to check the radio button                                                                                                                                                                           | `false`                             |
| `ref` (Reactive)     | `null \| HTMLInputElement` | Obtain a reference to the input HTML element                                                                                                                                                                      | `null`                              |
| `value`              | `Value`                    | Specify the value of the radio button.                                                                                                                                                                            | `""`                                |
| `disabled`           | `boolean`                  | Set to `true` to disable the radio button                                                                                                                                                                         | `false`                             |
| `required`           | `boolean`                  | Set to `true` to mark the field as required                                                                                                                                                                       | `false`                             |
| `labelPosition`      | `"right" \| "left"`        | Specify the label position.                                                                                                                                                                                       | `"right"`                           |
| `labelText`          | `string`                   | Specify the label text                                                                                                                                                                                            | `""`                                |
| `hideLabel`          | `boolean`                  | Set to `true` to visually hide the label text                                                                                                                                                                     | `false`                             |
| `id`                 | `string`                   | Set an id for the input element                                                                                                                                                                                   | `ccs-${Math.random().toString(36)}` |
| `name`               | `string`                   | Specify a name attribute for the radio button input.<br />When multiple standalone RadioButton components share the same `name`,<br />they form an implicit group and their `checked` state will be synchronized. | _undefined_                         |

#### `RadioButton` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `labelChildren` | `Record<string, never>` |

#### `RadioButton` forwarded events

| Event       |
| ----------- |
| `on:focus`  |
| `on:blur`   |
| `on:change` |

#### `RadioButton` $$restProps

`RadioButton` spreads `$$restProps` to the `div` element.

#### `RadioButtonSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `RadioButtonSkeleton` $$restProps

`RadioButtonSkeleton` spreads `$$restProps` to the `div` element.


## RadioTile

Radio tiles provide a selectable tile interface for choosing a single option
from a set. They support both individual and grouped usage, with options for
light and disabled states.

### Default

Create a group of radio tiles with a shared name and legend.

```svelte
<script>
  import { RadioTile, TileGroup } from "carbon-components-svelte";
</script>

<TileGroup legendText="Service pricing tiers" name="plan" selected="standard">
  <RadioTile value="lite">Lite plan</RadioTile>
  <RadioTile value="standard">Standard plan</RadioTile>
  <RadioTile value="plus">Plus plan</RadioTile>
</TileGroup>
```

### Reactive (one-way binding)

Update the selected value using the `select` event.

```svelte
<script>
  import { RadioTile, TileGroup } from "carbon-components-svelte";

  const values = ["Lite plan", "Standard plan", "Plus plan"];

  let selected = values[1];
</script>

<TileGroup
  legendText="Service pricing tiers"
  name="plan"
  on:select={({ detail }) => (selected = detail)}
>
  {#each values as value}
    <RadioTile {value} checked={selected === value}>
      {value}
    </RadioTile>
  {/each}
</TileGroup>

<br />

Selected: <strong>{selected}</strong>
```

### Reactive (two-way binding)

Bind to the `selected` prop for simpler state management.

```svelte
<script>
  import { Button, RadioTile, TileGroup } from "carbon-components-svelte";

  const values = ["Lite plan", "Standard plan", "Plus plan"];

  let selected = values[1];
</script>

<TileGroup legendText="Service pricing tiers" name="plan" bind:selected>
  {#each values as value}
    <RadioTile {value}>{value}</RadioTile>
  {/each}
</TileGroup>

<div>
  Selected: <strong>{selected}</strong>
</div>

<Button
  size="small"
  disabled={selected === values[1]}
  on:click={() => (selected = values[1])}
>
  Set to "{values[1]}"
</Button>

<style>
  div {
    margin: var(--cds-spacing-05) 0;
  }
</style>
```

### Light variant

Use the light variant for light backgrounds.

```svelte
<script>
  import { RadioTile, TileGroup } from "carbon-components-svelte";
</script>

<TileGroup
  legendText="Service pricing tiers"
  name="plan-light"
  selected="standard"
>
  <RadioTile light value="lite">Lite plan</RadioTile>
  <RadioTile light value="standard">Standard plan</RadioTile>
  <RadioTile light value="plus">Plus plan</RadioTile>
</TileGroup>
```

### Disabled state

Disable specific tiles to prevent selection.

```svelte
<script>
  import { RadioTile, TileGroup } from "carbon-components-svelte";
</script>

<TileGroup
  legendText="Service pricing tiers"
  name="plan-disabled"
  selected="standard"
>
  <RadioTile value="lite" disabled>Lite plan</RadioTile>
  <RadioTile value="standard">Standard plan</RadioTile>
  <RadioTile value="plus" disabled>Plus plan</RadioTile>
</TileGroup>
```

---

### Component API

#### `TileGroup` props

| Prop                  | Type             | Description                                                                       | Default     |
| --------------------- | ---------------- | --------------------------------------------------------------------------------- | ----------- |
| `selected` (Reactive) | `T \| undefined` | Specify the selected tile value.                                                  | _undefined_ |
| `disabled`            | `boolean`        | Set to `true` to disable the tile group                                           | `false`     |
| `required`            | `boolean`        | Set to `true` to require the selection of a radio button.                         | _undefined_ |
| `name`                | `string`         | Specify a name attribute for the radio button inputs.                             | _undefined_ |
| `legendText`          | `string`         | Specify the legend text.<br />Alternatively, use the named slot "legendChildren". | `""`        |

#### `TileGroup` slots

| Slot             | Detail                  |
| ---------------- | ----------------------- |
| `default`        | `Record<string, never>` |
| `legendChildren` | `Record<string, never>` |

#### `TileGroup` dispatched events

| Event       | Detail |
| ----------- | ------ |
| `on:select` | `T`    |

#### `TileGroup` $$restProps

`TileGroup` spreads `$$restProps` to the `fieldset` element.

#### `RadioTile` props

| Prop                 | Type      | Description                                              | Default                             |
| -------------------- | --------- | -------------------------------------------------------- | ----------------------------------- |
| `checked` (Reactive) | `boolean` | Set to `true` to check the tile                          | `false`                             |
| `light`              | `boolean` | Set to `true` to enable the light variant                | `false`                             |
| `disabled`           | `boolean` | Set to `true` to disable the tile                        | `false`                             |
| `required`           | `boolean` | Set to `true` to mark the field as required              | `false`                             |
| `value`              | `Value`   | Specify the value of the radio input.                    | `""`                                |
| `tabindex`           | `string`  | Specify the tabindex                                     | `"0"`                               |
| `iconDescription`    | `string`  | Specify the ARIA label for the radio tile checkmark icon | `"Tile checkmark"`                  |
| `id`                 | `string`  | Set an id for the input element                          | `ccs-${Math.random().toString(36)}` |
| `name`               | `string`  | Specify a name attribute for the radio tile input.       | _undefined_                         |

#### `RadioTile` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `RadioTile` forwarded events

| Event           |
| --------------- |
| `on:change`     |
| `on:keydown`    |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `RadioTile` $$restProps

`RadioTile` spreads `$$restProps` to the `label` element.


## RecursiveList

Recursive lists provide a flexible way to render hierarchical data structures
using either unordered or ordered lists. They support nested nodes, links, and
HTML content, making them ideal for displaying complex data hierarchies.

> [!WARNING] HTML content provided via the `html` prop is not sanitized.

### Default

Create a hierarchical list using the `nodes` prop. Each node can contain text,
links, HTML content, and nested nodes.

```svelte
<script>
  import { RecursiveList } from "carbon-components-svelte";

  const nodes = [
    {
      text: "Item 1",
      nodes: [
        {
          text: "Item 1a",
          nodes: [{ html: "<h5>HTML content</h5>" }],
        },
      ],
    },
    {
      text: "Item 2",
      nodes: [
        {
          href: "https://svelte.dev/",
        },
        {
          href: "https://svelte.dev/",
          text: "Link with custom text",
        },
      ],
    },
    {
      text: "Item 3",
    },
  ];
</script>

<RecursiveList {nodes} />
```

### Ordered

Set `type` to `"ordered"` to use numbered lists with proper indentation.

```svelte
<script>
  import { RecursiveList } from "carbon-components-svelte";

  const nodes = [
    {
      text: "Item 1",
      nodes: [
        {
          text: "Item 1a",
          nodes: [{ html: "<h5>HTML content</h5>" }],
        },
      ],
    },
    {
      text: "Item 2",
      nodes: [
        {
          href: "https://svelte.dev/",
        },
        {
          href: "https://svelte.dev/",
          text: "Link with custom text",
        },
      ],
    },
    {
      text: "Item 3",
    },
  ];
</script>

<RecursiveList type="ordered" {nodes} />
```

### Ordered (native styles)

Set `type` to `"ordered-native"` to use browser-native numbering styles.

```svelte
<script>
  import { RecursiveList } from "carbon-components-svelte";

  const nodes = [
    {
      text: "Item 1",
      nodes: [
        {
          text: "Item 1a",
          nodes: [{ html: "<h5>HTML content</h5>" }],
        },
      ],
    },
    {
      text: "Item 2",
      nodes: [
        {
          href: "https://svelte.dev/",
        },
        {
          href: "https://svelte.dev/",
          text: "Link with custom text",
        },
      ],
    },
    {
      text: "Item 3",
    },
  ];
</script>

<RecursiveList type="ordered-native" {nodes} />
```

### Flat data structure

Convert flat data structures to hierarchical arrays using the `toHierarchy`
utility function.

```svelte
<script>
  import { RecursiveList, toHierarchy } from "carbon-components-svelte";

  const nodesFlat = [
    { id: 1, text: "Item 1" },
    { id: 2, text: "Item 1a", pid: 1 },
    { id: 3, html: "<h5>HTML content</h5>", pid: 2 },
    { id: 4, text: "Item 2" },
    { id: 5, href: "https://svelte.dev/", pid: 4 },
    {
      id: 6,
      href: "https://svelte.dev/",
      text: "Link with custom text",
      pid: 4,
    },
    { id: 7, text: "Item 3" },
  ];
</script>

<RecursiveList nodes={toHierarchy(nodesFlat, (node) => node.pid)} />
```

---

### Component API

#### `RecursiveList` props

| Prop    | Type                                           | Description                         | Default       |
| ------- | ---------------------------------------------- | ----------------------------------- | ------------- |
| `nodes` | `ReadonlyArray<Node & { nodes?: Node[] }>`     | Specify the nodes to render.        | `[]`          |
| `type`  | `"unordered" \| "ordered" \| "ordered-native"` | Specify the type of list to render. | `"unordered"` |

#### `RecursiveList` typedefs

```ts
type RecursiveListNode = {
  /** Node text content */
  text?: string;
  /** Node link URL */
  href?: string;
  /** Node HTML content */
  html?: string;
  /** Child nodes */
  nodes?: RecursiveListNode[];
};
```

#### `RecursiveList` $$restProps

`RecursiveList` spreads `$$restProps` to the `ul | ol` element.


## Search

Search provides a flexible search input with support for expandable variants,
different sizes, and custom icons. It includes built-in functionality for
clearing input and handling keyboard events.

### Default

The search input is extra-large by default. Use the `size` prop to choose
between [large](#large-size) and [small](#small-size) variants.

```svelte
<script>
  import { Search } from "carbon-components-svelte";
</script>

<Search />
```

### Default value

Set an initial value using the `value` prop.

```svelte
<script>
  import { Search } from "carbon-components-svelte";
</script>

<Search placeholder="Search catalog..." value="Cloud functions" />
```

### Reactive example

Bind to the `value` prop for reactive updates.

```svelte
<script>
  import { Button, ButtonSet, Search } from "carbon-components-svelte";

  let value = "";
</script>

<Search bind:value />

<div>
  <ButtonSet>
    <Button
      size="small"
      disabled={value === "Cloud functions"}
      on:click={() => (value = "Cloud functions")}
    >
      Set value
    </Button>
    <Button
      kind="ghost"
      size="small"
      disabled={value.length === 0}
      on:click={() => (value = "")}
    >
      Clear value
    </Button>
  </ButtonSet>
</div>

<div>Value: {value}</div>

<style>
  div {
    margin-top: var(--cds-spacing-05);
  }
</style>
```

### Clear event

The `clear` event is dispatched when clicking the clear button or pressing the
Escape key.

```svelte
<script>
  import { Search } from "carbon-components-svelte";
</script>

<Search value="Cloud functions" on:clear={() => console.log("clear")} />

## Expandable variant Enable the expandable variant to show a compact search
icon that expands on focus.
```

```svelte
<script>
  import { Search } from "carbon-components-svelte";

  let expanded = false;
</script>

<Search expandable bind:expanded on:expand on:collapse />

<br />

<strong>Expanded:</strong>
{expanded}
```

### Light variant

Use the light variant for light backgrounds.

```svelte
<script>
  import { Search } from "carbon-components-svelte";
</script>

<Search light />
```

### Large size

Set `size` to `"lg"` for a large search input.

```svelte
<script>
  import { Search } from "carbon-components-svelte";
</script>

<Search size="lg" />
```

### Small size

Set `size` to `"sm"` for a small search input.

```svelte
<script>
  import { Search } from "carbon-components-svelte";
</script>

<Search size="sm" />
```

### Disabled state

Disable the search input using the `disabled` prop.

```svelte
<script>
  import { Search } from "carbon-components-svelte";
</script>

<Search disabled />
```

### Custom icon

Replace the default search icon with a custom one.

```svelte
<script>
  import { Search } from "carbon-components-svelte";
  import Query from "carbon-icons-svelte/lib/Query.svelte";
</script>

<Search icon={Query} />
```

### Skeleton

Display a loading state using the skeleton variant.

```svelte
<script>
  import { Search } from "carbon-components-svelte";
</script>

<Search skeleton />
```

### Skeleton (large)

Display a loading state for the large search variant.

```svelte
<script>
  import { Search } from "carbon-components-svelte";
</script>

<Search size="lg" skeleton />
```

### Skeleton (small)

Display a loading state for the small search variant.

```svelte
<script>
  import { Search } from "carbon-components-svelte";
</script>

<Search size="sm" skeleton />
```

---

### Component API

#### `Search` props

| Prop                   | Type                       | Description                                             | Default                             |
| ---------------------- | -------------------------- | ------------------------------------------------------- | ----------------------------------- |
| `value` (Reactive)     | `any`                      | Specify the value of the search input.                  | `""`                                |
| `expanded` (Reactive)  | `boolean`                  | Set to `true to expand the search input                 | `false`                             |
| `ref` (Reactive)       | `null \| HTMLInputElement` | Obtain a reference to the input HTML element            | `null`                              |
| `size`                 | `"sm" \| "lg" \| "xl"`     | Specify the size of the search input.                   | `"xl"`                              |
| `searchClass`          | `string`                   | Specify the class name passed to the outer div element  | `""`                                |
| `skeleton`             | `boolean`                  | Set to `true` to display the skeleton state             | `false`                             |
| `light`                | `boolean`                  | Set to `true` to enable the light variant               | `false`                             |
| `disabled`             | `boolean`                  | Set to `true` to disable the search input               | `false`                             |
| `expandable`           | `boolean`                  | Set to `true` to enable the expandable variant          | `false`                             |
| `placeholder`          | `string`                   | Specify the `placeholder` attribute of the search input | `"Search..."`                       |
| `autocomplete`         | `"on" \| "off"`            | Specify the `autocomplete` attribute.                   | `"off"`                             |
| `autofocus`            | `boolean`                  | Set to `true` to auto focus the search element          | `false`                             |
| `closeButtonLabelText` | `string`                   | Specify the close button label text                     | `"Clear search input"`              |
| `labelText`            | `string`                   | Specify the label text                                  | `""`                                |
| `icon`                 | `any`                      | Specify the icon to render.                             | `IconSearch`                        |
| `id`                   | `string`                   | Set an id for the input element                         | `ccs-${Math.random().toString(36)}` |

#### `Search` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `labelChildren` | `Record<string, never>` |

#### `Search` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:change`     |
| `on:input`      |
| `on:focus`      |
| `on:blur`       |
| `on:keydown`    |
| `on:keyup`      |
| `on:paste`      |

#### `Search` dispatched events

| Event         | Detail |
| ------------- | ------ |
| `on:expand`   | `null` |
| `on:collapse` | `null` |
| `on:clear`    | `null` |

#### `Search` $$restProps

`Search` spreads `$$restProps` to the `input` element.


## Select

Selects provide a dropdown menu for selecting a single option from a list. They
support various states, sizes, and include built-in validation and helper text.

### Default

Create a basic select menu with select item components. The first item's value
is used as the default if `selected` is not set.

```svelte
<script>
  import { Select, SelectItem } from "carbon-components-svelte";
</script>

<Select
  labelText="Carbon theme"
  on:change={(e) => console.log("value", e.target.value)}
>
  <SelectItem value="white" />
  <SelectItem value="g10" />
  <SelectItem value="g80" />
  <SelectItem value="g90" />
  <SelectItem value="g100" />
</Select>
```

### Custom item text

Use the `text` prop to customize the display text of each option.

```svelte
<script>
  import { Select, SelectItem } from "carbon-components-svelte";
</script>

<Select
  labelText="Carbon theme"
  on:change={(e) => console.log("value", e.target.value)}
>
  <SelectItem value="white" text="White" />
  <SelectItem value="g10" text="Gray 10" />
  <SelectItem value="g80" text="Gray 80" />
  <SelectItem value="g90" text="Gray 90" />
  <SelectItem value="g100" text="Gray 100" />
</Select>
```

### Initial selected value

Set the initial selection using the `selected` prop.

```svelte
<script>
  import { Select, SelectItem } from "carbon-components-svelte";
</script>

<Select
  labelText="Carbon theme"
  selected="g10"
  on:change={(e) => console.log("value", e.target.value)}
>
  <SelectItem value="white" text="White" />
  <SelectItem value="g10" text="Gray 10" />
  <SelectItem value="g80" text="Gray 80" />
  <SelectItem value="g90" text="Gray 90" />
  <SelectItem value="g100" text="Gray 100" />
</Select>
```

### Reactive example

The `selected` prop supports two-way binding for reactive updates.

```svelte
<script>
  import { Button, Select, SelectItem } from "carbon-components-svelte";

  let selected = "g10";
</script>

<Select labelText="Carbon theme" bind:selected>
  <SelectItem value="white" text="White" />
  <SelectItem value="g10" text="Gray 10" />
  <SelectItem value="g80" text="Gray 80" />
  <SelectItem value="g90" text="Gray 90" />
  <SelectItem value="g100" text="Gray 100" />
</Select>

<div style="margin: var(--cds-layout-01) 0">
  Selected: <strong>{selected}</strong>
</div>

<Button disabled={selected === "g90"} on:click={() => (selected = "g90")}>
  Set to "g90"
</Button>
```

### Helper text

Add descriptive text below the select menu.

```svelte
<script>
  import { Select, SelectItem } from "carbon-components-svelte";
</script>

<Select
  helperText="Carbon offers 4 themes (2 light, 3 dark)"
  labelText="Carbon theme"
  selected="g10"
>
  <SelectItem value="white" text="White" />
  <SelectItem value="g10" text="Gray 10" />
  <SelectItem value="g80" text="Gray 80" />
  <SelectItem value="g90" text="Gray 90" />
  <SelectItem value="g100" text="Gray 100" />
</Select>
```

### Hidden label

Visually hide the label while maintaining accessibility.

```svelte
<script>
  import { Select, SelectItem } from "carbon-components-svelte";
</script>

<Select hideLabel labelText="Carbon theme" selected="g10">
  <SelectItem value="white" text="White" />
  <SelectItem value="g10" text="Gray 10" />
  <SelectItem value="g80" text="Gray 80" />
  <SelectItem value="g90" text="Gray 90" />
  <SelectItem value="g100" text="Gray 100" />
</Select>
```

### Item groups

Group related options using select item group components.

```svelte
<script>
  import {
    Select,
    SelectItem,
    SelectItemGroup,
  } from "carbon-components-svelte";
</script>

<Select labelText="Carbon theme" selected="0">
  <SelectItem value="0" text="Select a theme" disabled hidden />
  <SelectItemGroup label="Light theme">
    <SelectItem value="white" text="White" />
    <SelectItem value="g10" text="Gray 10" />
  </SelectItemGroup>
  <SelectItemGroup label="Dark theme">
    <SelectItem value="g80" text="Gray 80" />
    <SelectItem value="g90" text="Gray 90" />
    <SelectItem value="g100" text="Gray 100" />
  </SelectItemGroup>
</Select>
```

### Small size

Use the small size variant for compact layouts.

```svelte
<script>
  import { Select, SelectItem } from "carbon-components-svelte";
</script>

<Select size="sm" labelText="Carbon theme" selected="g10">
  <SelectItem value="white" text="White" />
  <SelectItem value="g10" text="Gray 10" />
  <SelectItem value="g80" text="Gray 80" />
  <SelectItem value="g90" text="Gray 90" />
  <SelectItem value="g100" text="Gray 100" />
</Select>
```

### Extra-large size

Use the extra-large size variant for prominent selections.

```svelte
<script>
  import { Select, SelectItem } from "carbon-components-svelte";
</script>

<Select size="xl" labelText="Carbon theme" selected="g10">
  <SelectItem value="white" text="White" />
  <SelectItem value="g10" text="Gray 10" />
  <SelectItem value="g80" text="Gray 80" />
  <SelectItem value="g90" text="Gray 90" />
  <SelectItem value="g100" text="Gray 100" />
</Select>
```

### Inline variant

Use the inline variant for horizontal layouts.

```svelte
<script>
  import { Select, SelectItem } from "carbon-components-svelte";
</script>

<Select inline labelText="Carbon theme" selected="g10">
  <SelectItem value="white" text="White" />
  <SelectItem value="g10" text="Gray 10" />
  <SelectItem value="g80" text="Gray 80" />
  <SelectItem value="g90" text="Gray 90" />
  <SelectItem value="g100" text="Gray 100" />
</Select>
```

### Light variant

Use the light variant for light backgrounds.

```svelte
<script>
  import { Select, SelectItem } from "carbon-components-svelte";
</script>

<Select light labelText="Carbon theme" selected="g10">
  <SelectItem value="white" text="White" />
  <SelectItem value="g10" text="Gray 10" />
  <SelectItem value="g80" text="Gray 80" />
  <SelectItem value="g90" text="Gray 90" />
  <SelectItem value="g100" text="Gray 100" />
</Select>
```

### Invalid state

Show validation errors using the invalid state.

```svelte
<script>
  import { Select, SelectItem } from "carbon-components-svelte";
</script>

<Select
  invalid
  invalidText="Theme must be a dark variant"
  labelText="Carbon theme"
  selected="g10"
>
  <SelectItem value="white" text="White" />
  <SelectItem value="g10" text="Gray 10" />
  <SelectItem value="g80" text="Gray 80" />
  <SelectItem value="g90" text="Gray 90" />
  <SelectItem value="g100" text="Gray 100" />
</Select>
```

### Warning state

Show warnings using the warning state.

```svelte
<script>
  import { Select, SelectItem } from "carbon-components-svelte";
</script>

<Select
  warn
  warnText="The selected theme will not be persisted"
  labelText="Carbon theme"
  selected="g10"
>
  <SelectItem value="white" text="White" />
  <SelectItem value="g10" text="Gray 10" />
  <SelectItem value="g80" text="Gray 80" />
  <SelectItem value="g90" text="Gray 90" />
  <SelectItem value="g100" text="Gray 100" />
</Select>
```

### Disabled state

Disable the select menu to prevent interaction.

```svelte
<script>
  import { Select, SelectItem } from "carbon-components-svelte";
</script>

<Select disabled labelText="Carbon theme" selected="g10">
  <SelectItem value="white" text="White" />
  <SelectItem value="g10" text="Gray 10" />
  <SelectItem value="g80" text="Gray 80" />
  <SelectItem value="g90" text="Gray 90" />
  <SelectItem value="g100" text="Gray 100" />
</Select>
```

### Skeleton

Display a loading state using the skeleton variant.

```svelte
<script>
  import { SelectSkeleton } from "carbon-components-svelte";
</script>

<SelectSkeleton />
```

### Skeleton without label

Display a loading state for the select without a visible label.

```svelte
<script>
  import { SelectSkeleton } from "carbon-components-svelte";
</script>

<SelectSkeleton hideLabel />
```

---

### Component API

#### `Select` props

| Prop                  | Type                        | Description                                      | Default                             |
| --------------------- | --------------------------- | ------------------------------------------------ | ----------------------------------- |
| `selected` (Reactive) | `Value \| undefined`        | Specify the selected item value.                 | _undefined_                         |
| `ref` (Reactive)      | `null \| HTMLSelectElement` | Obtain a reference to the select HTML element    | `null`                              |
| `size`                | `"sm" \| "xl"`              | Set the size of the select input.                | _undefined_                         |
| `inline`              | `boolean`                   | Set to `true` to use the inline variant          | `false`                             |
| `light`               | `boolean`                   | Set to `true` to enable the light variant        | `false`                             |
| `disabled`            | `boolean`                   | Set to `true` to disable the select element      | `false`                             |
| `id`                  | `string`                    | Set an id for the select element                 | `ccs-${Math.random().toString(36)}` |
| `name`                | `string`                    | Specify a name attribute for the select element. | _undefined_                         |
| `invalid`             | `boolean`                   | Set to `true` to indicate an invalid state       | `false`                             |
| `invalidText`         | `string`                    | Specify the invalid state text                   | `""`                                |
| `warn`                | `boolean`                   | Set to `true` to indicate a warning state        | `false`                             |
| `warnText`            | `string`                    | Specify the warning state text                   | `""`                                |
| `helperText`          | `string`                    | Specify the helper text                          | `""`                                |
| `noLabel`             | `boolean`                   | Set to `true` to not render a label              | `false`                             |
| `labelText`           | `string`                    | Specify the label text                           | `""`                                |
| `hideLabel`           | `boolean`                   | Set to `true` to visually hide the label text    | `false`                             |
| `required`            | `boolean`                   | Set to `true` to mark the field as required      | `false`                             |

#### `Select` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `default`       | `Record<string, never>` |
| `labelChildren` | `Record<string, never>` |

#### `Select` forwarded events

| Event       |
| ----------- |
| `on:change` |
| `on:input`  |
| `on:focus`  |
| `on:blur`   |

#### `Select` dispatched events

| Event       | Detail  | Description         |
| ----------- | ------- | ------------------- |
| `on:update` | `Value` | The selected value. |

#### `Select` $$restProps

`Select` spreads `$$restProps` to the `select` element.

#### `SelectItem` props

| Prop       | Type      | Description                                                                         | Default     |
| ---------- | --------- | ----------------------------------------------------------------------------------- | ----------- |
| `value`    | `Value`   | Specify the option value.                                                           | `""`        |
| `text`     | `string`  | Specify the option text.<br />If not specified, the value will be used as the text. | _undefined_ |
| `hidden`   | `boolean` | Set to `true` to hide the option                                                    | `false`     |
| `disabled` | `boolean` | Set to `true` to disable the option                                                 | `false`     |
| `class`    | `string`  | Specify the class of the `option` element.                                          | _undefined_ |
| `style`    | `string`  | Specify the style of the `option` element.                                          | _undefined_ |

#### `SelectItemGroup` props

| Prop       | Type      | Description                                         | Default           |
| ---------- | --------- | --------------------------------------------------- | ----------------- |
| `disabled` | `boolean` | Set to `true` to disable the optgroup element       | `false`           |
| `label`    | `string`  | Specify the label attribute of the optgroup element | `"Provide label"` |

#### `SelectItemGroup` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `SelectItemGroup` $$restProps

`SelectItemGroup` spreads `$$restProps` to the `optgroup` element.

#### `SelectSkeleton` props

| Prop        | Type      | Description                          | Default |
| ----------- | --------- | ------------------------------------ | ------- |
| `hideLabel` | `boolean` | Set to `true` to hide the label text | `false` |

#### `SelectSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `SelectSkeleton` $$restProps

`SelectSkeleton` spreads `$$restProps` to the `div` element.


## SelectableTile

Selectable tiles provide a tile-based selection interface that allows users to
select multiple options. They support various states and include built-in
keyboard navigation and accessibility features.

### Multi-selectable tiles

Group multiple selectable tiles together for multi-selection scenarios.

```svelte
<script>
  import {
    SelectableTile,
    SelectableTileGroup,
  } from "carbon-components-svelte";
</script>

<SelectableTileGroup
  legendText="Select options"
  name="options"
  selected={["option1", "option2"]}
>
  <SelectableTile value="option1">Multi-select Tile</SelectableTile>
  <SelectableTile value="option2">Multi-select Tile</SelectableTile>
  <SelectableTile value="option3">Multi-select Tile</SelectableTile>
</SelectableTileGroup>
```

### Reactive (one-way binding)

Update the selected values using the `select` and `deselect` events.

```svelte
<script>
  import {
    SelectableTile,
    SelectableTileGroup,
  } from "carbon-components-svelte";

  const values = ["Lite plan", "Standard plan", "Plus plan"];

  let selected = [values[0], values[1]];
</script>

<SelectableTileGroup
  legendText="Service pricing tiers"
  name="plan"
  on:select={({ detail }) => (selected = [...selected, detail])}
  on:deselect={({ detail }) =>
    (selected = selected.filter((v) => v !== detail))}
>
  {#each values as value}
    <SelectableTile {value} selected={selected.includes(value)}>
      {value}
    </SelectableTile>
  {/each}
</SelectableTileGroup>

<br />

Selected: <strong>{selected.join(", ") || "None"}</strong>
```

### Reactive (two-way binding)

Bind to the `selected` prop for simpler state management.

```svelte
<script>
  import {
    Button,
    SelectableTile,
    SelectableTileGroup,
  } from "carbon-components-svelte";

  const values = ["Lite plan", "Standard plan", "Plus plan"];

  let selected = [values[0], values[1]];
</script>

<SelectableTileGroup
  legendText="Service pricing tiers"
  name="plan"
  bind:selected
>
  {#each values as value}
    <SelectableTile {value}>{value}</SelectableTile>
  {/each}
</SelectableTileGroup>

<div>
  Selected: <strong>{selected.join(", ") || "None"}</strong>
</div>

<Button
  size="small"
  disabled={selected.length === 1 && selected[0] === values[1]}
  on:click={() => (selected = [values[1]])}
>
  Set to "{values[1]}" only
</Button>

<style>
  div {
    margin: var(--cds-spacing-05) 0;
  }
</style>
```

### Light variant

Use the light variant for light backgrounds.

```svelte
<script>
  import {
    SelectableTile,
    SelectableTileGroup,
  } from "carbon-components-svelte";
</script>

<SelectableTileGroup
  legendText="Select options"
  name="options-light"
  selected={["option1", "option2"]}
>
  <SelectableTile light value="option1">Multi-select Tile</SelectableTile>
  <SelectableTile light value="option2">Multi-select Tile</SelectableTile>
  <SelectableTile light value="option3">Multi-select Tile</SelectableTile>
</SelectableTileGroup>
```

### Disabled state

Disable specific tiles to prevent interaction.

```svelte
<script>
  import {
    SelectableTile,
    SelectableTileGroup,
  } from "carbon-components-svelte";
</script>

<SelectableTileGroup
  legendText="Select options"
  name="options-disabled"
  selected={["option1"]}
>
  <SelectableTile value="option1">Multi-select Tile</SelectableTile>
  <SelectableTile disabled value="option2">Multi-select Tile</SelectableTile>
  <SelectableTile disabled value="option3">Multi-select Tile</SelectableTile>
</SelectableTileGroup>
```

---

### Component API

#### `SelectableTileGroup` props

| Prop                  | Type                  | Description                                                                       | Default     |
| --------------------- | --------------------- | --------------------------------------------------------------------------------- | ----------- |
| `selected` (Reactive) | `T[]`                 | Specify the selected tile values.                                                 | `[]`        |
| `disabled`            | `boolean`             | Set to `true` to disable the tile group                                           | `false`     |
| `name`                | `string \| undefined` | Specify a name attribute for the checkbox inputs.                                 | _undefined_ |
| `legendText`          | `string`              | Specify the legend text.<br />Alternatively, use the named slot "legendChildren". | `""`        |

#### `SelectableTileGroup` slots

| Slot             | Detail                  |
| ---------------- | ----------------------- |
| `default`        | `Record<string, never>` |
| `legendChildren` | `Record<string, never>` |

#### `SelectableTileGroup` dispatched events

| Event         | Detail |
| ------------- | ------ |
| `on:select`   | `T`    |
| `on:deselect` | `T`    |

#### `SelectableTileGroup` $$restProps

`SelectableTileGroup` spreads `$$restProps` to the `fieldset` element.

#### `SelectableTile` props

| Prop                  | Type                       | Description                                                   | Default                             |
| --------------------- | -------------------------- | ------------------------------------------------------------- | ----------------------------------- |
| `selected` (Reactive) | `boolean`                  | Set to `true` to select the tile                              | `false`                             |
| `ref` (Reactive)      | `null \| HTMLInputElement` | Obtain a reference to the input HTML element                  | `null`                              |
| `light`               | `boolean`                  | Set to `true` to enable the light variant                     | `false`                             |
| `disabled`            | `boolean`                  | Set to `true` to disable the tile                             | `false`                             |
| `title`               | `string`                   | Specify the title of the selectable tile                      | `"title"`                           |
| `value`               | `string`                   | Specify the value of the selectable tile                      | `"value"`                           |
| `tabindex`            | `string`                   | Specify the tabindex                                          | `"0"`                               |
| `iconDescription`     | `string`                   | Specify the ARIA label for the selectable tile checkmark icon | `"Tile checkmark"`                  |
| `id`                  | `string`                   | Set an id for the input element                               | `ccs-${Math.random().toString(36)}` |
| `name`                | `string`                   | Specify a name attribute for the input.                       | `""`                                |

#### `SelectableTile` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `SelectableTile` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:keydown`    |

#### `SelectableTile` dispatched events

| Event         | Detail   |
| ------------- | -------- |
| `on:select`   | `string` |
| `on:deselect` | `string` |

#### `SelectableTile` $$restProps

`SelectableTile` spreads `$$restProps` to the `label` element.


## SkeletonPlaceholder

Skeleton placeholders provide a loading state placeholder that can be used to
indicate content is being loaded. They support custom sizing and forward mouse
events for interactive loading states.

### Default

Create a basic skeleton placeholder with default styling.

```svelte
<script>
  import { SkeletonPlaceholder } from "carbon-components-svelte";
</script>

<SkeletonPlaceholder />
```

### Custom size

Specify custom dimensions using the `style` prop.

```svelte
<script>
  import { SkeletonPlaceholder } from "carbon-components-svelte";
</script>

<SkeletonPlaceholder style="height: 12rem; width: 12rem;" />
```

---

### Component API

#### `SkeletonPlaceholder` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `SkeletonPlaceholder` $$restProps

`SkeletonPlaceholder` spreads `$$restProps` to the `div` element.


## SkeletonText

Skeleton text provides a loading state for text content with support for
different sizes and line counts. It's commonly used to indicate that text
content is being loaded.

### Default

Create a basic skeleton text with default styling.

```svelte
<script>
  import { SkeletonText } from "carbon-components-svelte";
</script>

<SkeletonText />
```

### Heading variant

Use the heading variant for larger text placeholders.

```svelte
<script>
  import { SkeletonText } from "carbon-components-svelte";
</script>

<SkeletonText heading />
```

### Paragraph variant

Use the paragraph variant for multi-line text placeholders.

```svelte
<script>
  import { SkeletonText } from "carbon-components-svelte";
</script>

<SkeletonText paragraph />
```

### Paragraph with custom line count

Specify the number of lines to render using the `lines` prop.

```svelte
<script>
  import { SkeletonText } from "carbon-components-svelte";
</script>

<SkeletonText paragraph lines={8} />
```

### Paragraph with max width

Set a custom width for the text placeholder using the `width` prop.

```svelte
<script>
  import { SkeletonText } from "carbon-components-svelte";
</script>

<SkeletonText paragraph width="50%" />
```

---

### Component API

#### `SkeletonText` props

| Prop        | Type      | Description                                     | Default  |
| ----------- | --------- | ----------------------------------------------- | -------- |
| `lines`     | `number`  | Specify the number of lines to render           | `3`      |
| `heading`   | `boolean` | Set to `true` to use the heading size variant   | `false`  |
| `paragraph` | `boolean` | Set to `true` to use the paragraph size variant | `false`  |
| `width`     | `string`  | Specify the width of the text (% or px)         | `"100%"` |

#### `SkeletonText` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `SkeletonText` $$restProps

`SkeletonText` spreads `$$restProps` to the `div` element.


## Slider

Sliders provide a visual way to select a value from a range. They support
keyboard navigation, custom ranges, step values, and various states.

### Default

Create a basic slider with a label and default range (0-100).

```svelte
<script>
  import { Slider } from "carbon-components-svelte";
</script>

<Slider labelText="Instances" value={0} />
```

### Full width

Set `fullWidth` to `true` for the slider to span the full width of its
containing element.

```svelte
<script>
  import { Slider } from "carbon-components-svelte";
</script>

<Slider labelText="Instances" fullWidth value={0} />
```

### Hidden label

Visually hide the label while maintaining accessibility.

```svelte
<script>
  import { Slider } from "carbon-components-svelte";
</script>

<Slider labelText="Instances" hideLabel value={0} />
```

### Hidden text input

Hide the text input while keeping the slider functionality.

```svelte
<script>
  import { Slider } from "carbon-components-svelte";
</script>

<Slider labelText="Instances" hideTextInput value={0} />
```

### Custom minimum, maximum values

Set custom range values and labels.

```svelte
<script>
  import { Slider } from "carbon-components-svelte";
</script>

<Slider
  labelText="Runtime memory (MB)"
  min={10}
  max={990}
  maxLabel="990 MB"
  value={100}
/>
```

### Custom step value

Specify the step value for more precise control.

```svelte
<script>
  import { Slider } from "carbon-components-svelte";
</script>

<Slider
  labelText="Runtime memory (MB)"
  min={10}
  max={990}
  maxLabel="990 MB"
  value={100}
  step={10}
/>
```

### Light variant

Use the light variant for light backgrounds.

```svelte
<script>
  import { Slider } from "carbon-components-svelte";
</script>

<Slider
  light
  labelText="Runtime memory (MB)"
  min={10}
  max={990}
  maxLabel="990 MB"
  value={100}
  step={10}
/>
```

### Invalid state

Indicate an invalid state with the `invalid` prop. The invalid state takes
precedence over the [warning state](#warning-state) when both are set.

```svelte
<script>
  import { Slider } from "carbon-components-svelte";
</script>

<Slider
  invalid
  invalidText="Value must be a multiple of 10"
  labelText="Runtime memory (MB)"
  min={10}
  max={990}
  maxLabel="990 MB"
  value={105}
  step={10}
/>
```

### Warning state

Indicate a warning state with the `warn` prop. The warning icon appears next to
the input field, and a warning message is displayed below the slider.

```svelte
<script>
  import { Slider } from "carbon-components-svelte";
</script>

<Slider
  warn
  warnText="Value must be an increment of 5"
  labelText="Slider (must be an increment of 5)"
  min={0}
  max={100}
  value={51}
  step={5}
/>
```

### Disabled state

Disable the slider to prevent interaction.

```svelte
<script>
  import { Slider } from "carbon-components-svelte";
</script>

<Slider
  disabled
  labelText="Runtime memory (MB)"
  min={10}
  max={990}
  maxLabel="990 MB"
  value={100}
  step={10}
/>
```

### Read-only state

Set the slider to read-only to display a value without allowing changes.

```svelte
<script>
  import { Slider } from "carbon-components-svelte";
</script>

<Slider
  readonly
  labelText="Runtime memory (MB)"
  min={10}
  max={990}
  maxLabel="990 MB"
  value={100}
  step={10}
/>
```

### Skeleton

Show a loading state with the skeleton variant.

```svelte
<script>
  import { SliderSkeleton } from "carbon-components-svelte";
</script>

<SliderSkeleton />
```

### Skeleton without label

Show a loading state without a label.

```svelte
<script>
  import { SliderSkeleton } from "carbon-components-svelte";
</script>

<SliderSkeleton hideLabel />
```

---

### Component API

#### `Slider` props

| Prop               | Type                     | Description                                                                         | Default                             |
| ------------------ | ------------------------ | ----------------------------------------------------------------------------------- | ----------------------------------- |
| `value` (Reactive) | `number`                 | Specify the value of the slider                                                     | `0`                                 |
| `ref` (Reactive)   | `null \| HTMLDivElement` | Obtain a reference to the HTML element                                              | `null`                              |
| `max`              | `number`                 | Set the maximum slider value                                                        | `100`                               |
| `maxLabel`         | `string`                 | Specify the label for the max value                                                 | `""`                                |
| `min`              | `number`                 | Set the minimum slider value                                                        | `0`                                 |
| `minLabel`         | `string`                 | Specify the label for the min value                                                 | `""`                                |
| `step`             | `number`                 | Set the step value                                                                  | `1`                                 |
| `stepMultiplier`   | `number`                 | Set the step multiplier value                                                       | `4`                                 |
| `required`         | `boolean`                | Set to `true` to require a value                                                    | `false`                             |
| `inputType`        | `string`                 | Specify the input type                                                              | `"number"`                          |
| `disabled`         | `boolean`                | Set to `true` to disable the slider                                                 | `false`                             |
| `readonly`         | `boolean`                | Set to `true` to use the read-only variant                                          | `false`                             |
| `light`            | `boolean`                | Set to `true` to enable the light variant                                           | `false`                             |
| `hideTextInput`    | `boolean`                | Set to `true` to hide the text input                                                | `false`                             |
| `fullWidth`        | `boolean`                | Set to `true` for the slider to span<br />the full width of its containing element. | `false`                             |
| `id`               | `string`                 | Set an id for the slider div element                                                | `ccs-${Math.random().toString(36)}` |
| `invalid`          | `boolean`                | Set to `true` to indicate an invalid state                                          | `false`                             |
| `invalidText`      | `string`                 | Specify the invalid state text                                                      | `""`                                |
| `warn`             | `boolean`                | Set to `true` to indicate a warning state                                           | `false`                             |
| `warnText`         | `string`                 | Specify the warning state text                                                      | `""`                                |
| `labelText`        | `string`                 | Specify the label text.<br />Alternatively, use the "labelChildren" slot.           | `""`                                |
| `hideLabel`        | `boolean`                | Set to `true` to visually hide the label text                                       | `false`                             |
| `name`             | `string`                 | Set a name for the slider element                                                   | `""`                                |

#### `Slider` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `labelChildren` | `Record<string, never>` |

#### `Slider` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `Slider` dispatched events

| Event       | Detail   |
| ----------- | -------- |
| `on:change` | `number` |
| `on:input`  | `number` |

#### `Slider` $$restProps

`Slider` spreads `$$restProps` to the `div` element.

#### `SliderSkeleton` props

| Prop        | Type      | Description                          | Default |
| ----------- | --------- | ------------------------------------ | ------- |
| `hideLabel` | `boolean` | Set to `true` to hide the label text | `false` |

#### `SliderSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `SliderSkeleton` $$restProps

`SliderSkeleton` spreads `$$restProps` to the `div` element.


## Stack

Stacks are utility components that can be used to create a stack of elements
with a consistent gap between them. They support both vertical and horizontal
orientations.

It uses layout tokens from the Carbon Design System to define the gap between
elements. The default gap is `1`, which is equivalent to `0.125rem` (`2px`).

The `gap` scale can be set from `0` to `13`:

- **0**: 0 (no gap)
- **1**: 0.125rem (2px)
- **2**: 0.25rem (4px)
- **3**: 0.5rem (8px)
- **4**: 0.75rem (12px)
- **5**: 1rem (16px)
- **6**: 1.5rem (24px)
- **7**: 2rem (32px)
- **8**: 2.5rem (40px)
- **9**: 3rem (48px)
- **10**: 4rem (64px)
- **11**: 5rem (80px)
- **12**: 6rem (96px)
- **13**: 10rem (160px)

Alternatively, you can specify an arbitrary `gap` value (e.g., `200px`). You can
also set `gap` to `0` to omit any gap class.

### Vertical (gap 0)

Setting `gap` to `0` omits any gap class, resulting in no spacing between items.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack gap={0}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (gap 1)

By default, the stack has a vertical orientation and a gap scale of `1` (2px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (gap 2)

Gap scale of `2` (4px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack gap={2}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (gap 3)

Gap scale of `3` (8px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack gap={3}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (gap 4)

Gap scale of `4` (12px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack gap={4}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (gap 5)

Gap scale of `5` (16px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack gap={5}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (gap 6)

Gap scale of `6` (24px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack gap={6}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (gap 7)

Gap scale of `7` (32px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack gap={7}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (gap 8)

Gap scale of `8` (40px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack gap={8}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (gap 9)

Gap scale of `9` (48px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack gap={9}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (gap 10)

Gap scale of `10` (64px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack gap={10}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (gap 11)

Gap scale of `11` (80px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack gap={11}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (gap 12)

Gap scale of `12` (96px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack gap={12}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (gap 13)

Gap scale of `13` (160px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack gap={13}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical inline

Set `inline` to `true` to use `display: inline-flex` instead of `display: flex`.
This causes the stack to shrink to fit its content width instead of spanning the
full width of its container.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack inline gap={3}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (custom value)

Use an arbitrary gap value (e.g., 22px) instead of the scale.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack gap="22px">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Vertical (custom element)

By default, the stack uses a `div` element. You can specify a different element
using the `tag` prop.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack tag="ul" gap={3}>
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
</Stack>
```

### Horizontal (gap 0)

Setting `gap` to `0` omits any gap class, resulting in no spacing between items.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" gap={0}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (gap 1)

Set the `orientation` prop to `horizontal` to create a horizontal stack. Gap
scale of `1` (2px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (gap 2)

Gap scale of `2` (4px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" gap={2}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (gap 3)

Gap scale of `3` (8px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" gap={3}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (gap 4)

Gap scale of `4` (12px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" gap={4}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (gap 5)

Gap scale of `5` (16px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" gap={5}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (gap 6)

Gap scale of `6` (24px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" gap={6}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (gap 7)

Gap scale of `7` (32px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" gap={7}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (gap 8)

Gap scale of `8` (40px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" gap={8}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (gap 9)

Gap scale of `9` (48px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" gap={9}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (gap 10)

Gap scale of `10` (64px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" gap={10}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (gap 11)

Gap scale of `11` (80px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" gap={11}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (gap 12)

Gap scale of `12` (96px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" gap={12}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (gap 13)

Gap scale of `13` (160px).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" gap={13}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (custom value)

Use an arbitrary gap value (e.g., 22px) instead of the scale.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" gap="22px">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal (custom element)

By default, the stack uses a `div` element. You can specify a different element
using the `tag` prop.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" tag="ul" gap={3}>
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
</Stack>
```

### Horizontal align start

Aligns items to the start of the cross-axis. For horizontal stacks, this aligns
items to the top. The default `align` value is `"stretch"`, which stretches
items to fill the container height.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" align="start" gap={2} style="height: 120px">
  <div style="height: 40px">Short</div>
  <div style="height: 80px">Taller item</div>
  <div style="height: 50px">Short</div>
</Stack>
```

### Horizontal align center

Aligns items to the center of the cross-axis. For horizontal stacks, this
centers items vertically.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" align="center" gap={2} style="height: 120px">
  <div style="height: 40px; min-width: 60px">Short</div>
  <div style="height: 80px; min-width: 80px">Taller item</div>
  <div style="height: 50px; min-width: 60px">Short</div>
</Stack>
```

### Horizontal align end

Aligns items to the end of the cross-axis. For horizontal stacks, this aligns
items to the bottom.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" align="end" gap={2} style="height: 120px">
  <div style="height: 40px">Short</div>
  <div style="height: 80px">Taller item</div>
  <div style="height: 50px">Short</div>
</Stack>
```

### Horizontal align baseline

Aligns items along their baseline.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" align="baseline" gap={2}>
  <div style="font-size: 2rem; line-height: 1">Large</div>
  <div style="font-size: 1rem; line-height: 1">Medium</div>
  <div style="font-size: 0.75rem; line-height: 1">Small</div>
</Stack>
```

### Vertical align start

For vertical stacks, `align="start"` aligns items to the start of the cross-axis
(left).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="vertical" align="start" gap={2}>
  <div style="width: 80px">Narrow</div>
  <div style="width: 150px">Wider item</div>
  <div style="width: 100px">Medium</div>
</Stack>
```

### Vertical align center

For vertical stacks, `align="center"` centers items horizontally.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="vertical" align="center" gap={2}>
  <div style="width: 80px">Narrow</div>
  <div style="width: 150px">Wider item</div>
  <div style="width: 100px">Medium</div>
</Stack>
```

### Vertical align end

For vertical stacks, `align="end"` aligns items to the end of the cross-axis
(right).

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="vertical" align="end" gap={2}>
  <div style="width: 80px">Narrow</div>
  <div style="width: 150px">Wider item</div>
  <div style="width: 100px">Medium</div>
</Stack>
```

### Horizontal justify center

Aligns items to the center of the main axis. The default `justify` value is
`"start"`, which aligns items to the start of the main axis.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" justify="center" gap={2}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal justify end

Aligns items to the end of the main axis.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" justify="end" gap={2}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal justify space-between

Distributes items evenly with the first item at the start and the last item at
the end.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" justify="space-between">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal justify space-around

Distributes items evenly with equal space around each item.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" justify="space-around">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Horizontal justify space-evenly

Distributes items evenly with equal space between each item.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack orientation="horizontal" justify="space-evenly">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Stack>
```

### Combined align and justify

Use both `align` and `justify` to center content on both axes.

```svelte
<script>
  import { Stack } from "carbon-components-svelte";
</script>

<Stack align="center" justify="center" gap={4}>
  <div>Centered</div>
  <div>Content</div>
</Stack>
```

---

### Component API

#### `Stack` props

| Prop          | Type                                                                                  | Description                                                                                                                                                                                                                               | Default      |
| ------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `gap`         | `StackScale \| string`                                                                | Specify the gap between items in the stack.<br />The scale maps to Carbon layout values.<br />Use 0 to omit any gap class.<br />Alternatively, specify a custom value (e.g., "200px" or "1.5rem").<br />Custom values _must_ be a string. | `1`          |
| `orientation` | `"vertical" \| "horizontal"`                                                          | Specify the orientation of the stack.                                                                                                                                                                                                     | `"vertical"` |
| `align`       | `"start" \| "center" \| "end" \| "stretch" \| "baseline"`                             | Specify the cross-axis alignment of items in the stack.                                                                                                                                                                                   | `"stretch"`  |
| `justify`     | `"start" \| "center" \| "end" \| "space-between" \| "space-around" \| "space-evenly"` | Specify the main-axis alignment of items in the stack.                                                                                                                                                                                    | `"start"`    |
| `inline`      | `boolean`                                                                             | Set to `true` to use `display: inline-flex` instead of `display: flex`.                                                                                                                                                                   | `false`      |
| `tag`         | `keyof HTMLElementTagNameMap`                                                         | Specify the tag name.                                                                                                                                                                                                                     | `"div"`      |

#### `Stack` typedefs

```ts
type StackScale = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
```

#### `Stack` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `Stack` $$restProps

`Stack` spreads `$$restProps` to the `svelte:element` element.


## StructuredList

Structured lists provide a semantic way to display tabular data with support for
selection, keyboard navigation, and various layout options.

### Default

Display a basic structured list with headers and rows by default.

```svelte
<script>
  import {
    StructuredList,
    StructuredListBody,
    StructuredListCell,
    StructuredListHead,
    StructuredListRow,
  } from "carbon-components-svelte";
</script>

<StructuredList>
  <StructuredListHead>
    <StructuredListRow head>
      <StructuredListCell head>Column A</StructuredListCell>
      <StructuredListCell head>Column B</StructuredListCell>
      <StructuredListCell head>Column C</StructuredListCell>
    </StructuredListRow>
  </StructuredListHead>
  <StructuredListBody>
    <StructuredListRow>
      <StructuredListCell>Row 1</StructuredListCell>
      <StructuredListCell>Row 1</StructuredListCell>
      <StructuredListCell>Row 1</StructuredListCell>
    </StructuredListRow>
    <StructuredListRow>
      <StructuredListCell>Row 2</StructuredListCell>
      <StructuredListCell>Row 2</StructuredListCell>
      <StructuredListCell>Row 2</StructuredListCell>
    </StructuredListRow>
    <StructuredListRow>
      <StructuredListCell>Row 3</StructuredListCell>
      <StructuredListCell>Row 3</StructuredListCell>
      <StructuredListCell>Row 3</StructuredListCell>
    </StructuredListRow>
  </StructuredListBody>
</StructuredList>
```

### Condensed variant

Use the condensed variant for more compact rows.

```svelte
<script>
  import {
    StructuredList,
    StructuredListBody,
    StructuredListCell,
    StructuredListHead,
    StructuredListRow,
  } from "carbon-components-svelte";
</script>

<StructuredList condensed>
  <StructuredListHead>
    <StructuredListRow head>
      <StructuredListCell head>Column A</StructuredListCell>
      <StructuredListCell head>Column B</StructuredListCell>
      <StructuredListCell head>Column C</StructuredListCell>
    </StructuredListRow>
  </StructuredListHead>
  <StructuredListBody>
    <StructuredListRow>
      <StructuredListCell>Row 1</StructuredListCell>
      <StructuredListCell>Row 1</StructuredListCell>
      <StructuredListCell>Row 1</StructuredListCell>
    </StructuredListRow>
    <StructuredListRow>
      <StructuredListCell>Row 2</StructuredListCell>
      <StructuredListCell>Row 2</StructuredListCell>
      <StructuredListCell>Row 2</StructuredListCell>
    </StructuredListRow>
    <StructuredListRow>
      <StructuredListCell>Row 3</StructuredListCell>
      <StructuredListCell>Row 3</StructuredListCell>
      <StructuredListCell>Row 3</StructuredListCell>
    </StructuredListRow>
  </StructuredListBody>
</StructuredList>
```

### Flush variant

Use the flush variant to remove padding from the list.

```svelte
<script>
  import {
    StructuredList,
    StructuredListBody,
    StructuredListCell,
    StructuredListHead,
    StructuredListRow,
  } from "carbon-components-svelte";
</script>

<StructuredList flush>
  <StructuredListHead>
    <StructuredListRow head>
      <StructuredListCell head>Column A</StructuredListCell>
      <StructuredListCell head>Column B</StructuredListCell>
      <StructuredListCell head>Column C</StructuredListCell>
    </StructuredListRow>
  </StructuredListHead>
  <StructuredListBody>
    <StructuredListRow>
      <StructuredListCell noWrap>Row 1</StructuredListCell>
      <StructuredListCell>Row 1</StructuredListCell>
      <StructuredListCell>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc dui magna,
        finibus id tortor sed, aliquet bibendum augue. Aenean posuere sem vel
        euismod dignissim. Nulla ut cursus dolor. Pellentesque vulputate nisl a
        porttitor interdum.
      </StructuredListCell>
    </StructuredListRow>
    <StructuredListRow>
      <StructuredListCell noWrap>Row 2</StructuredListCell>
      <StructuredListCell>Row 2</StructuredListCell>
      <StructuredListCell>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc dui magna,
        finibus id tortor sed, aliquet bibendum augue. Aenean posuere sem vel
        euismod dignissim. Nulla ut cursus dolor. Pellentesque vulputate nisl a
        porttitor interdum.
      </StructuredListCell>
    </StructuredListRow>
    <StructuredListRow>
      <StructuredListCell noWrap>Row 3</StructuredListCell>
      <StructuredListCell>Row 3</StructuredListCell>
      <StructuredListCell>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc dui magna,
        finibus id tortor sed, aliquet bibendum augue. Aenean posuere sem vel
        euismod dignissim. Nulla ut cursus dolor. Pellentesque vulputate nisl a
        porttitor interdum.
      </StructuredListCell>
    </StructuredListRow>
  </StructuredListBody>
</StructuredList>
```

### Selectable rows

Enable row selection with the `selection` prop and structured list input
components.

```svelte
<script>
  import {
    StructuredList,
    StructuredListBody,
    StructuredListCell,
    StructuredListHead,
    StructuredListInput,
    StructuredListRow,
  } from "carbon-components-svelte";
  import CheckmarkFilled from "carbon-icons-svelte/lib/CheckmarkFilled.svelte";
</script>

<StructuredList selection selected="row-1-value">
  <StructuredListHead>
    <StructuredListRow head>
      <StructuredListCell head>ColumnA</StructuredListCell>
      <StructuredListCell head>ColumnB</StructuredListCell>
      <StructuredListCell head>ColumnC</StructuredListCell>
      <StructuredListCell head>{""}</StructuredListCell>
    </StructuredListRow>
  </StructuredListHead>
  <StructuredListBody>
    {#each [1, 2, 3] as item}
      <StructuredListRow label for="row-{item}">
        <StructuredListCell>Row {item}</StructuredListCell>
        <StructuredListCell>Row {item}</StructuredListCell>
        <StructuredListCell>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc dui
          magna, finibus id tortor sed, aliquet bibendum augue. Aenean posuere
          sem vel euismod dignissim. Nulla ut cursus dolor. Pellentesque
          vulputate nisl a porttitor interdum.
        </StructuredListCell>
        <StructuredListInput
          id="row-{item}"
          value="row-{item}-value"
          title="row-{item}-title"
          name="row-{item}-name"
        />
        <StructuredListCell>
          <CheckmarkFilled
            class="bx--structured-list-svg"
            aria-label="select an option"
            title="select an option"
          />
        </StructuredListCell>
      </StructuredListRow>
    {/each}
  </StructuredListBody>
</StructuredList>
```

### Skeleton

Show a loading state with the skeleton variant.

```svelte
<script>
  import { StructuredListSkeleton } from "carbon-components-svelte";
</script>

<StructuredListSkeleton rows={3} />
```

---

### Component API

#### `StructuredList` props

| Prop                  | Type                 | Description                                     | Default     |
| --------------------- | -------------------- | ----------------------------------------------- | ----------- |
| `selected` (Reactive) | `Value \| undefined` | Specify the selected structured list row value. | _undefined_ |
| `condensed`           | `boolean`            | Set to `true` to use the condensed variant      | `false`     |
| `flush`               | `boolean`            | Set to `true` to flush the list                 | `false`     |
| `selection`           | `boolean`            | Set to `true` to use the selection variant      | `false`     |

#### `StructuredList` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `StructuredList` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `StructuredList` dispatched events

| Event       | Detail  |
| ----------- | ------- |
| `on:change` | `Value` |

#### `StructuredList` $$restProps

`StructuredList` spreads `$$restProps` to the `div` element.

#### `StructuredListSkeleton` props

| Prop   | Type     | Description                | Default |
| ------ | -------- | -------------------------- | ------- |
| `rows` | `number` | Specify the number of rows | `5`     |

#### `StructuredListSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `StructuredListSkeleton` $$restProps

`StructuredListSkeleton` spreads `$$restProps` to the `div` element.

#### `StructuredListBody` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `StructuredListBody` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `StructuredListBody` $$restProps

`StructuredListBody` spreads `$$restProps` to the `div` element.

#### `StructuredListHead` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `StructuredListHead` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `StructuredListHead` $$restProps

`StructuredListHead` spreads `$$restProps` to the `div` element.

#### `StructuredListCell` props

| Prop     | Type      | Description                       | Default |
| -------- | --------- | --------------------------------- | ------- |
| `head`   | `boolean` | Set to `true` to use as a header  | `false` |
| `noWrap` | `boolean` | Set to `true` to prevent wrapping | `false` |

#### `StructuredListCell` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `StructuredListCell` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `StructuredListCell` $$restProps

`StructuredListCell` spreads `$$restProps` to the `div` element.

#### `StructuredListRow` props

| Prop       | Type      | Description                          | Default |
| ---------- | --------- | ------------------------------------ | ------- |
| `head`     | `boolean` | Set to `true` to use as a header     | `false` |
| `label`    | `boolean` | Set to `true` to render a label slot | `false` |
| `tabindex` | `string`  | Specify the tabindex                 | `"0"`   |

#### `StructuredListRow` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `StructuredListRow` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:keydown`    |

#### `StructuredListRow` $$restProps

`StructuredListRow` spreads `$$restProps` to the `label` element.

#### `StructuredListInput` props

| Prop                 | Type                       | Description                                  | Default                             |
| -------------------- | -------------------------- | -------------------------------------------- | ----------------------------------- |
| `checked` (Reactive) | `boolean`                  | Set to `true` to check the input             | `false`                             |
| `ref` (Reactive)     | `null \| HTMLInputElement` | Obtain a reference to the input HTML element | `null`                              |
| `title`              | `string`                   | Specify the title of the input               | `"title"`                           |
| `value`              | `Value`                    | Specify the value of the input.              | `"value"`                           |
| `id`                 | `string`                   | Set an id for the input element              | `ccs-${Math.random().toString(36)}` |
| `name`               | `string`                   | Specify a name attribute for the input       | `""`                                |

#### `StructuredListInput` $$restProps

`StructuredListInput` spreads `$$restProps` to the `input` element.


## Tabs

Tabs provide a way to organize content into separate views that can be switched
between. They support keyboard navigation, disabled states, and various layout
options.

### Default

Create a basic tab interface with labels and content.

```svelte
<script>
  import { Tab, TabContent, Tabs } from "carbon-components-svelte";
</script>

<Tabs>
  <Tab label="Tab label 1" />
  <Tab label="Tab label 2" />
  <Tab label="Tab label 3" />
  <svelte:fragment slot="content">
    <TabContent>Content 1</TabContent>
    <TabContent>Content 2</TabContent>
    <TabContent>Content 3</TabContent>
  </svelte:fragment>
</Tabs>
```

### Auto width

By default, each tab has a fixed width of `10rem`. Set `autoWidth` to `true` for
tabs to automatically adjust their width based on content.

```svelte
<script>
  import { Tab, TabContent, Tabs } from "carbon-components-svelte";
</script>

<Tabs autoWidth>
  <Tab label="Tab label 1" />
  <Tab label="Tab label 2" />
  <Tab label="Tab label 3" />
  <svelte:fragment slot="content">
    <TabContent>Content 1</TabContent>
    <TabContent>Content 2</TabContent>
    <TabContent>Content 3</TabContent>
  </svelte:fragment>
</Tabs>
```

### Reactive example

Use `bind:selected` to create a two-way binding with the selected tab index.
This allows you to programmatically control the selected tab and react to tab
changes.

```svelte
<script>
  import { Button, Tab, TabContent, Tabs } from "carbon-components-svelte";

  let selected = 0;
</script>

<Tabs bind:selected>
  <Tab label="Tab label 1" />
  <Tab label="Tab label 2" />
  <Tab label="Tab label 3" />
  <svelte:fragment slot="content">
    <TabContent>Content 1</TabContent>
    <TabContent>Content 2</TabContent>
    <TabContent>Content 3</TabContent>
  </svelte:fragment>
</Tabs>

<div style="margin: var(--cds-layout-01) 0">
  <Button on:click={() => (selected = 1)}>Set index to 1</Button>
</div>

<strong>Selected index:</strong>
{selected}
```

### Conditional tabs

Tabs can be conditionally rendered using Svelte's `{#if}` blocks. The component
automatically maintains correct indices even when tabs are dynamically added or
removed.

If the current selected tab is removed, the next tab will be selected.

```svelte
<script>
  import { Checkbox, Tab, TabContent, Tabs } from "carbon-components-svelte";

  let selected = 0;
  let showAdminTab = true;
  let showSettingsTab = true;
</script>

<Checkbox bind:checked={showAdminTab} labelText="Show Admin tab" />
<Checkbox bind:checked={showSettingsTab} labelText="Show Settings tab" />

<div
  style:margin-top="var(--cds-layout-01)"
  style:margin-bottom="var(--cds-layout-02)"
>
  <strong>Selected index:</strong>
  {selected}
</div>

<Tabs bind:selected>
  <Tab label="Dashboard" />
  {#if showAdminTab}
    <Tab label="Admin" />
  {/if}
  {#if showSettingsTab}
    <Tab label="Settings" />
  {/if}
  <Tab label="Profile" />
  <svelte:fragment slot="content">
    <TabContent>
      <p>Dashboard content with analytics and overview.</p>
    </TabContent>
    {#if showAdminTab}
      <TabContent>
        <p>Admin panel for managing users and permissions.</p>
      </TabContent>
    {/if}
    {#if showSettingsTab}
      <TabContent>
        <p>Settings and configuration options.</p>
      </TabContent>
    {/if}
    <TabContent>
      <p>User profile and account information.</p>
    </TabContent>
  </svelte:fragment>
</Tabs>
```

### Disabled tabs

Set `disabled` to `true` on a tab component to prevent interaction. Keyboard
navigation will skip disabled tabs.

```svelte
<script>
  import { Tab, TabContent, Tabs } from "carbon-components-svelte";
</script>

<Tabs>
  <Tab label="Tab label 1" />
  <Tab label="Tab label 2" disabled />
  <Tab label="Tab label 3" disabled />
  <Tab label="Tab label 4" />
  <svelte:fragment slot="content">
    <TabContent>Content 1</TabContent>
    <TabContent>Content 2</TabContent>
    <TabContent>Content 3</TabContent>
    <TabContent>Content 4</TabContent>
  </svelte:fragment>
</Tabs>
```

### Container type

Use the container type for a more prominent tab interface.

```svelte
<script>
  import { Tab, TabContent, Tabs } from "carbon-components-svelte";
</script>

<Tabs type="container">
  <Tab label="Tab label 1" />
  <Tab label="Tab label 2" />
  <Tab label="Tab label 3" />
  <svelte:fragment slot="content">
    <TabContent>Content 1</TabContent>
    <TabContent>Content 2</TabContent>
    <TabContent>Content 3</TabContent>
  </svelte:fragment>
</Tabs>
```

### Skeleton (default)

Show a loading state with the default skeleton variant.

```svelte
<script>
  import { TabsSkeleton } from "carbon-components-svelte";
</script>

<TabsSkeleton count={3} />
```

### Skeleton (container)

Show a loading state with the container skeleton variant.

```svelte
<script>
  import { TabsSkeleton } from "carbon-components-svelte";
</script>

<TabsSkeleton type="container" count={3} />
```

---

### Component API

#### `Tabs` props

| Prop                  | Type                       | Description                                  | Default               |
| --------------------- | -------------------------- | -------------------------------------------- | --------------------- |
| `selected` (Reactive) | `number`                   | Specify the selected tab index               | `0`                   |
| `type`                | `"default" \| "container"` | Specify the type of tabs.                    | `"default"`           |
| `autoWidth`           | `boolean`                  | Set to `true` for tabs to have an auto-width | `false`               |
| `iconDescription`     | `string`                   | Specify the ARIA label for the chevron icon. | `"Show menu options"` |
| `triggerHref`         | `string`                   | Specify the tab trigger href attribute       | `"#"`                 |

#### `Tabs` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |
| `content` | `Record<string, never>` |

#### `Tabs` forwarded events

| Event         |
| ------------- |
| `on:keypress` |
| `on:click`    |

#### `Tabs` dispatched events

| Event       | Detail   |
| ----------- | -------- |
| `on:change` | `number` |

#### `Tabs` $$restProps

`Tabs` spreads `$$restProps` to the `div` element.

#### `Tab` props

| Prop             | Type                        | Description                                                      | Default                             |
| ---------------- | --------------------------- | ---------------------------------------------------------------- | ----------------------------------- |
| `ref` (Reactive) | `null \| HTMLAnchorElement` | Obtain a reference to the anchor HTML element                    | `null`                              |
| `label`          | `string`                    | Specify the tab label.<br />Alternatively, use the default slot. | `""`                                |
| `href`           | `string`                    | Specify the href attribute                                       | `"#"`                               |
| `disabled`       | `boolean`                   | Set to `true` to disable the tab                                 | `false`                             |
| `tabindex`       | `string`                    | Specify the tabindex                                             | `"0"`                               |
| `id`             | `string`                    | Set an id for the top-level element                              | `ccs-${Math.random().toString(36)}` |

#### `Tab` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `Tab` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `Tab` $$restProps

`Tab` spreads `$$restProps` to the `li` element.

#### `TabContent` props

| Prop | Type     | Description                         | Default                             |
| ---- | -------- | ----------------------------------- | ----------------------------------- |
| `id` | `string` | Set an id for the top-level element | `ccs-${Math.random().toString(36)}` |

#### `TabContent` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `TabContent` $$restProps

`TabContent` spreads `$$restProps` to the `div` element.

#### `TabsSkeleton` props

| Prop    | Type                       | Description                          | Default     |
| ------- | -------------------------- | ------------------------------------ | ----------- |
| `count` | `number`                   | Specify the number of tabs to render | `4`         |
| `type`  | `"default" \| "container"` | Specify the type of tabs.            | `"default"` |

#### `TabsSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `TabsSkeleton` $$restProps

`TabsSkeleton` spreads `$$restProps` to the `div` element.


## Tag

Tags provide a way to categorize content with a keyword or label. They support
various styles, sizes, and interactive states, including filterable and
interactive variants.

### Default

Create a basic tag with text content.

```svelte
<script>
  import { Tag } from "carbon-components-svelte";
</script>

<Tag>IBM Cloud</Tag>
```

### Small size

Use the small size variant for more compact layouts.

```svelte
<script>
  import { Tag } from "carbon-components-svelte";
</script>

<Tag size="sm">IBM Cloud</Tag>
```

### Tag types

Choose from a variety of color types to match your design system.

```svelte
<script>
  import { Tag } from "carbon-components-svelte";
</script>

<Tag type="red">red</Tag>
<Tag type="magenta">magenta</Tag>
<Tag type="purple">purple</Tag>
<Tag type="blue">blue</Tag>
<Tag type="cyan">cyan</Tag>
<Tag type="teal">teal</Tag>
<Tag type="green">green</Tag>
<Tag type="gray">gray</Tag>
<Tag type="cool-gray">cool-gray</Tag>
<Tag type="warm-gray">warm-gray</Tag>
<Tag type="high-contrast">high-contrast</Tag>
<Tag type="outline">outline</Tag>
```

### Filterable

Create a filterable tag with a close button that dispatches a `close` event when
clicked.

```svelte
<script>
  import { Tag } from "carbon-components-svelte";
</script>

<Tag filter on:close>carbon-components</Tag>
```

### Filterable (disabled)

Disable a filterable tag to prevent interaction.

```svelte
<script>
  import { Tag } from "carbon-components-svelte";
</script>

<Tag filter disabled on:close>carbon-components</Tag>
```

### Filterable (small)

Combine the filterable variant with the small size.

```svelte
<script>
  import { Tag } from "carbon-components-svelte";
</script>

<Tag size="sm" filter on:close>carbon-components</Tag>
```

### Custom icon

Add a custom icon to the tag. Note: custom icons cannot be used with the
filterable variant.

```svelte
<script>
  import { Tag } from "carbon-components-svelte";
  import IbmCloud from "carbon-icons-svelte/lib/IbmCloud.svelte";
</script>

<Tag icon={IbmCloud}>IBM Cloud</Tag>
```

### Interactive variant

Set `interactive` to `true` to render a `button` element instead of a `div`.
This is useful for clickable tags.

```svelte
<script>
  import { Tag } from "carbon-components-svelte";
</script>

<Tag interactive>Machine learning</Tag>
```

### Disabled state

Both filterable and interactive tag variants support a disabled state.

```svelte
<script>
  import { Tag } from "carbon-components-svelte";
</script>

<Tag filter disabled>Machine learning</Tag>
<Tag interactive disabled>Machine learning</Tag>
```

### Tooltip in a tag

Embed a tooltip within a tag to provide additional context.

```svelte
<script>
  import { Tag, TooltipDefinition } from "carbon-components-svelte";
</script>

<Tag>
  <TooltipDefinition
    tooltipText="IBM Corporate Headquarters is based in Armonk, New York."
  >
    Armonk
  </TooltipDefinition>
</Tag>
```

### Skeleton

Show a loading state with the default skeleton variant.

```svelte
<script>
  import { Tag } from "carbon-components-svelte";
</script>

<Tag skeleton />
```

### Skeleton (small)

Show a loading state with the small skeleton variant.

```svelte
<script>
  import { Tag } from "carbon-components-svelte";
</script>

<Tag size="sm" skeleton />
```

---

### Component API

#### `Tag` props

| Prop          | Type                                                                                                                                              | Description                                                   | Default                             |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------- |
| `type`        | `"red" \| "magenta" \| "purple" \| "blue" \| "cyan" \| "teal" \| "green" \| "gray" \| "cool-gray" \| "warm-gray" \| "high-contrast" \| "outline"` | Specify the type of tag.                                      | _undefined_                         |
| `size`        | `"sm" \| "default"`                                                                                                                               |                                                               | `"default"`                         |
| `filter`      | `boolean`                                                                                                                                         | Set to `true` to use filterable variant                       | `false`                             |
| `disabled`    | `boolean`                                                                                                                                         | Set to `true` to disable a filterable tag                     | `false`                             |
| `interactive` | `boolean`                                                                                                                                         | Set to `true` to render a `button` element instead of a `div` | `false`                             |
| `skeleton`    | `boolean`                                                                                                                                         | Set to `true` to display the skeleton state                   | `false`                             |
| `title`       | `string`                                                                                                                                          | Set the title for the close button in a filterable tag        | `"Clear filter"`                    |
| `icon`        | `any`                                                                                                                                             | Specify the icon to render.                                   | _undefined_                         |
| `id`          | `string`                                                                                                                                          | Set an id for the filterable tag                              | `ccs-${Math.random().toString(36)}` |

#### `Tag` slots

| Slot      | Detail                                               |
| --------- | ---------------------------------------------------- |
| `default` | `{<br /> props: { class: "bx--tag__label" };<br />}` |
| `icon`    | `Record<string, never>`                              |

#### `Tag` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `Tag` dispatched events

| Event      | Detail |
| ---------- | ------ |
| `on:close` | `null` |

#### `Tag` $$restProps

`Tag` spreads `$$restProps` to the `div | span` element.

#### `TagSkeleton` props

| Prop   | Type                | Description | Default     |
| ------ | ------------------- | ----------- | ----------- |
| `size` | `"sm" \| "default"` |             | `"default"` |

#### `TagSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `TagSkeleton` $$restProps

`TagSkeleton` spreads `$$restProps` to the `span` element.


## TextArea

Text areas provide a multi-line text input field with support for various
states, character counting, and accessibility features. They are ideal for
longer text input like descriptions, comments, or messages.

### Default

Create a basic textarea with a label and placeholder text.

```svelte
<script>
  import { TextArea } from "carbon-components-svelte";
</script>

<TextArea labelText="App description" placeholder="Enter a description..." />
```

### Maximum character count

Specify the max character count using the `maxCount` prop. A character counter
will be displayed to the right of the label. You can also use the native
`maxlength` attribute if you prefer not to show a counter.

```svelte
<script>
  import { TextArea } from "carbon-components-svelte";
</script>

<TextArea
  labelText="App description"
  placeholder="Enter a description..."
  maxCount={100}
/>
```

### With helper text

Add helper text below the textarea to provide additional context or
instructions.

```svelte
<script>
  import { TextArea } from "carbon-components-svelte";
</script>

<TextArea
  labelText="App description"
  helperText="A rich description helps us better recommend related products and services"
  placeholder="Enter a description..."
/>
```

### Hidden label

Visually hide the label while maintaining accessibility by setting `hideLabel`
to `true`.

```svelte
<script>
  import { TextArea } from "carbon-components-svelte";
</script>

<TextArea
  hideLabel
  labelText="App description"
  placeholder="Enter a description..."
/>
```

### Light variant

Use the light variant for light-themed backgrounds by setting `light` to `true`.

```svelte
<script>
  import { TextArea } from "carbon-components-svelte";
</script>

<TextArea
  light
  labelText="App description"
  placeholder="Enter a description..."
/>
```

### Custom rows

Adjust the number of visible rows using the `rows` prop. The default is 4 rows.

```svelte
<script>
  import { TextArea } from "carbon-components-svelte";
</script>

<TextArea
  rows={10}
  labelText="App description"
  placeholder="Enter a description..."
/>
```

### Invalid state

Indicate an invalid state with an error message by setting `invalid` to `true`
and providing `invalidText`.

```svelte
<script>
  import { TextArea } from "carbon-components-svelte";
</script>

<TextArea
  invalid
  invalidText="Only plain text characters are allowed"
  labelText="App description"
  placeholder="Enter a description..."
/>
```

### Warning state

Indicate a warning state with a message by setting `warn` to `true` and
providing `warnText`.

```svelte
<script>
  import { TextArea } from "carbon-components-svelte";
</script>

<TextArea
  warn
  warnText="This description is shorter than recommended"
  labelText="App description"
  placeholder="Enter a description..."
/>
```

### Disabled state

Disable the textarea to prevent user interaction by setting `disabled` to
`true`.

```svelte
<script>
  import { TextArea } from "carbon-components-svelte";
</script>

<TextArea
  disabled
  labelText="App description"
  placeholder="Enter a description..."
/>
```

### Skeleton

Show a loading state with the default skeleton variant.

```svelte
<script>
  import { TextAreaSkeleton } from "carbon-components-svelte";
</script>

<TextAreaSkeleton />
```

### Skeleton without label

Show a loading state without a label by setting `hideLabel` to `true`.

```svelte
<script>
  import { TextAreaSkeleton } from "carbon-components-svelte";
</script>

<TextAreaSkeleton hideLabel />
```

---

### Component API

#### `TextArea` props

| Prop               | Type                          | Description                                                                                                                               | Default                             |
| ------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `value` (Reactive) | `null \| string`              | Specify the textarea value.                                                                                                               | `""`                                |
| `ref` (Reactive)   | `null \| HTMLTextAreaElement` | Obtain a reference to the textarea HTML element                                                                                           | `null`                              |
| `placeholder`      | `string`                      | Specify the placeholder text                                                                                                              | `""`                                |
| `cols`             | `number`                      | Specify the number of cols.<br />If specified, the textarea will not be resizable.<br />Override this using the `resize` style attribute. | _undefined_                         |
| `rows`             | `number`                      | Specify the number of rows                                                                                                                | `4`                                 |
| `maxCount`         | `number`                      | Specify the max character count.                                                                                                          | _undefined_                         |
| `light`            | `boolean`                     | Set to `true` to enable the light variant                                                                                                 | `false`                             |
| `disabled`         | `boolean`                     | Set to `true` to disable the input                                                                                                        | `false`                             |
| `readonly`         | `boolean`                     | Set to `true` to use the read-only variant                                                                                                | `false`                             |
| `helperText`       | `string`                      | Specify the helper text                                                                                                                   | `""`                                |
| `labelText`        | `string`                      | Specify the label text                                                                                                                    | `""`                                |
| `hideLabel`        | `boolean`                     | Set to `true` to visually hide the label text                                                                                             | `false`                             |
| `invalid`          | `boolean`                     | Set to `true` to indicate an invalid state                                                                                                | `false`                             |
| `invalidText`      | `string`                      | Specify the text for the invalid state                                                                                                    | `""`                                |
| `warn`             | `boolean`                     | Set to `true` to indicate a warning state                                                                                                 | `false`                             |
| `warnText`         | `string`                      | Specify the warning state text                                                                                                            | `""`                                |
| `id`               | `string`                      | Set an id for the textarea element                                                                                                        | `ccs-${Math.random().toString(36)}` |
| `name`             | `string`                      | Specify a name attribute for the input.                                                                                                   | _undefined_                         |

#### `TextArea` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `labelChildren` | `Record<string, never>` |

#### `TextArea` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:change`     |
| `on:input`      |
| `on:keydown`    |
| `on:keyup`      |
| `on:focus`      |
| `on:blur`       |
| `on:paste`      |

#### `TextArea` $$restProps

`TextArea` spreads `$$restProps` to the `textarea` element.

#### `TextAreaSkeleton` props

| Prop        | Type      | Description                                   | Default |
| ----------- | --------- | --------------------------------------------- | ------- |
| `hideLabel` | `boolean` | Set to `true` to visually hide the label text | `false` |

#### `TextAreaSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `TextAreaSkeleton` $$restProps

`TextAreaSkeleton` spreads `$$restProps` to the `div` element.


## TextInput

Text inputs provide a single-line text input field with support for various
states, sizes, and accessibility features. They are ideal for short text input
like usernames, search terms, or form fields.

### Default

Create a basic text input with a label and placeholder text.

```svelte
<script>
  import { TextInput } from "carbon-components-svelte";
</script>

<TextInput labelText="User name" placeholder="Enter user name..." />
```

### With helper text

Add helper text below the input to provide additional context or instructions.

```svelte
<script>
  import { TextInput } from "carbon-components-svelte";
</script>

<TextInput
  labelText="User name"
  helperText="Your user name is associated with your email"
  placeholder="Enter user name..."
/>
```

### Hidden label

Visually hide the label while maintaining accessibility by setting `hideLabel`
to `true`.

```svelte
<script>
  import { TextInput } from "carbon-components-svelte";
</script>

<TextInput hideLabel labelText="User name" placeholder="Enter user name..." />
```

### Custom label

Use the `labelChildren` slot to provide custom label content.

```svelte
<script>
  import { TextInput } from "carbon-components-svelte";
</script>

<TextInput labelText="" placeholder="Enter user name...">
  <strong slot="labelChildren">User name</strong>
</TextInput>
```

### Light variant

Use the light variant for light-themed backgrounds by setting `light` to `true`.

```svelte
<script>
  import { TextInput } from "carbon-components-svelte";
</script>

<TextInput light labelText="User name" placeholder="Enter user name..." />
```

### Inline variant

Use the inline variant to display the label and input on the same line by
setting `inline` to `true`.

```svelte
<script>
  import { TextInput } from "carbon-components-svelte";
</script>

<TextInput inline labelText="User name" placeholder="Enter user name..." />
```

### Inline variant with custom label

Use the `labelChildren` slot to provide custom inline label content.

```svelte
<script>
  import { TextInput } from "carbon-components-svelte";
</script>

<TextInput inline labelText="" placeholder="Enter user name...">
  <strong slot="labelChildren">User name</strong>
</TextInput>
```

### Extra-large size

Use the extra-large size for more prominent inputs by setting `size` to `"xl"`.

```svelte
<script>
  import { TextInput } from "carbon-components-svelte";
</script>

<TextInput size="xl" labelText="User name" placeholder="Enter user name..." />
```

### Small size

Use the small size for more compact inputs by setting `size` to `"sm"`.

```svelte
<script>
  import { TextInput } from "carbon-components-svelte";
</script>

<TextInput size="sm" labelText="User name" placeholder="Enter user name..." />
```

### Invalid state

Indicate an invalid state with an error message by setting `invalid` to `true`
and providing `invalidText`.

```svelte
<script>
  import { TextInput } from "carbon-components-svelte";
</script>

<TextInput
  invalid
  invalidText="User name is already taken. Please try another."
  labelText="User name"
  placeholder="Enter user name..."
/>
```

### Warning state

Indicate a warning state with a message by setting `warn` to `true` and
providing `warnText`.

```svelte
<script>
  import { TextInput } from "carbon-components-svelte";
</script>

<TextInput
  warn
  warnText="Your user name is different from your log in ID."
  labelText="User name"
  placeholder="Enter user name..."
/>
```

### Disabled state

Disable the input to prevent user interaction by setting `disabled` to `true`.

```svelte
<script>
  import { TextInput } from "carbon-components-svelte";
</script>

<TextInput disabled labelText="User name" placeholder="Enter user name..." />
```

### Read-only state

Display a non-editable value by setting `readonly` to `true`.

```svelte
<script>
  import { TextInput } from "carbon-components-svelte";
</script>

<TextInput readonly labelText="User name" value="IBM" />
```

### Skeleton

Show a loading state with the default skeleton variant.

```svelte
<script>
  import { TextInputSkeleton } from "carbon-components-svelte";
</script>

<TextInputSkeleton />
```

### Skeleton without label

Show a loading state without a label by setting `hideLabel` to `true`.

```svelte
<script>
  import { TextInputSkeleton } from "carbon-components-svelte";
</script>

<TextInputSkeleton hideLabel />
```

---

### Component API

#### `TextInput` props

| Prop               | Type                       | Description                                                                                                | Default                             |
| ------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `value` (Reactive) | `null \| number \| string` | Specify the input value.<br /><br />`value` will be set to `null` if type="number" and the value is empty. | `""`                                |
| `ref` (Reactive)   | `null \| HTMLInputElement` | Obtain a reference to the input HTML element                                                               | `null`                              |
| `size`             | `"sm" \| "xl"`             | Set the size of the input.                                                                                 | _undefined_                         |
| `placeholder`      | `string`                   | Specify the placeholder text                                                                               | `""`                                |
| `light`            | `boolean`                  | Set to `true` to enable the light variant                                                                  | `false`                             |
| `disabled`         | `boolean`                  | Set to `true` to disable the input                                                                         | `false`                             |
| `helperText`       | `string`                   | Specify the helper text                                                                                    | `""`                                |
| `id`               | `string`                   | Set an id for the input element                                                                            | `ccs-${Math.random().toString(36)}` |
| `name`             | `string`                   | Specify a name attribute for the input.                                                                    | _undefined_                         |
| `labelText`        | `string`                   | Specify the label text                                                                                     | `""`                                |
| `hideLabel`        | `boolean`                  | Set to `true` to visually hide the label text                                                              | `false`                             |
| `invalid`          | `boolean`                  | Set to `true` to indicate an invalid state                                                                 | `false`                             |
| `invalidText`      | `string`                   | Specify the invalid state text                                                                             | `""`                                |
| `warn`             | `boolean`                  | Set to `true` to indicate a warning state                                                                  | `false`                             |
| `warnText`         | `string`                   | Specify the warning state text                                                                             | `""`                                |
| `required`         | `boolean`                  | Set to `true` to mark the field as required                                                                | `false`                             |
| `inline`           | `boolean`                  | Set to `true` to use the inline variant                                                                    | `false`                             |
| `readonly`         | `boolean`                  | Set to `true` to use the read-only variant                                                                 | `false`                             |

#### `TextInput` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `labelChildren` | `Record<string, never>` |

#### `TextInput` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:keydown`    |
| `on:keyup`      |
| `on:focus`      |
| `on:blur`       |
| `on:paste`      |

#### `TextInput` dispatched events

| Event       | Detail                                                             |
| ----------- | ------------------------------------------------------------------ |
| `on:change` | `type EventDetail =<br /> \| null<br /> \| number<br /> \| string` |
| `on:input`  | `type EventDetail =<br /> \| null<br /> \| number<br /> \| string` |

#### `TextInput` $$restProps

`TextInput` spreads `$$restProps` to the `input` element.

#### `TextInputSkeleton` props

| Prop        | Type      | Description                          | Default |
| ----------- | --------- | ------------------------------------ | ------- |
| `hideLabel` | `boolean` | Set to `true` to hide the label text | `false` |

#### `TextInputSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `TextInputSkeleton` $$restProps

`TextInputSkeleton` spreads `$$restProps` to the `div` element.


## Theme

Theme provides dynamic client-side theming using CSS variables. It supports five
themes: `white`, `g10`, `g80`, `g90`, and `g100`, and allows for custom theme
token overrides.

The component can persist theme preferences using
[window.localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
and provides built-in toggle and select controls for theme switching.

You must use the `all.css` StyleSheet for dynamic theming, which uses
[CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).

```css
import "carbon-components-svelte/css/all.css";
```

### Default

Create a basic theme component that can be controlled programmatically.

```svelte
<script>
  import {
    RadioButton,
    RadioButtonGroup,
    Theme,
  } from "carbon-components-svelte";

  let theme = "g90";
</script>

<Theme bind:theme />

<RadioButtonGroup legendText="Carbon theme" bind:selected={theme}>
  {#each ["white", "g10", "g80", "g90", "g100"] as value}
    <RadioButton labelText={value} {value} />
  {/each}
</RadioButtonGroup>
```

### Persist locally

Set `persist` to `true` to save the theme preference in
[localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).
Use `persistKey` to specify a custom storage key.

When `persist` is enabled, theme changes are automatically synchronized across
browser tabs. When the theme is changed in one tab, all other tabs with the same
`persistKey` will update immediately.

```svelte
<script>
  import {
    RadioButton,
    RadioButtonGroup,
    Theme,
  } from "carbon-components-svelte";

  let theme = "g90";
</script>

<Theme bind:theme persist persistKey="__carbon-theme" />

<RadioButtonGroup legendText="Carbon theme" bind:selected={theme}>
  {#each ["white", "g10", "g80", "g90", "g100"] as value}
    <RadioButton labelText={value} {value} />
  {/each}
</RadioButtonGroup>
```

### Custom theme

Override default Carbon theme tokens using the `tokens` prop.

**Understanding token usage:** The Theme component sets CSS custom properties
via `--cds-{token}`. However, not all token names directly map to component
styles. Components often use **semantic tokens** (like `interactive-01`) rather
than component-specific tokens (like `button-primary`).

For example, primary buttons use `interactive-01` for background color,
`hover-primary` for hover state, and `active-primary` for active state. Both
token types exist in the system but serve different purposes. Refer to the
component CSS or Carbon Design System documentation to understand which tokens
affect specific components.

```svelte
<script>
  import {
    Button,
    Checkbox,
    InlineNotification,
    Link,
    Stack,
    Tag,
    TextInput,
    Theme,
    Tile,
    Toggle,
  } from "carbon-components-svelte";
</script>

<Theme
  theme="g90"
  tokens={{
    // Interactive elements
    "interactive-01": "#d02670", // Primary button background
    "hover-primary": "#ee5396", // Primary button hover
    "active-primary": "#9f1853", // Primary button active
    "interactive-02": "#6f6f6f", // Secondary button background
    "hover-secondary": "#5e5e5e", // Secondary button hover

    // Links
    "link-01": "#ff6eb3", // Link text color

    // Tags
    "tag-background-blue": "#4a1942", // Tag background
    "tag-color-blue": "#ffb3d9", // Tag text color

    // Form elements
    "field-01": "#2d2d2d", // Input field background
    "ui-01": "#2d2d2d", // Tile background
    focus: "#ff6eb3", // Focus indicator color

    // Text colors
    "text-01": "#ffffff", // Primary text
    "text-02": "#c6c6c6", // Secondary text

    // Notification colors
    "support-04": "#a855f7", // Info notification color
  }}
/>

<Stack gap={5}>
  <div>
    <Button>Primary button</Button>
    <Button kind="secondary">Secondary button</Button>
  </div>

  <div>
    <Link href="#example">Themed link</Link>
  </div>

  <div>
    <Tag type="blue">Themed tag</Tag>
  </div>

  <TextInput labelText="Text input" placeholder="Enter text..." />

  <Checkbox labelText="Checkbox with themed focus" />

  <Toggle labelText="Toggle with themed colors" />

  <Tile>
    <p>Tile with themed background</p>
  </Tile>

  <InlineNotification
    kind="info"
    title="Info notification"
    subtitle="With themed colors"
    hideCloseButton
    lowContrast
  />
</Stack>
```

### Theme toggle

Set `render` to `"toggle"` to display a toggle switch for switching between two
themes. By default, it toggles between "white" and "g100" themes.

```svelte
<script>
  import { Theme } from "carbon-components-svelte";
</script>

<Theme render="toggle" />
```

### Theme toggle (custom)

Customize the toggle appearance and behavior using the `toggle` prop. You can
specify custom themes, labels, and other toggle properties.

```svelte
<script>
  import { Theme } from "carbon-components-svelte";
</script>

<Theme
  render="toggle"
  toggle={{
    themes: ["g10", "g80"],
    labelA: "Enable dark mode",
    labelB: "Enable dark mode",
    hideLabel: true,
    size: "sm",
  }}
/>
```

### Theme select

Set `render` to `"select"` to display a dropdown menu for selecting from all
available themes.

```svelte
<script>
  import { Theme } from "carbon-components-svelte";
</script>

<Theme render="select" />
```

### Theme select (custom)

Customize the select dropdown using the `select` prop. You can specify which
themes to include, customize labels, and adjust other select properties.

```svelte
<script>
  import { Theme } from "carbon-components-svelte";
</script>

<Theme
  render="select"
  select={{
    themes: ["white", "g90", "g100"],
    labelText: "Select a theme",
    inline: true,
  }}
/>
```

### Exported themes constant

The `themes` constant is exported from the Theme component, providing
programmatic access to all available theme keys and their human-readable labels.

`themes` must be imported directly from the Theme component file and used in a
`script context="module"` block in Svelte components.

```html
<script context="module">
  import { themes } from "carbon-components-svelte/src/Theme/Theme.svelte";

  // themes = {
  //   white: "White",
  //   g10: "Gray 10",
  //   g80: "Gray 80",
  //   g90: "Gray 90",
  //   g100: "Gray 100"
  // }

  // Get all theme keys programmatically
  const themeKeys = Object.keys(themes); // ["white", "g10", "g80", "g90", "g100"]

  // Build custom theme selectors with correct labels
  Object.entries(themes).forEach(([key, label]) => {
    console.log(`${key}: ${label}`); // "white: White", etc.
  });
</script>
```

---

### Component API

#### `Theme` props

| Prop               | Type                                                                                                       | Description                                                                                                                     | Default                                                                                                                               |
| ------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `theme` (Reactive) | `CarbonTheme`                                                                                              | Set the current Carbon theme.                                                                                                   | `"white"`                                                                                                                             |
| `tokens`           | `{ [token: string]: any; }`                                                                                | Customize a theme with your own tokens.<br />@see https://carbondesignsystem.com/guidelines/themes/overview#customizing-a-theme | `{}`                                                                                                                                  |
| `persist`          | `boolean`                                                                                                  | Set to `true` to persist the theme using window.localStorage                                                                    | `false`                                                                                                                               |
| `persistKey`       | `string`                                                                                                   | Specify the local storage key                                                                                                   | `"theme"`                                                                                                                             |
| `render`           | `"toggle" \| "select"`                                                                                     | Render a toggle or select dropdown to control the theme.                                                                        | _undefined_                                                                                                                           |
| `toggle`           | `import("../Toggle/Toggle.svelte").ToggleProps & { themes?: [labelA: CarbonTheme, labelB: CarbonTheme]; }` | Override the default toggle props.                                                                                              | `{<br /> themes: ["white", "g100"],<br /> labelA: "",<br /> labelB: "",<br /> labelText: "Dark mode",<br /> hideLabel: false,<br />}` |
| `select`           | `import("../Select/Select.svelte").SelectProps<CarbonTheme> & { themes?: CarbonTheme[]; }`                 | Override the default select props.                                                                                              | `{<br /> themes: themeKeys,<br /> labelText: "Themes",<br /> hideLabel: false,<br />}`                                                |

#### `Theme` typedefs

```ts
type CarbonTheme = "white" | "g10" | "g80" | "g90" | "g100";
```

#### `Theme` slots

| Slot      | Detail                   |
| --------- | ------------------------ |
| `default` | `{ theme: CarbonTheme }` |

#### `Theme` dispatched events

| Event       | Detail                               |
| ----------- | ------------------------------------ |
| `on:update` | `{<br /> theme: CarbonTheme;<br />}` |


## Tile

Tiles provide a container for displaying content in a structured, card-like
format. They support light and dark variants and can be used to create
consistent, visually distinct content sections.

### Default

Create a basic tile container for your content.

```svelte
<script>
  import { Tile } from "carbon-components-svelte";
</script>

<Tile>Content</Tile>
```

### Light variant

Use the light variant for light-themed backgrounds by setting `light` to `true`.

```svelte
<script>
  import { Tile } from "carbon-components-svelte";
</script>

<Tile light>Content</Tile>
```

---

### Component API

#### `Tile` props

| Prop    | Type      | Description                               | Default |
| ------- | --------- | ----------------------------------------- | ------- |
| `light` | `boolean` | Set to `true` to enable the light variant | `false` |

#### `Tile` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `Tile` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `Tile` $$restProps

`Tile` spreads `$$restProps` to the `div` element.


## TimePicker

Time pickers provide a time input field with optional period (AM/PM) and
timezone selectors. They support various sizes, states, and themes to match your
application's design system.

### Default

Create a time picker with period (AM/PM) and timezone selectors.

```svelte
<script>
  import {
    SelectItem,
    TimePicker,
    TimePickerSelect,
  } from "carbon-components-svelte";
</script>

<TimePicker labelText="Cron job" placeholder="hh:mm">
  <TimePickerSelect value="pm">
    <SelectItem value="am" text="AM" />
    <SelectItem value="pm" text="PM" />
  </TimePickerSelect>
  <TimePickerSelect value="pdt">
    <SelectItem value="pdt" text="PDT" />
    <SelectItem value="gmt" text="GMT" />
  </TimePickerSelect>
</TimePicker>
```

### Light variant

Use the light variant for light-themed backgrounds by setting `light` to `true`.

```svelte
<script>
  import {
    SelectItem,
    TimePicker,
    TimePickerSelect,
  } from "carbon-components-svelte";
</script>

<TimePicker light labelText="Cron job" placeholder="hh:mm">
  <TimePickerSelect value="pm">
    <SelectItem value="am" text="AM" />
    <SelectItem value="pm" text="PM" />
  </TimePickerSelect>
  <TimePickerSelect value="pdt">
    <SelectItem value="pdt" text="PDT" />
    <SelectItem value="gmt" text="GMT" />
  </TimePickerSelect>
</TimePicker>
```

### Extra-large size

Use the extra-large size for more prominent time pickers by setting `size` to
`"xl"`.

```svelte
<script>
  import {
    SelectItem,
    TimePicker,
    TimePickerSelect,
  } from "carbon-components-svelte";
</script>

<TimePicker size="xl" labelText="Cron job" placeholder="hh:mm">
  <TimePickerSelect value="pm">
    <SelectItem value="am" text="AM" />
    <SelectItem value="pm" text="PM" />
  </TimePickerSelect>
  <TimePickerSelect value="pdt">
    <SelectItem value="pdt" text="PDT" />
    <SelectItem value="gmt" text="GMT" />
  </TimePickerSelect>
</TimePicker>
```

### Small size

Use the small size for more compact time pickers by setting `size` to `"sm"`.

```svelte
<script>
  import {
    SelectItem,
    TimePicker,
    TimePickerSelect,
  } from "carbon-components-svelte";
</script>

<TimePicker size="sm" labelText="Cron job" placeholder="hh:mm">
  <TimePickerSelect value="pm">
    <SelectItem value="am" text="AM" />
    <SelectItem value="pm" text="PM" />
  </TimePickerSelect>
  <TimePickerSelect value="pdt">
    <SelectItem value="pdt" text="PDT" />
    <SelectItem value="gmt" text="GMT" />
  </TimePickerSelect>
</TimePicker>
```

### Invalid state

Indicate an invalid state with an error message by setting `invalid` to `true`
and providing `invalidText`.

```svelte
<script>
  import {
    SelectItem,
    TimePicker,
    TimePickerSelect,
  } from "carbon-components-svelte";
</script>

<TimePicker
  invalid
  invalidText="A valid value is required"
  labelText="Cron job"
  placeholder="hh:mm"
>
  <TimePickerSelect value="pm">
    <SelectItem value="am" text="AM" />
    <SelectItem value="pm" text="PM" />
  </TimePickerSelect>
  <TimePickerSelect value="pdt">
    <SelectItem value="pdt" text="PDT" />
    <SelectItem value="gmt" text="GMT" />
  </TimePickerSelect>
</TimePicker>
```

### Disabled state

Disable the time picker to prevent user interaction by setting `disabled` to
`true`.

```svelte
<script>
  import {
    SelectItem,
    TimePicker,
    TimePickerSelect,
  } from "carbon-components-svelte";
</script>

<TimePicker labelText="Cron job" placeholder="hh:mm" disabled>
  <TimePickerSelect value="pm" disabled>
    <SelectItem value="am" text="AM" />
    <SelectItem value="pm" text="PM" />
  </TimePickerSelect>
  <TimePickerSelect value="pdt" disabled>
    <SelectItem value="pdt" text="PDT" />
    <SelectItem value="gmt" text="GMT" />
  </TimePickerSelect>
</TimePicker>
```

---

### Component API

#### `TimePicker` props

| Prop               | Type                       | Description                                           | Default                              |
| ------------------ | -------------------------- | ----------------------------------------------------- | ------------------------------------ |
| `value` (Reactive) | `string`                   | Specify the input value.                              | `""`                                 |
| `ref` (Reactive)   | `null \| HTMLInputElement` | Obtain a reference to the input HTML element          | `null`                               |
| `size`             | `"sm" \| "xl"`             | Specify the size of the input.                        | _undefined_                          |
| `placeholder`      | `string`                   | Specify the input placeholder text                    | `"hh:mm"`                            |
| `pattern`          | `string`                   | Specify the `pattern` attribute for the input element | `"(1[012]\|[1-9]):[0-5][0-9](\\s)?"` |
| `maxlength`        | `number`                   | Specify the `maxlength` input attribute               | `5`                                  |
| `light`            | `boolean`                  | Set to `true` to enable the light variant             | `false`                              |
| `disabled`         | `boolean`                  | Set to `true` to disable the input                    | `false`                              |
| `labelText`        | `string`                   | Specify the label text                                | `""`                                 |
| `hideLabel`        | `boolean`                  | Set to `true` to visually hide the label text         | `false`                              |
| `invalid`          | `boolean`                  | Set to `true` to indicate an invalid state            | `false`                              |
| `invalidText`      | `string`                   | Specify the invalid state text                        | `""`                                 |
| `id`               | `string`                   | Set an id for the input element                       | `ccs-${Math.random().toString(36)}`  |
| `name`             | `string`                   | Specify a name attribute for the input.               | _undefined_                          |

#### `TimePicker` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `default`       | `Record<string, never>` |
| `labelChildren` | `Record<string, never>` |

#### `TimePicker` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:change`     |
| `on:input`      |
| `on:keydown`    |
| `on:keyup`      |
| `on:focus`      |
| `on:blur`       |
| `on:paste`      |

#### `TimePicker` $$restProps

`TimePicker` spreads `$$restProps` to the `input` element.

#### `TimePickerSelect` props

| Prop               | Type                        | Description                                      | Default                             |
| ------------------ | --------------------------- | ------------------------------------------------ | ----------------------------------- |
| `value` (Reactive) | `number \| string`          | Specify the select value.                        | `""`                                |
| `ref` (Reactive)   | `null \| HTMLSelectElement` | Obtain a reference to the select HTML element    | `null`                              |
| `disabled`         | `boolean`                   | Set to `true` to disable the select              | `false`                             |
| `iconDescription`  | `string`                    | Specify the ARIA label for the chevron icon      | `"Open list of options"`            |
| `labelText`        | `string`                    | Specify the label text                           | `""`                                |
| `id`               | `string`                    | Set an id for the select element                 | `ccs-${Math.random().toString(36)}` |
| `name`             | `string`                    | Specify a name attribute for the select element. | _undefined_                         |

#### `TimePickerSelect` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `default`       | `Record<string, never>` |
| `labelChildren` | `Record<string, never>` |

#### `TimePickerSelect` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `TimePickerSelect` $$restProps

`TimePickerSelect` spreads `$$restProps` to the `div` element.

#### `SelectItem` props

| Prop       | Type      | Description                                                                         | Default     |
| ---------- | --------- | ----------------------------------------------------------------------------------- | ----------- |
| `value`    | `Value`   | Specify the option value.                                                           | `""`        |
| `text`     | `string`  | Specify the option text.<br />If not specified, the value will be used as the text. | _undefined_ |
| `hidden`   | `boolean` | Set to `true` to hide the option                                                    | `false`     |
| `disabled` | `boolean` | Set to `true` to disable the option                                                 | `false`     |
| `class`    | `string`  | Specify the class of the `option` element.                                          | _undefined_ |
| `style`    | `string`  | Specify the style of the `option` element.                                          | _undefined_ |


## ToastNotification

Toast notifications display non-modal, time-based messages that appear at the
top of the screen and automatically disappear. They support various notification
types, custom content, and accessibility features.

For an imperative API to manage multiple toast notifications with automatic
queue management, see [NotificationQueue](NotificationQueue).

See
[detailed usage](https://carbondesignsystem.com/components/notification/usage).  
See also: [InlineNotification](InlineNotification)

### Default

Display a basic error notification with title, subtitle, and timestamp by
default.

```svelte
<script>
  import { ToastNotification } from "carbon-components-svelte";
</script>

<ToastNotification
  title="Error"
  subtitle="An internal server error occurred."
  caption={new Date().toLocaleString()}
/>
```

### Autoclose

Specify the `timeout` prop to automatically close the notification after a
specified duration (in milliseconds).

```svelte
<script>
  import { Button, ToastNotification } from "carbon-components-svelte";
  import { fade } from "svelte/transition";

  let timeout = undefined;
  $: showNotification = timeout !== undefined;
</script>

<Button
  disabled={showNotification}
  on:click={() => {
    timeout = 3_000; // 3 seconds
  }}
>
  Show notification
</Button>

{#if showNotification}
  <div transition:fade>
    <ToastNotification
      {timeout}
      kind="success"
      title="Success"
      subtitle="This notification will autoclose in {timeout.toLocaleString()} ms."
      caption={new Date().toLocaleString()}
      on:close={(e) => {
        timeout = undefined;
        console.log(e.detail.timeout); // true if closed via timeout
      }}
    />
  </div>
{/if}
```

### Prevent default close behavior

Prevent the default close behavior using `e.preventDefault()` in the `on:close`
event handler.

```svelte
<script>
  import { ToastNotification } from "carbon-components-svelte";
</script>

<ToastNotification
  title="Error"
  subtitle="An internal server error occurred."
  caption={new Date().toLocaleString()}
  on:close={(e) => {
    e.preventDefault();
    // custom close logic (e.g., transitions)
  }}
/>

## Reusable notification Control the notification visibility by binding to the
`open` prop. This allows you to show, hide, and reuse the same notification
component with different messages. The `open` prop defaults to `true`.
```

```svelte
<script>
  import {
    Button,
    ButtonSet,
    Stack,
    ToastNotification,
  } from "carbon-components-svelte";

  let open = false;
  let kind = "error";
  let title = "Error";
  let subtitle = "An internal server error occurred.";
  let caption = new Date().toLocaleString();

  function showError() {
    kind = "error";
    title = "Error";
    subtitle = "An internal server error occurred.";
    caption = new Date().toLocaleString();
    open = true;
  }

  function showSuccess() {
    kind = "success";
    title = "Success";
    subtitle = "Your settings have been saved.";
    caption = new Date().toLocaleString();
    open = true;
  }

  function showWarning() {
    kind = "warning";
    title = "Warning";
    subtitle = "Please review your changes before continuing.";
    caption = new Date().toLocaleString();
    open = true;
  }
</script>

<Stack gap={5}>
  <ButtonSet>
    <Button on:click={showSuccess}>Show success</Button>
    <Button kind="ghost" on:click={showWarning}>Show warning</Button>
    <Button kind="danger-ghost" on:click={showError}>Show error</Button>
  </ButtonSet>

  <ToastNotification bind:open {kind} {title} {subtitle} {caption} />
</Stack>
```

### Full width

Set `fullWidth` to `true` for the notification to span the full width of its
container.

```svelte
<script>
  import { ToastNotification } from "carbon-components-svelte";
</script>

<ToastNotification
  fullWidth
  title="Error"
  subtitle="An internal server error occurred."
  caption={new Date().toLocaleString()}
/>
```

### Slottable title, subtitle, caption

Customize the notification content using slots for more flexibility.

```svelte
<script>
  import { ToastNotification } from "carbon-components-svelte";
</script>

<ToastNotification>
  <strong slot="titleChildren">Error: </strong>
  <strong slot="subtitleChildren">An internal server error occurred.</strong>
  <strong slot="captionChildren">{new Date().toLocaleString()}</strong>
</ToastNotification>
```

### Optional subtitle and caption

Subtitle and caption are optional and only render when provided.

```svelte
<script>
  import { ToastNotification } from "carbon-components-svelte";
</script>

<ToastNotification subtitle="An internal server error occurred." />
<ToastNotification
  title="Error"
  subtitle="An internal server error occurred."
/>
<ToastNotification
  subtitle="An internal server error occurred."
  caption={new Date().toLocaleString()}
/>
<ToastNotification title="Success" caption={new Date().toLocaleString()} />
```

### Accessible icon descriptions

Provide custom descriptions for icons to improve accessibility.

```svelte
<script>
  import { ToastNotification } from "carbon-components-svelte";
</script>

<ToastNotification
  title="错误"
  subtitle="发生内部服务器错误"
  statusIconDescription="错误图标"
  closeButtonDescription="关闭通知"
/>
```

### Hidden close button

Create a persistent notification by hiding the close button.

```svelte
<script>
  import { ToastNotification } from "carbon-components-svelte";
</script>

<ToastNotification
  hideCloseButton
  kind="warning"
  title="Scheduled maintenance"
  subtitle="Maintenance will last 2-4 hours."
  caption={new Date().toLocaleString()}
/>
```

### Notification variants

The component supports different notification types:

```svelte
<script>
  import { ToastNotification } from "carbon-components-svelte";
</script>

<ToastNotification
  kind="error"
  title="Error"
  subtitle="An internal server error occurred."
  caption={new Date().toLocaleString()}
/>
<ToastNotification
  kind="info"
  title="New updates"
  subtitle="Restart to get the latest updates."
  caption={new Date().toLocaleString()}
/>
<ToastNotification
  kind="info-square"
  title="New updates"
  subtitle="Restart to get the latest updates."
  caption={new Date().toLocaleString()}
/>
<ToastNotification
  kind="success"
  title="Success"
  subtitle="Your settings have been saved."
  caption={new Date().toLocaleString()}
/>
<ToastNotification
  kind="warning"
  title="Scheduled maintenance"
  subtitle="Maintenance will last 2-4 hours."
  caption={new Date().toLocaleString()}
/>
<ToastNotification
  kind="warning-alt"
  title="Scheduled maintenance"
  subtitle="Maintenance will last 2-4 hours."
  caption={new Date().toLocaleString()}
/>
```

### Low contrast

Use low contrast variants for less prominent notifications.

```svelte
<script>
  import { ToastNotification } from "carbon-components-svelte";
</script>

<ToastNotification
  lowContrast
  kind="error"
  title="Error"
  subtitle="An internal server error occurred."
  caption={new Date().toLocaleString()}
/>
<ToastNotification
  lowContrast
  kind="info"
  title="New updates"
  subtitle="Restart to get the latest updates."
  caption={new Date().toLocaleString()}
/>
<ToastNotification
  lowContrast
  kind="info-square"
  title="New updates"
  subtitle="Restart to get the latest updates."
  caption={new Date().toLocaleString()}
/>
<ToastNotification
  lowContrast
  kind="success"
  title="Success"
  subtitle="Your settings have been saved."
  caption={new Date().toLocaleString()}
/>
<ToastNotification
  lowContrast
  kind="warning"
  title="Scheduled maintenance"
  subtitle="Maintenance will last 2-4 hours."
  caption={new Date().toLocaleString()}
/>
<ToastNotification
  lowContrast
  kind="warning-alt"
  title="Scheduled maintenance"
  subtitle="Maintenance will last 2-4 hours."
  caption={new Date().toLocaleString()}
/>
```

---

### Component API

#### `ToastNotification` props

| Prop                     | Type                                                                            | Description                                                                               | Default                |
| ------------------------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------- |
| `open` (Reactive)        | `boolean`                                                                       | Set to `true` to show the notification, `false` to hide it.                               | `true`                 |
| `kind`                   | `"error" \| "info" \| "info-square" \| "success" \| "warning" \| "warning-alt"` | Specify the kind of notification.                                                         | `"error"`              |
| `lowContrast`            | `boolean`                                                                       | Set to `true` to use the low contrast variant                                             | `false`                |
| `timeout`                | `number`                                                                        | Set the timeout duration (ms) to hide the notification after opening it                   | `0`                    |
| `role`                   | `string`                                                                        | Set the `role` attribute                                                                  | `"alert"`              |
| `title`                  | `string`                                                                        | Specify the title text                                                                    | `""`                   |
| `subtitle`               | `string`                                                                        | Specify the subtitle text                                                                 | `""`                   |
| `caption`                | `string`                                                                        | Specify the caption text                                                                  | `""`                   |
| `statusIconDescription`  | `string`                                                                        | Specify the ARIA label for the status icon.                                               | `${kind} icon`         |
| `closeButtonDescription` | `string`                                                                        | Specify the ARIA label for the close button                                               | `"Close notification"` |
| `hideCloseButton`        | `boolean`                                                                       | Set to `true` to hide the close button                                                    | `false`                |
| `fullWidth`              | `boolean`                                                                       | Set to `true` for the notification to span<br />the full width of its containing element. | `false`                |

#### `ToastNotification` slots

| Slot               | Detail                  |
| ------------------ | ----------------------- |
| `default`          | `Record<string, never>` |
| `captionChildren`  | `Record<string, never>` |
| `subtitleChildren` | `Record<string, never>` |
| `titleChildren`    | `Record<string, never>` |

#### `ToastNotification` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `ToastNotification` dispatched events

| Event      | Detail                             |
| ---------- | ---------------------------------- |
| `on:close` | `{<br /> timeout: boolean;<br />}` |

#### `ToastNotification` $$restProps

`ToastNotification` spreads `$$restProps` to the `div` element.


## Toggle

Toggles provide a switch-like control that allows users to turn options on or
off. They support custom labels, different sizes, and various states to match
your application's needs.

### Default

Display a basic toggle in its untoggled state by default.

```svelte
<script>
  import { Toggle } from "carbon-components-svelte";
</script>

<Toggle labelText="Push notifications" />
```

### Toggled

Set `toggled` to `true` to display the toggle in its on state.

```svelte
<script>
  import { Toggle } from "carbon-components-svelte";
</script>

<Toggle labelText="Push notifications" toggled />
```

### Reactive example

Use two-way binding to control the toggle state programmatically.

```svelte
<script>
  import { Button, Toggle } from "carbon-components-svelte";

  let toggled = true;
</script>

<Toggle labelText="Push notifications" bind:toggled />

<div>
  <Button size="small" on:click={() => (toggled = !toggled)}>
    Toggle
    {toggled ? "off" : "on"}
  </Button>
</div>

<div>Toggled: {toggled}</div>

<style>
  div {
    margin-top: var(--cds-spacing-05);
  }
</style>
```

### on:toggle event

Listen for toggle state changes using the `on:toggle` event.

```svelte
<script>
  import { Toggle, ToggleSkeleton } from "carbon-components-svelte";
</script>

<Toggle
  labelText="Push notifications"
  on:toggle={(e) => console.log(e.detail)}
/>

## Hidden label text Set `hideLabel` to `true` to visually hide the label while
maintaining accessibility.

<Toggle labelText="Push notifications" hideLabel />

## Custom labels Customize the toggle labels using `labelA` and `labelB` props.

<Toggle labelText="Push notifications" labelA="No" labelB="Yes" />

## Slottable labels Use slots to customize the toggle labels with additional
styling or content.

<Toggle labelText="Push notifications">
  <span slot="labelA" style="color: red">No</span>
  <span slot="labelB" style="color: green">Yes</span>
</Toggle>

## Disabled state Set `disabled` to `true` to prevent user interaction.

<Toggle labelText="Push notifications" disabled />

## Small size Use the small size variant by setting `size` to `"sm"`.

<Toggle size="sm" labelText="Push notifications" />

## Skeleton Display a loading state using the skeleton component.

<ToggleSkeleton />

## Skeleton (small) Use the small size variant for the skeleton component.

<ToggleSkeleton size="sm" />
```

---

### Component API

#### `Toggle` props

| Prop                 | Type                       | Description                                      | Default                             |
| -------------------- | -------------------------- | ------------------------------------------------ | ----------------------------------- |
| `toggled` (Reactive) | `boolean`                  | Set to `true` to toggle the checkbox input       | `false`                             |
| `ref` (Reactive)     | `null \| HTMLInputElement` | Obtain a reference to the input HTML element     | `null`                              |
| `size`               | `"default" \| "sm"`        | Specify the toggle size.                         | `"default"`                         |
| `disabled`           | `boolean`                  | Set to `true` to disable checkbox input          | `false`                             |
| `labelA`             | `string`                   | Specify the label for the untoggled state        | `"Off"`                             |
| `labelB`             | `string`                   | Specify the label for the toggled state          | `"On"`                              |
| `labelText`          | `string`                   | Specify the label text                           | `""`                                |
| `hideLabel`          | `boolean`                  | Set to `true` to visually hide the label text    | `false`                             |
| `id`                 | `string`                   | Set an id for the input element                  | `ccs-${Math.random().toString(36)}` |
| `name`               | `string`                   | Specify a name attribute for the checkbox input. | _undefined_                         |

#### `Toggle` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `labelA`        | `Record<string, never>` |
| `labelB`        | `Record<string, never>` |
| `labelChildren` | `Record<string, never>` |

#### `Toggle` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:change`     |
| `on:keyup`      |
| `on:focus`      |
| `on:blur`       |

#### `Toggle` dispatched events

| Event       | Detail                 |
| ----------- | ---------------------- |
| `on:toggle` | `{ toggled: boolean }` |

#### `Toggle` $$restProps

`Toggle` spreads `$$restProps` to the `div` element.

#### `ToggleSkeleton` props

| Prop        | Type                | Description                     | Default                             |
| ----------- | ------------------- | ------------------------------- | ----------------------------------- |
| `size`      | `"default" \| "sm"` | Specify the toggle size.        | `"default"`                         |
| `labelText` | `string`            | Specify the label text          | `""`                                |
| `id`        | `string`            | Set an id for the input element | `ccs-${Math.random().toString(36)}` |

#### `ToggleSkeleton` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `labelChildren` | `Record<string, never>` |

#### `ToggleSkeleton` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `ToggleSkeleton` $$restProps

`ToggleSkeleton` spreads `$$restProps` to the `div` element.


## Toolbar

Toolbars provide a flexible container for organizing actions, search, and menu
items. They can be used standalone or as part of a data table for batch
operations and filtering.

### Default

Create a basic toolbar with content inside toolbar content.

```svelte
<script>
  import { Button, Toolbar, ToolbarContent } from "carbon-components-svelte";
</script>

<Toolbar>
  <ToolbarContent>
    <Button>Primary action</Button>
  </ToolbarContent>
</Toolbar>
```

### Small size

Set `size="sm"` for a compact toolbar.

```svelte
<script>
  import { Button, Toolbar, ToolbarContent } from "carbon-components-svelte";
</script>

<Toolbar size="sm">
  <ToolbarContent>
    <Button size="small">Create</Button>
  </ToolbarContent>
</Toolbar>
```

### With search

Add search functionality using toolbar search.

```svelte
<script>
  import {
    Button,
    Toolbar,
    ToolbarContent,
    ToolbarSearch,
  } from "carbon-components-svelte";
</script>

<Toolbar>
  <ToolbarContent>
    <ToolbarSearch />
    <Button>Create</Button>
  </ToolbarContent>
</Toolbar>
```

### With persistent search

Set `persistent` on toolbar search to keep it always expanded.

```svelte
<script>
  import {
    Button,
    Toolbar,
    ToolbarContent,
    ToolbarSearch,
  } from "carbon-components-svelte";
</script>

<Toolbar>
  <ToolbarContent>
    <ToolbarSearch persistent placeholder="Search..." />
    <Button>Create</Button>
  </ToolbarContent>
</Toolbar>
```

### Reactive search

Bind to the `value` prop for reactive updates.

```svelte
<script>
  import {
    Button,
    ButtonSet,
    Toolbar,
    ToolbarContent,
    ToolbarSearch,
  } from "carbon-components-svelte";

  let value = "";
</script>

<Toolbar>
  <ToolbarContent>
    <ToolbarSearch bind:value placeholder="Search..." />
    <Button size="small">Create</Button>
  </ToolbarContent>
</Toolbar>

<div>
  <ButtonSet>
    <Button
      size="small"
      disabled={value === "products"}
      on:click={() => (value = "products")}
    >
      Set value
    </Button>
    <Button
      kind="ghost"
      size="small"
      disabled={value.length === 0}
      on:click={() => (value = "")}
    >
      Clear value
    </Button>
  </ButtonSet>
</div>

<div>Search value: {value}</div>

<style>
  div {
    margin-top: var(--cds-spacing-05);
  }
</style>
```

### With menu

Add an overflow menu using toolbar menu and toolbar menu item.

```svelte
<script>
  import {
    Button,
    Toolbar,
    ToolbarContent,
    ToolbarMenu,
    ToolbarMenuItem,
  } from "carbon-components-svelte";
</script>

<Toolbar>
  <ToolbarContent>
    <ToolbarMenu>
      <ToolbarMenuItem>Restart all</ToolbarMenuItem>
      <ToolbarMenuItem href="https://cloud.ibm.com/docs"
        >API documentation</ToolbarMenuItem
      >
      <ToolbarMenuItem>Settings</ToolbarMenuItem>
    </ToolbarMenu>
    <Button>Create</Button>
  </ToolbarContent>
</Toolbar>
```

### Menu with divider and danger item

Use `hasDivider` to add a separator and `danger` for destructive actions.

```svelte
<script>
  import {
    Toolbar,
    ToolbarContent,
    ToolbarMenu,
    ToolbarMenuItem,
  } from "carbon-components-svelte";
</script>

<Toolbar>
  <ToolbarContent>
    <ToolbarMenu>
      <ToolbarMenuItem>Restart all</ToolbarMenuItem>
      <ToolbarMenuItem href="https://cloud.ibm.com/docs"
        >API documentation</ToolbarMenuItem
      >
      <ToolbarMenuItem hasDivider danger>Stop all</ToolbarMenuItem>
    </ToolbarMenu>
  </ToolbarContent>
</Toolbar>
```

### Menu with primary focus

Set `primaryFocus` on a menu item to focus it when opening the dropdown.

```svelte
<script>
  import {
    Toolbar,
    ToolbarContent,
    ToolbarMenu,
    ToolbarMenuItem,
  } from "carbon-components-svelte";
</script>

<Toolbar>
  <ToolbarContent>
    <ToolbarMenu>
      <ToolbarMenuItem>Restart all</ToolbarMenuItem>
      <ToolbarMenuItem href="https://cloud.ibm.com/docs"
        >API documentation</ToolbarMenuItem
      >
      <ToolbarMenuItem primaryFocus hasDivider danger>Stop all</ToolbarMenuItem>
    </ToolbarMenu>
  </ToolbarContent>
</Toolbar>
```

### Complete toolbar

Combine search, menu, and buttons for a full-featured toolbar.

```svelte
<script>
  import {
    Button,
    Toolbar,
    ToolbarContent,
    ToolbarMenu,
    ToolbarMenuItem,
    ToolbarSearch,
  } from "carbon-components-svelte";
</script>

<Toolbar>
  <ToolbarContent>
    <ToolbarSearch />
    <ToolbarMenu>
      <ToolbarMenuItem primaryFocus>Restart all</ToolbarMenuItem>
      <ToolbarMenuItem href="https://cloud.ibm.com/docs/loadbalancer-service">
        API documentation
      </ToolbarMenuItem>
      <ToolbarMenuItem hasDivider danger>Stop all</ToolbarMenuItem>
    </ToolbarMenu>
    <Button>Create balancer</Button>
  </ToolbarContent>
</Toolbar>
```

### With multiple actions

Stack multiple action buttons in the toolbar.

```svelte
<script>
  import {
    Button,
    Toolbar,
    ToolbarContent,
    ToolbarSearch,
  } from "carbon-components-svelte";
</script>

<Toolbar>
  <ToolbarContent>
    <ToolbarSearch persistent />
    <Button kind="secondary" size="small">Export</Button>
    <Button size="small">Create</Button>
  </ToolbarContent>
</Toolbar>
```

### Standalone usage

> [!NOTE] > **Toolbar** can be used independently of DataTable. It provides its
> own context for child components like **ToolbarMenu** and **ToolbarSearch**.

The toolbar components work standalone for general-purpose layouts:

```svelte
<script>
  import {
    Button,
    Toolbar,
    ToolbarContent,
    ToolbarMenu,
    ToolbarMenuItem,
    ToolbarSearch,
  } from "carbon-components-svelte";
</script>

<Toolbar>
  <ToolbarContent>
    <ToolbarSearch placeholder="Search products..." />
    <ToolbarMenu>
      <ToolbarMenuItem>Filter by category</ToolbarMenuItem>
      <ToolbarMenuItem>Sort by price</ToolbarMenuItem>
    </ToolbarMenu>
    <Button>Add product</Button>
  </ToolbarContent>
</Toolbar>
```

### Batch actions

Toolbar batch actions display batch actions when items are selected.

Although intended for use with [DataTable](/components/datatable), this
component can be used standalone if `selectedIds` is provided. This prop does
not need to be provided if using with a data table.

```svelte
<script>
  import {
    Button,
    Checkbox,
    Toolbar,
    ToolbarBatchActions,
    ToolbarContent,
  } from "carbon-components-svelte";
  import Add from "carbon-icons-svelte/lib/Add.svelte";
  import TrashCan from "carbon-icons-svelte/lib/TrashCan.svelte";

  let items = [
    { id: 1, name: "Item 1", checked: false },
    { id: 2, name: "Item 2", checked: false },
    { id: 3, name: "Item 3", checked: false },
  ];
  let nextId = items.length + 1;

  $: selectedIds = items.filter((item) => item.checked).map((item) => item.id);
</script>

<Toolbar>
  <ToolbarBatchActions
    {selectedIds}
    on:cancel={() => {
      items = items.map((item) => ({ ...item, checked: false }));
    }}
  >
    <Button
      kind="danger"
      icon={TrashCan}
      on:click={() => {
        items = items.filter((item) => !item.checked);
      }}
    >
      Delete
    </Button>
  </ToolbarBatchActions>
  <ToolbarContent>
    <Button
      icon={Add}
      size="small"
      on:click={() => {
        items = [
          ...items,
          { id: nextId, name: "Item " + nextId, checked: false },
        ];
        nextId++;
      }}
    >
      Add item
    </Button>
  </ToolbarContent>
</Toolbar>

<div style:margin-top="var(--cds-layout-02)">
  {#each items as item (item.id)}
    <Checkbox labelText={item.name} bind:checked={item.checked} />
  {/each}
</div>
```

---

### Component API

#### `Toolbar` props

| Prop   | Type                | Description               | Default     |
| ------ | ------------------- | ------------------------- | ----------- |
| `size` | `"sm" \| "default"` | Specify the toolbar size. | `"default"` |

#### `Toolbar` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `Toolbar` $$restProps

`Toolbar` spreads `$$restProps` to the `section` element.

#### `ToolbarContent` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ToolbarSearch` props

| Prop                        | Type                                                          | Description                                                                                                                                                                                                                                                                                                                                     | Default |
| --------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `value` (Reactive)          | `number \| string`                                            | Specify the value of the search input.                                                                                                                                                                                                                                                                                                          | `""`    |
| `expanded` (Reactive)       | `boolean`                                                     | Set to `true` to expand the search bar                                                                                                                                                                                                                                                                                                          | `false` |
| `filteredRowIds` (Reactive) | `ReadonlyArray<Row["id"]>`                                    | The filtered row ids.                                                                                                                                                                                                                                                                                                                           | `[]`    |
| `ref` (Reactive)            | `null \| HTMLInputElement`                                    | Obtain a reference to the input HTML element.                                                                                                                                                                                                                                                                                                   | `null`  |
| `persistent`                | `boolean`                                                     | Set to `true` to keep the search bar expanded                                                                                                                                                                                                                                                                                                   | `false` |
| `disabled`                  | `boolean`                                                     | Set to `true` to disable the search bar                                                                                                                                                                                                                                                                                                         | `false` |
| `shouldFilterRows`          | `boolean \| ((row: Row, value: number \| string) => boolean)` | Set to `true` to filter table rows using the search value.<br /><br />If `true`, the default search excludes `id`, `cells` fields and<br />only does a basic comparison on string and number type cell values.<br /><br />To implement your own client-side filtering, pass a function<br />that accepts a row and value and returns a boolean. | `false` |
| `tabindex`                  | `string`                                                      | Specify the tabindex                                                                                                                                                                                                                                                                                                                            | `"0"`   |

#### `ToolbarSearch` forwarded events

| Event        |
| ------------ |
| `on:clear`   |
| `on:change`  |
| `on:input`   |
| `on:focus`   |
| `on:blur`    |
| `on:keyup`   |
| `on:keydown` |
| `on:paste`   |

#### `ToolbarSearch` $$restProps

`ToolbarSearch` spreads `$$restProps` to the `input` element.

#### `ToolbarMenu` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ToolbarMenu` $$restProps

`ToolbarMenu` spreads `$$restProps` to the `OverflowMenu` component.

#### `ToolbarMenuItem` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ToolbarMenuItem` forwarded events

| Event        |
| ------------ |
| `on:click`   |
| `on:keydown` |

#### `ToolbarMenuItem` $$restProps

`ToolbarMenuItem` spreads `$$restProps` to the `OverflowMenuItem` component.

#### `ToolbarBatchActions` props

| Prop                  | Type                                | Description                                                                                                       | Default     |
| --------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------- |
| `active` (Reactive)   | `undefined \| boolean`              | Use a boolean to show or hide the toolbar.                                                                        | _undefined_ |
| `formatTotalSelected` | `(totalSelected: number) => string` | Override the total items selected text.                                                                           | _undefined_ |
| `selectedIds`         | `ReadonlyArray<any>`                | Specify the selected IDs for standalone usage.<br />This is unnecessary if using this component with `DataTable`. | `[]`        |

#### `ToolbarBatchActions` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |
| `cancel`  | `Record<string, never>` |

#### `ToolbarBatchActions` dispatched events

| Event       | Detail |
| ----------- | ------ |
| `on:cancel` | `null` |

#### `ToolbarBatchActions` $$restProps

`ToolbarBatchActions` spreads `$$restProps` to the `div` element.


## Tooltip

Tooltips display contextual information when users hover over or focus on an
element. They support various directions, alignments, and interactive content to
provide additional context or guidance.

### Default

Display a tooltip triggered by the default information icon.

```svelte
<script>
  import { Tooltip } from "carbon-components-svelte";
</script>

<Tooltip>
  <p>Resources are provisioned based on your account's organization.</p>
</Tooltip>
```

### With trigger text

Use custom trigger text instead of the default icon.

```svelte
<script>
  import { Tooltip } from "carbon-components-svelte";
</script>

<Tooltip triggerText="Resource list">
  <p>Resources are provisioned based on your account's organization.</p>
</Tooltip>
```

### Reactive example

Control the tooltip state programmatically.

```svelte
<script>
  import { Button, Tooltip } from "carbon-components-svelte";

  let open = true;
</script>

<Tooltip bind:open triggerText="Resource list" align="start">
  <p>Resources are provisioned based on your account's organization.</p>
</Tooltip>

<div style="margin-top: var(--cds-spacing-12);">
  <Button size="small" on:click={() => (open = !open)}>
    {open ? "Close tooltip" : "Open tooltip"}
  </Button>
</div>

<div>Open: {open}</div>

<style>
  div {
    margin-top: var(--cds-spacing-05);
  }
</style>
```

### Directions

Position the tooltip in different directions using the `direction` prop.

```svelte
<script>
  import { Tooltip } from "carbon-components-svelte";
</script>

<Tooltip triggerText="Top" direction="top"><p>Top</p></Tooltip>
<Tooltip triggerText="Right" direction="right"><p>Right</p></Tooltip>
<Tooltip triggerText="Bottom" direction="bottom"><p>Bottom</p></Tooltip>
<Tooltip triggerText="Left" direction="left"><p>Left</p></Tooltip>
```

### Alignment

Align the tooltip content using the `align` prop.

```svelte
<script>
  import { Tooltip } from "carbon-components-svelte";
</script>

<Tooltip triggerText="Start" align="start"><p>Start</p></Tooltip>
<Tooltip triggerText="End" align="end"><p>End</p></Tooltip>
<Tooltip triggerText="Center" align="center"><p>Center</p></Tooltip>
```

### Interactive

Add interactive elements like links and buttons using the tooltip footer.

```svelte
<script>
  import {
    Button,
    Link,
    Tooltip,
    TooltipFooter,
  } from "carbon-components-svelte";
</script>

<Tooltip triggerText="Resource list">
  <p>Resources are provisioned based on your account's organization.</p>
  <TooltipFooter selectorPrimaryFocus="#d">
    <Link href="/">Learn more</Link>
    <Button id="d" size="small">Manage</Button>
  </TooltipFooter>
</Tooltip>
```

### Custom icon (component)

Use a custom icon component with the `icon` prop.

```svelte
<script>
  import { Tooltip } from "carbon-components-svelte";
  import Catalog from "carbon-icons-svelte/lib/Catalog.svelte";
</script>

<Tooltip triggerText="Resource list" icon={Catalog}>
  <p>Resources are provisioned based on your account's organization.</p>
</Tooltip>
```

### Custom icon (slot)

Customize the icon using the `icon` slot for more flexibility.

```svelte
<script>
  import { Tooltip } from "carbon-components-svelte";
</script>

<Tooltip triggerText="Resource list">
  <div slot="icon" style="width: 1rem; height: 1rem; outline: 1px solid red;" />
  <p>Resources are provisioned based on your account's organization.</p>
</Tooltip>
```

### Custom delay

The tooltip has a hover delay to avoid accidental opening. The default enter
delay is 100ms and default leave delay is 300ms.

Customize the enter and leave delay using `enterDelayMs` and `leaveDelayMs`.

```svelte
<script>
  import { Tooltip } from "carbon-components-svelte";
</script>

<Tooltip triggerText="Slow open" enterDelayMs={500} leaveDelayMs={200}>
  <p>This tooltip has a 500ms enter delay and a 200ms leave delay.</p>
</Tooltip>
```

### Hidden icon

Hide the icon while keeping the tooltip functionality using `hideIcon`.

```svelte
<script>
  import { Tooltip } from "carbon-components-svelte";
</script>

<Tooltip hideIcon triggerText="Resource list">
  <p>Resources are provisioned based on your account's organization.</p>
</Tooltip>
```

---

### Component API

#### `Tooltip` props

| Prop                    | Type                                     | Description                                                                            | Default                             |
| ----------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------- |
| `open` (Reactive)       | `boolean`                                | Set to `true` to open the tooltip.                                                     | `false`                             |
| `ref` (Reactive)        | `null \| HTMLDivElement`                 | Obtain a reference to the trigger text HTML element                                    | `null`                              |
| `refTooltip` (Reactive) | `null \| HTMLDivElement`                 | Obtain a reference to the tooltip HTML element                                         | `null`                              |
| `refIcon` (Reactive)    | `null \| HTMLDivElement`                 | Obtain a reference to the icon HTML element                                            | `null`                              |
| `align`                 | `"start" \| "center" \| "end"`           | Set the alignment of the tooltip relative to the icon.                                 | `"center"`                          |
| `direction`             | `"top" \| "right" \| "bottom" \| "left"` | Set the direction of the tooltip relative to the button.                               | `"bottom"`                          |
| `hideIcon`              | `boolean`                                | Set to `true` to hide the tooltip icon.                                                | `false`                             |
| `icon`                  | `any`                                    | Specify the icon to render for the tooltip button.<br />Defaults to `<Information />`. | `Information`                       |
| `iconDescription`       | `string`                                 | Specify the ARIA label for the tooltip button                                          | `""`                                |
| `iconName`              | `string`                                 | Specify the icon name attribute                                                        | `""`                                |
| `tabindex`              | `string`                                 | Set the button tabindex                                                                | `"0"`                               |
| `tooltipId`             | `string`                                 | Set an id for the tooltip.                                                             | `ccs-${Math.random().toString(36)}` |
| `triggerId`             | `string`                                 | Set an id for the tooltip button.                                                      | `ccs-${Math.random().toString(36)}` |
| `triggerText`           | `string`                                 | Set the tooltip button text                                                            | `""`                                |
| `enterDelayMs`          | `number`                                 | Specify the duration in milliseconds to delay before displaying the tooltip.           | `100`                               |
| `leaveDelayMs`          | `number`                                 | Specify the duration in milliseconds to delay before hiding the tooltip.               | `300`                               |

#### `Tooltip` slots

| Slot          | Detail                  |
| ------------- | ----------------------- |
| `default`     | `Record<string, never>` |
| `icon`        | `Record<string, never>` |
| `triggerText` | `Record<string, never>` |

#### `Tooltip` forwarded events

| Event          |
| -------------- |
| `on:click`     |
| `on:mousedown` |

#### `Tooltip` dispatched events

| Event      | Detail |
| ---------- | ------ |
| `on:open`  | `null` |
| `on:close` | `null` |

#### `Tooltip` $$restProps

`Tooltip` spreads `$$restProps` to the `div` element.

#### `TooltipFooter` props

| Prop                   | Type     | Description                                                                 | Default                             |
| ---------------------- | -------- | --------------------------------------------------------------------------- | ----------------------------------- |
| `selectorPrimaryFocus` | `string` | Specify a selector to be focused inside the footer when opening the tooltip | `"a[href], button:not([disabled])"` |

#### `TooltipFooter` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |


## TooltipDefinition

Tooltip definitions provide inline definitions for terms or concepts. They
display a tooltip when users hover over or focus on the defined term, making
them ideal for providing additional context without cluttering the interface.

### Default

Display a basic definition tooltip with the default bottom-center alignment.

```svelte
<script>
  import { TooltipDefinition } from "carbon-components-svelte";
</script>

<TooltipDefinition
  tooltipText="IBM Corporate Headquarters is based in Armonk, New York."
>
  Armonk
</TooltipDefinition>
```

### Custom tooltip direction and alignment

Customize the tooltip position using the `direction` and `align` props. The
default direction is `"bottom"` and alignment is `"center"`.

```svelte
<script>
  import { TooltipDefinition } from "carbon-components-svelte";
</script>

<TooltipDefinition
  direction="top"
  align="start"
  tooltipText="IBM Corporate Headquarters is based in Armonk, New York."
>
  Armonk
</TooltipDefinition>
```

### Custom tooltip slot

Use the `tooltip` slot to customize the tooltip content with additional styling
or structure.

```svelte
<script>
  import { TooltipDefinition } from "carbon-components-svelte";
</script>

<TooltipDefinition>
  Armonk
  <span slot="tooltip" style="color: red">
    IBM Corporate Headquarters is based in Armonk, New York.
  </span>
</TooltipDefinition>
```

---

### Component API

#### `TooltipDefinition` props

| Prop              | Type                           | Description                                            | Default                             |
| ----------------- | ------------------------------ | ------------------------------------------------------ | ----------------------------------- |
| `open` (Reactive) | `boolean`                      | Set to `true` to open the tooltip.                     | `false`                             |
| `ref` (Reactive)  | `null \| HTMLButtonElement`    | Obtain a reference to the button HTML element          | `null`                              |
| `tooltipText`     | `string`                       | Specify the tooltip text                               | `""`                                |
| `align`           | `"start" \| "center" \| "end"` | Set the alignment of the tooltip relative to the icon. | `"center"`                          |
| `direction`       | `"top" \| "bottom"`            | Set the direction of the tooltip relative to the icon. | `"bottom"`                          |
| `id`              | `string`                       | Set an id for the tooltip div element                  | `ccs-${Math.random().toString(36)}` |

#### `TooltipDefinition` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |
| `tooltip` | `Record<string, never>` |

#### `TooltipDefinition` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:focus`      |

#### `TooltipDefinition` dispatched events

| Event      | Detail |
| ---------- | ------ |
| `on:open`  | `null` |
| `on:close` | `null` |

#### `TooltipDefinition` $$restProps

`TooltipDefinition` spreads `$$restProps` to the `span` element.


## TooltipIcon

Tooltip icons display contextual information when users hover over or focus on
an icon. They are ideal for providing additional context about icons or actions
in your interface.

### Default

Display a tooltip with the default bottom-center alignment.

```svelte
<script>
  import { TooltipIcon } from "carbon-components-svelte";
  import Carbon from "carbon-icons-svelte/lib/Carbon.svelte";
</script>

<TooltipIcon
  tooltipText="Carbon is an open source design system by IBM."
  icon={Carbon}
/>
```

### Sizes

Specify the icon size with the `size` prop. Carbon icons use a 16/20/24/32
scale, but any number (pixels) can be used.

```svelte
<script>
  import { TooltipIcon } from "carbon-components-svelte";
  import Carbon from "carbon-icons-svelte/lib/Carbon.svelte";
</script>

<TooltipIcon tooltipText="16px" icon={Carbon} size={16} />
<TooltipIcon tooltipText="20px" icon={Carbon} size={20} />
<TooltipIcon tooltipText="24px" icon={Carbon} size={24} />
<TooltipIcon tooltipText="32px" icon={Carbon} size={32} />
```

### Directions

Position the tooltip in different directions and alignments using the
`direction` and `align` props.

```svelte
<script>
  import { TooltipIcon } from "carbon-components-svelte";
  import Filter from "carbon-icons-svelte/lib/Filter.svelte";
</script>

<TooltipIcon
  tooltipText="Top start"
  direction="top"
  align="start"
  icon={Filter}
/>
<TooltipIcon
  tooltipText="Right end"
  direction="right"
  align="end"
  icon={Filter}
/>
<TooltipIcon
  tooltipText="Bottom start"
  direction="bottom"
  align="start"
  icon={Filter}
/>
<TooltipIcon
  tooltipText="Left start"
  direction="left"
  align="start"
  icon={Filter}
/>
```

### Custom tooltip text

Use the `tooltipText` slot to customize the tooltip content with additional
styling.

```svelte
<script>
  import { TooltipIcon } from "carbon-components-svelte";
  import Carbon from "carbon-icons-svelte/lib/Carbon.svelte";
</script>

<TooltipIcon icon={Carbon}>
  <span slot="tooltipText" style="color: red"
    >Carbon is an open source design system by IBM.</span
  >
</TooltipIcon>
```

### Disabled state

Set `disabled` to `true` to prevent user interaction with the tooltip.

```svelte
<script>
  import { TooltipIcon } from "carbon-components-svelte";
  import Carbon from "carbon-icons-svelte/lib/Carbon.svelte";
</script>

<TooltipIcon
  disabled
  tooltipText="Carbon is an open source design system by IBM."
  icon={Carbon}
/>
```

---

### Component API

#### `TooltipIcon` props

| Prop             | Type                                      | Description                                                                                            | Default                             |
| ---------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------- |
| `ref` (Reactive) | `null \| HTMLButtonElement`               | Obtain a reference to the button HTML element                                                          | `null`                              |
| `tooltipText`    | `string`                                  | Specify the tooltip text.<br />Alternatively, use the "tooltipText" slot.                              | `""`                                |
| `icon`           | `any`                                     | Specify the icon to render.                                                                            | _undefined_                         |
| `size`           | `(16 \| 20 \| 24 \| 32 \| (number & {}))` | Specify the icon size.<br />Carbon icons use a 16/20/24/32 scale, but any number (pixels) can be used. | `16`                                |
| `disabled`       | `boolean`                                 | Set to `true` to disable the tooltip icon                                                              | `false`                             |
| `align`          | `"start" \| "center" \| "end"`            | Set the alignment of the tooltip relative to the icon.                                                 | `"center"`                          |
| `direction`      | `"top" \| "right" \| "bottom" \| "left"`  | Set the direction of the tooltip relative to the icon.                                                 | `"bottom"`                          |
| `id`             | `string`                                  | Set an id for the span element                                                                         | `ccs-${Math.random().toString(36)}` |

#### `TooltipIcon` slots

| Slot          | Detail                  |
| ------------- | ----------------------- |
| `default`     | `Record<string, never>` |
| `tooltipText` | `Record<string, never>` |

#### `TooltipIcon` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:focus`      |

#### `TooltipIcon` $$restProps

`TooltipIcon` spreads `$$restProps` to the `button` element.


## TreeView

A tree view displays hierarchical data in a collapsible tree structure. It
supports node selection, expansion, icons, and programmatic control of the tree
state.

### Default

Create a basic tree view using the `nodes` prop. Each node requires an `id` and
`text`, with optional properties for `disabled`, `icon`, and child `nodes`.

> [!NOTE] Every node must have a unique id.

```svelte
<script>
  import { TreeView } from "carbon-components-svelte";

  let activeId = "";
  let selectedIds = [];
  let nodes = [
    { id: 0, text: "AI / Machine learning" },
    {
      id: 1,
      text: "Analytics",
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          nodes: [
            { id: 3, text: "Apache Spark" },
            { id: 4, text: "Hadoop" },
          ],
        },
        { id: 5, text: "IBM Cloud SQL Query" },
        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
    {
      id: 9,
      text: "Databases",
      nodes: [
        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
        { id: 12, text: "IBM Cloud Databases for MongoDB" },
        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
      ],
    },
    {
      id: 14,
      text: "Integration",
      disabled: true,
      nodes: [{ id: 15, text: "IBM API Connect", disabled: true }],
    },
  ];
</script>

<TreeView
  labelText="Cloud Products"
  {nodes}
  bind:activeId
  bind:selectedIds
  on:select={({ detail }) => console.log("select", detail)}
  on:toggle={({ detail }) => console.log("toggle", detail)}
  on:focus={({ detail }) => console.log("focus", detail)}
/>

<div>Active node id: {activeId}</div>
<div>Selected ids: {JSON.stringify(selectedIds)}</div>

<style>
  div {
    margin-top: var(--cds-spacing-05);
  }
</style>
```

### Slottable node

Customize node rendering using the default slot with the `let:node` directive.
The node object provides:

- **id**: the node id
- **text**: the node text
- **expanded**: true if the node is expanded
- **leaf**: true if the node does not have child nodes
- **disabled**: true if the node is disabled
- **selected**: true if the node is selected

```svelte
<script>
  import { TreeView } from "carbon-components-svelte";

  let activeId = 0;
  let selectedIds = [0, 7, 9];
  let nodes = [
    { id: 0, text: "AI / Machine learning" },
    {
      id: 1,
      text: "Analytics",
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          nodes: [
            { id: 3, text: "Apache Spark" },
            { id: 4, text: "Hadoop" },
          ],
        },
        { id: 5, text: "IBM Cloud SQL Query" },
        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
    {
      id: 9,
      text: "Databases",
      nodes: [
        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
        { id: 12, text: "IBM Cloud Databases for MongoDB" },
        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
      ],
    },
    {
      id: 14,
      text: "Integration",
      disabled: true,
      nodes: [{ id: 15, text: "IBM API Connect", disabled: true }],
    },
  ];
</script>

<TreeView labelText="Cloud Products" {activeId} {selectedIds} {nodes} let:node>
  <span
    style:color={node.selected ? "var(--cds-interactive-04)" : "inherit"}
    style:text-decoration={node.disabled ? "inherit" : "underline"}
  >
    {node.text} (id: {node.id})
  </span>
</TreeView>
```

### Slottable node with checkbox

Slot a checkbox component in each tree view node to create a tree with checkable
items. The checkbox is wrapped in a container with `stopPropagation` to prevent
tree node selection when checking items.

```svelte
<script>
  import { Checkbox, TreeView } from "carbon-components-svelte";

  let checkedNodes = new Set([0, 7]);
  let nodes = [
    { id: 0, text: "AI / Machine learning" },
    {
      id: 1,
      text: "Analytics",
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          nodes: [
            { id: 3, text: "Apache Spark" },
            { id: 4, text: "Hadoop" },
          ],
        },
        { id: 5, text: "IBM Cloud SQL Query" },
        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
    {
      id: 9,
      text: "Databases",
      nodes: [
        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
        { id: 11, text: "IBM Cloud Databases for MongoDB" },
      ],
    },
  ];

  function handleCheck(nodeId) {
    if (checkedNodes.has(nodeId)) {
      checkedNodes.delete(nodeId);
    } else {
      checkedNodes.add(nodeId);
    }
    checkedNodes = checkedNodes;
  }
</script>

<TreeView labelText="Cloud Products" {nodes} let:node>
  <div on:click|stopPropagation on:keydown|stopPropagation role="none">
    <Checkbox
      labelText={node.text}
      checked={checkedNodes.has(node.id)}
      disabled={node.disabled}
      on:check={() => handleCheck(node.id)}
    />
  </div>
</TreeView>

<div style:margin-top="var(--cds-layout-02)">
  <strong>Checked node IDs:</strong>
  {Array.from(checkedNodes)}
</div>
```

### Slottable node with inline editing

Use a `contenteditable` element in each tree view node to enable inline editing
of node names. The editable region is wrapped in a container with
`stopPropagation` to prevent tree node selection when editing.

```svelte
<script>
  import { RecursiveList, TreeView } from "carbon-components-svelte";
  import Edit from "carbon-icons-svelte/lib/Edit.svelte";

  let nodes = [
    { id: 0, text: "AI / Machine learning" },
    {
      id: 1,
      text: "Analytics",
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          nodes: [
            { id: 3, text: "Apache Spark" },
            { id: 4, text: "Hadoop" },
          ],
        },
        { id: 5, text: "IBM Cloud SQL Query" },
        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
    {
      id: 9,
      text: "Databases",
      nodes: [
        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
        { id: 11, text: "IBM Cloud Databases for MongoDB" },
      ],
    },
  ];

  function updateNodeText(id, text) {
    const findAndUpdate = (items) => {
      for (const item of items) {
        if (item.id === id) {
          item.text = text;
          return true;
        }
        if (item.nodes && findAndUpdate(item.nodes)) {
          return true;
        }
      }
      return false;
    };
    findAndUpdate(nodes);
    nodes = nodes;
  }
</script>

<TreeView labelText="Cloud Products" {nodes} let:node>
  <div on:click|stopPropagation on:keydown|stopPropagation role="none">
    <span
      contenteditable={!node.disabled}
      on:input={(e) => updateNodeText(node.id, e.target.textContent)}
      style:display="flex"
      style:align-items="center"
      style:outline="none"
      style:gap="var(--cds-spacing-02)"
    >
      {node.text}
      <Edit aria-hidden="true" />
    </span>
  </div>
</TreeView>

<br />
<RecursiveList {nodes} />
```

### Initial active node

Set the initial active node using the `activeId` prop.

```svelte
<script>
  import { TreeView } from "carbon-components-svelte";

  let activeId = 0;
  let selectedIds = [];
  let nodes = [
    { id: 0, text: "AI / Machine learning" },
    {
      id: 1,
      text: "Analytics",
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          nodes: [
            { id: 3, text: "Apache Spark" },
            { id: 4, text: "Hadoop" },
          ],
        },
        { id: 5, text: "IBM Cloud SQL Query" },
        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
    {
      id: 9,
      text: "Databases",
      nodes: [
        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
        { id: 12, text: "IBM Cloud Databases for MongoDB" },
        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
      ],
    },
    {
      id: 14,
      text: "Integration",
      disabled: true,
      nodes: [{ id: 15, text: "IBM API Connect", disabled: true }],
    },
  ];
</script>

<TreeView
  labelText="Cloud Products"
  {nodes}
  bind:activeId
  bind:selectedIds
  on:select={({ detail }) => console.log("select", detail)}
  on:toggle={({ detail }) => console.log("toggle", detail)}
  on:focus={({ detail }) => console.log("focus", detail)}
/>

<div>Active node id: {activeId}</div>
<div>Selected ids: {JSON.stringify(selectedIds)}</div>

<style>
  div {
    margin-top: var(--cds-spacing-05);
  }
</style>
```

### Compact size

Use the compact variant by setting `size` to `"compact"`.

```svelte
<script>
  import { TreeView } from "carbon-components-svelte";

  let activeId = 0;
  let selectedIds = [];
  let nodes = [
    { id: 0, text: "AI / Machine learning" },
    {
      id: 1,
      text: "Analytics",
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          nodes: [
            { id: 3, text: "Apache Spark" },
            { id: 4, text: "Hadoop" },
          ],
        },
        { id: 5, text: "IBM Cloud SQL Query" },
        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
    {
      id: 9,
      text: "Databases",
      nodes: [
        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
        { id: 12, text: "IBM Cloud Databases for MongoDB" },
        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
      ],
    },
    {
      id: 14,
      text: "Integration",
      disabled: true,
      nodes: [{ id: 15, text: "IBM API Connect", disabled: true }],
    },
  ];
</script>

<TreeView
  size="compact"
  labelText="Cloud Products"
  {nodes}
  bind:activeId
  bind:selectedIds
  on:select={({ detail }) => console.log("select", detail)}
  on:toggle={({ detail }) => console.log("toggle", detail)}
  on:focus={({ detail }) => console.log("focus", detail)}
/>

<div>Active node id: {activeId}</div>
<div>Selected ids: {JSON.stringify(selectedIds)}</div>

<style>
  div {
    margin-top: var(--cds-spacing-05);
  }
</style>
```

### With icons

Add icons to nodes by defining an `icon` property with a Carbon Svelte icon
component.

```svelte
<script>
  import { TreeView } from "carbon-components-svelte";
  import Analytics from "carbon-icons-svelte/lib/Analytics.svelte";
  import Blockchain from "carbon-icons-svelte/lib/Blockchain.svelte";
  import DataBase from "carbon-icons-svelte/lib/DataBase.svelte";
  import SignalStrength from "carbon-icons-svelte/lib/SignalStrength.svelte";
  import WatsonMachineLearning from "carbon-icons-svelte/lib/WatsonMachineLearning.svelte";

  let activeId = 1;
  let selectedIds = [];
  let nodes = [
    { id: 0, text: "AI / Machine learning", icon: WatsonMachineLearning },
    {
      id: 1,
      text: "Analytics",
      icon: Analytics,
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          icon: Analytics,
          nodes: [
            { id: 3, text: "Apache Spark", icon: Analytics },
            { id: 4, text: "Hadoop", icon: Analytics },
          ],
        },
        { id: 5, text: "IBM Cloud SQL Query", icon: Analytics },
        { id: 6, text: "IBM Db2 Warehouse on Cloud", icon: Analytics },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      icon: Blockchain,
      nodes: [{ id: 8, text: "IBM Blockchain Platform", icon: Blockchain }],
    },
    {
      id: 9,
      text: "Databases",
      icon: DataBase,
      nodes: [
        {
          id: 10,
          text: "IBM Cloud Databases for Elasticsearch",
          icon: DataBase,
        },
        {
          id: 11,
          text: "IBM Cloud Databases for Enterprise DB",
          icon: DataBase,
        },
        { id: 12, text: "IBM Cloud Databases for MongoDB", icon: DataBase },
        {
          id: 13,
          text: "IBM Cloud Databases for PostgreSQL",
          icon: DataBase,
        },
      ],
    },
    {
      id: 14,
      text: "Integration",
      icon: SignalStrength,
      disabled: true,
      nodes: [
        {
          id: 15,
          text: "IBM API Connect",
          icon: SignalStrength,
          disabled: true,
        },
      ],
    },
  ];
</script>

<TreeView
  labelText="Cloud Products"
  {nodes}
  bind:activeId
  bind:selectedIds
  on:select={({ detail }) => console.log("select", detail)}
  on:toggle={({ detail }) => console.log("toggle", detail)}
  on:focus={({ detail }) => console.log("focus", detail)}
/>

<div>Active node id: {activeId}</div>
<div>Selected ids: {JSON.stringify(selectedIds)}</div>

<style>
  div {
    margin-top: var(--cds-spacing-05);
  }
</style>
```

### Initial expanded nodes

Set initially expanded nodes using the `expandedIds` prop.

```svelte
<script>
  import { TreeView } from "carbon-components-svelte";

  let activeId = 1;
  let selectedIds = [];
  let expandedIds = [1, 2, 14];
  let nodes = [
    { id: 0, text: "AI / Machine learning" },
    {
      id: 1,
      text: "Analytics",
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          nodes: [
            { id: 3, text: "Apache Spark" },
            { id: 4, text: "Hadoop" },
          ],
        },
        { id: 5, text: "IBM Cloud SQL Query" },
        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
    {
      id: 9,
      text: "Databases",
      nodes: [
        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
        { id: 12, text: "IBM Cloud Databases for MongoDB" },
        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
      ],
    },
    {
      id: 14,
      text: "Integration",
      disabled: true,
      nodes: [{ id: 15, text: "IBM API Connect", disabled: true }],
    },
  ];
</script>

<TreeView
  labelText="Cloud Products"
  {nodes}
  bind:activeId
  bind:selectedIds
  bind:expandedIds
  on:select={({ detail }) => console.log("select", detail)}
  on:toggle={({ detail }) => console.log("toggle", detail)}
  on:focus={({ detail }) => console.log("focus", detail)}
/>

<div>Active node id: {activeId}</div>
<div>Selected ids: {JSON.stringify(selectedIds)}</div>
<div>Expanded ids: {JSON.stringify(expandedIds)}</div>

<style>
  div {
    margin-top: var(--cds-spacing-05);
  }
</style>
```

### Initial multiple selected nodes

Set multiple initially selected nodes using the `selectedIds` prop.

```svelte
<script>
  import { TreeView } from "carbon-components-svelte";

  let activeId = 0;
  let selectedIds = [0, 7, 9];
  let nodes = [
    { id: 0, text: "AI / Machine learning" },
    {
      id: 1,
      text: "Analytics",
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          nodes: [
            { id: 3, text: "Apache Spark" },
            { id: 4, text: "Hadoop" },
          ],
        },
        { id: 5, text: "IBM Cloud SQL Query" },
        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
    {
      id: 9,
      text: "Databases",
      nodes: [
        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
        { id: 12, text: "IBM Cloud Databases for MongoDB" },
        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
      ],
    },
    {
      id: 14,
      text: "Integration",
      disabled: true,
      nodes: [{ id: 15, text: "IBM API Connect", disabled: true }],
    },
  ];
</script>

<TreeView
  labelText="Cloud Products"
  {nodes}
  bind:activeId
  bind:selectedIds
  on:select={({ detail }) => console.log("select", detail)}
  on:toggle={({ detail }) => console.log("toggle", detail)}
  on:focus={({ detail }) => console.log("focus", detail)}
/>

<div>Active node id: {activeId}</div>
<div>Selected ids: {JSON.stringify(selectedIds)}</div>

<style>
  div {
    margin-top: var(--cds-spacing-05);
  }
</style>
```

### Auto-collapse siblings

Enable the `autoCollapse` prop to automatically collapse sibling nodes when
expanding a node. When enabled, only one node at each level can be expanded at a
time, creating an accordion-like behavior.

```svelte
<script>
  import { Button, ButtonSet, Stack, TreeView } from "carbon-components-svelte";

  let activeId = "";
  let selectedIds = [];
  let expandedIds = [];
  let nodes = [
    { id: 0, text: "AI / Machine learning" },
    {
      id: 1,
      text: "Analytics",
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          nodes: [
            { id: 3, text: "Apache Spark" },
            { id: 4, text: "Hadoop" },
          ],
        },
        { id: 5, text: "IBM Cloud SQL Query" },
        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
    {
      id: 9,
      text: "Databases",
      nodes: [
        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
        { id: 12, text: "IBM Cloud Databases for MongoDB" },
        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
      ],
    },
    {
      id: 14,
      text: "Integration",
      nodes: [{ id: 15, text: "IBM API Connect" }],
    },
  ];
</script>

<Stack gap={4}>
  <ButtonSet>
    <Button size="small" on:click={() => (activeId = 3)}>Select Spark</Button>
    <Button size="small" on:click={() => (activeId = 8)}>
      Select Blockchain
    </Button>
    <Button size="small" on:click={() => (activeId = 12)}>
      Select MongoDB
    </Button>
  </ButtonSet>

  <TreeView
    labelText="Cloud Products"
    {nodes}
    bind:activeId
    bind:selectedIds
    bind:expandedIds
    autoCollapse={true}
    on:select={({ detail }) => console.log("select", detail)}
    on:toggle={({ detail }) => console.log("toggle", detail)}
    on:focus={({ detail }) => console.log("focus", detail)}
  />

  <div>Active node id: {activeId}</div>
  <div>Selected ids: {JSON.stringify(selectedIds)}</div>
  <div>Expanded ids: {JSON.stringify(expandedIds)}</div>
</Stack>
```

### Expand all nodes

Programmatically expand all nodes using the `TreeView.expandAll()` method.

```svelte
<script>
  import { Button, TreeView } from "carbon-components-svelte";

  let treeview = null;
  let nodes = [
    { id: 0, text: "AI / Machine learning" },
    {
      id: 1,
      text: "Analytics",
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          nodes: [
            { id: 3, text: "Apache Spark" },
            { id: 4, text: "Hadoop" },
          ],
        },
        { id: 5, text: "IBM Cloud SQL Query" },
        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
    {
      id: 9,
      text: "Databases",
      nodes: [
        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
        { id: 12, text: "IBM Cloud Databases for MongoDB" },
        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
      ],
    },
    {
      id: 14,
      text: "Integration",
      disabled: true,
      nodes: [{ id: 15, text: "IBM API Connect", disabled: true }],
    },
  ];
</script>

<div>
  <Button on:click={treeview?.expandAll}>Expand all</Button>
</div>

<TreeView bind:this={treeview} labelText="Cloud Products" {nodes} />

<style>
  div {
    margin-bottom: var(--cds-spacing-05);
  }
</style>
```

### Collapse all nodes

Programmatically collapse all nodes using the `TreeView.collapseAll()` method.

```svelte
<script>
  import { Button, TreeView } from "carbon-components-svelte";

  let treeview = null;
  let expandedIds = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
  let nodes = [
    { id: 0, text: "AI / Machine learning" },
    {
      id: 1,
      text: "Analytics",
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          nodes: [
            { id: 3, text: "Apache Spark" },
            { id: 4, text: "Hadoop" },
          ],
        },
        { id: 5, text: "IBM Cloud SQL Query" },
        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
    {
      id: 9,
      text: "Databases",
      nodes: [
        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
        { id: 12, text: "IBM Cloud Databases for MongoDB" },
        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
      ],
    },
    {
      id: 14,
      text: "Integration",
      disabled: true,
      nodes: [{ id: 15, text: "IBM API Connect", disabled: true }],
    },
  ];
</script>

<div>
  <Button on:click={treeview?.collapseAll}>Collapse all</Button>
</div>

<TreeView
  bind:this={treeview}
  bind:expandedIds
  labelText="Cloud Products"
  {nodes}
/>

<style>
  div {
    margin-bottom: var(--cds-spacing-05);
  }
</style>
```

### Expand a subset of nodes

Use `TreeView.expandNodes` to expand specific nodes based on a condition.

```svelte
<script>
  import { Button, TreeView } from "carbon-components-svelte";

  let treeview = null;
  let nodes = [
    { id: 0, text: "AI / Machine learning" },
    {
      id: 1,
      text: "Analytics",
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          nodes: [
            { id: 3, text: "Apache Spark" },
            { id: 4, text: "Hadoop" },
          ],
        },
        { id: 5, text: "IBM Cloud SQL Query" },
        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
    {
      id: 9,
      text: "Databases",
      nodes: [
        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
        { id: 12, text: "IBM Cloud Databases for MongoDB" },
        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
      ],
    },
    {
      id: 14,
      text: "Integration",
      disabled: true,
      nodes: [{ id: 15, text: "IBM API Connect", disabled: true }],
    },
  ];
</script>

<div>
  <Button
    on:click={() => {
      treeview?.expandNodes((node) => /^IBM/.test(node.text));
    }}
  >
    Expand nodes starting with "IBM"
  </Button>
</div>

<TreeView bind:this={treeview} labelText="Cloud Products" {nodes} />

<style>
  div {
    margin-bottom: var(--cds-spacing-05);
  }
</style>
```

### Collapse a subset of nodes

Use `TreeView.collapseNodes` to collapse specific nodes based on a condition.

```svelte
<script>
  import { Button, TreeView } from "carbon-components-svelte";

  let treeview = null;
  let expandedIds = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 14];
  let nodes = [
    { id: 0, text: "AI / Machine learning" },
    {
      id: 1,
      text: "Analytics",
      disabled: true,
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          disabled: true,
          nodes: [
            { id: 3, text: "Apache Spark", disabled: true },
            { id: 4, text: "Hadoop", disabled: true },
          ],
        },
        { id: 5, text: "IBM Cloud SQL Query", disabled: true },
        { id: 6, text: "IBM Db2 Warehouse on Cloud", disabled: true },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
    {
      id: 9,
      text: "Databases",
      nodes: [
        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
        { id: 12, text: "IBM Cloud Databases for MongoDB" },
        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
      ],
    },
    {
      id: 14,
      text: "Integration",
      disabled: true,
      nodes: [{ id: 15, text: "IBM API Connect", disabled: true }],
    },
  ];
</script>

<div>
  <Button
    on:click={() => {
      treeview?.collapseNodes((node) => node.disabled);
    }}
  >
    Collapse disabled nodes
  </Button>
</div>

<TreeView
  bind:this={treeview}
  bind:expandedIds
  labelText="Cloud Products"
  {nodes}
/>

<style>
  div {
    margin-bottom: var(--cds-spacing-05);
  }
</style>
```

### Show a specific node

Use `TreeView.showNode` to expand, select, and focus a specific node.

```svelte
<script>
  import { Button, ButtonSet, TreeView } from "carbon-components-svelte";

  const nodeSpark = { id: 3, text: "Apache Spark" };
  const nodeBlockchain = { id: 8, text: "IBM Blockchain Platform" };

  let treeview = null;
  let nodes = [
    { id: 0, text: "AI / Machine learning" },
    {
      id: 1,
      text: "Analytics",
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          nodes: [nodeSpark, { id: 4, text: "Hadoop" }],
        },
        { id: 5, text: "IBM Cloud SQL Query" },
        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
  ];
</script>

<ButtonSet style="margin-bottom: var(--cds-spacing-05)">
  {#each [nodeSpark, nodeBlockchain] as { id, text }}
    <Button
      on:click={() => {
        treeview?.showNode(id);
      }}
    >
      Show "{text}"
    </Button>
  {/each}
  <Button kind="tertiary" on:click={treeview.collapseAll}>Collapse all</Button>
</ButtonSet>

<TreeView bind:this={treeview} labelText="Cloud Products" {nodes} />
```

### Show node with options

Configure `TreeView.showNode` behavior using optional parameters. By default,
all three actions occur (`expand`, `select`, `focus`), but you can disable any
combination. This is useful for expanding nodes without selecting them, or
selecting without expanding.

```svelte
<script>
  import { Button, ButtonSet, TreeView } from "carbon-components-svelte";

  const targetNode = { id: 3, text: "Apache Spark" };
  const targetNodeSelect = { id: 0, text: "AI / Machine learning" };

  let treeview = null;
  let key = 0;
  let nodes = [
    targetNodeSelect,
    {
      id: 1,
      text: "Analytics",
      nodes: [
        {
          id: 2,
          text: "IBM Analytics Engine",
          nodes: [targetNode, { id: 4, text: "Hadoop" }],
        },
        { id: 5, text: "IBM Cloud SQL Query" },
        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
      ],
    },
    {
      id: 7,
      text: "Blockchain",
      nodes: [{ id: 8, text: "IBM Blockchain Platform" }],
    },
  ];
</script>

<ButtonSet style="margin-bottom: var(--cds-spacing-05)">
  <Button
    on:click={() => {
      treeview?.showNode(targetNode.id);
    }}
  >
    Default (expand + select + focus)
  </Button>
  <Button
    on:click={() => {
      treeview?.showNode(targetNode.id, {
        select: false,
        focus: false,
      });
    }}
  >
    Expand only
  </Button>
  <Button
    on:click={() => {
      treeview?.showNode(targetNodeSelect.id, {
        expand: false,
        focus: false,
      });
    }}
  >
    Select only
  </Button>
  <Button kind="tertiary" on:click={() => key++}>Reset</Button>
</ButtonSet>

{#key key}
  <TreeView bind:this={treeview} labelText="Cloud Products" {nodes} />
{/key}
```

### Performance with large and deep trees

The tree view is optimized to handle large datasets efficiently. This example
demonstrates performance with both a large tree (1000+ nodes) and a deeply
nested tree (100 levels deep).

```svelte
<script>
  import {
    Button,
    ButtonSet,
    ContentSwitcher,
    Stack,
    Switch,
    TreeView,
  } from "carbon-components-svelte";
  import { tick } from "svelte";

  let treeview = null;
  let performanceInfo = { expandAll: 0, collapseAll: 0, showNode: 0 };

  function generateLargeTree() {
    const nodes = [];
    let idCounter = 0;

    for (let i = 0; i < 10; i++) {
      const categoryNodes = [];

      for (let j = 0; j < 10; j++) {
        const subcategoryNodes = [];

        for (let k = 0; k < 10; k++) {
          subcategoryNodes.push({
            id: idCounter++,
            text: `Item ${i}-${j}-${k}`,
          });
        }

        categoryNodes.push({
          id: idCounter++,
          text: `Subcategory ${i}-${j}`,
          nodes: subcategoryNodes,
        });
      }

      nodes.push({
        id: idCounter++,
        text: `Category ${i}`,
        nodes: categoryNodes,
      });
    }

    return nodes;
  }

  function generateDeepTree() {
    let idCounter = 0;
    let lastId = 0;

    function createNestedNode(depth, maxDepth) {
      const node = {
        id: idCounter++,
        text: `Level ${depth}`,
      };
      lastId = node.id;

      if (depth < maxDepth) {
        node.nodes = [createNestedNode(depth + 1, maxDepth)];
      }

      return node;
    }

    const rootNode = createNestedNode(0, 100);
    return { nodes: [rootNode], lastId };
  }

  let nodes = generateLargeTree();
  let treeType = "large";
  let lastDeepNodeId = null;
  let selectedIndex = 0;

  async function handleTreeSwitch(event) {
    const index = event.detail;
    selectedIndex = index;

    performanceInfo = { expandAll: 0, collapseAll: 0, showNode: 0 };

    const start = performance.now();
    if (index === 0) {
      nodes = generateLargeTree();
      treeType = "large";
      lastDeepNodeId = null;
    } else {
      const { nodes: deepNodes, lastId } = generateDeepTree();
      nodes = deepNodes;
      lastDeepNodeId = lastId;
      treeType = "deep";
    }

    await tick();
    setTimeout(() => {
      const end = performance.now();
      console.log(
        (index === 0 ? "Large" : "Deep") +
          " tree generation: " +
          (end - start).toFixed(2) +
          "ms"
      );
    }, 0);
  }

  function handleExpandAll() {
    const start = performance.now();
    treeview?.expandAll();
    const end = performance.now();
    performanceInfo.expandAll = end - start;
    performanceInfo = performanceInfo;
  }

  function handleCollapseAll() {
    const start = performance.now();
    treeview?.collapseAll();
    const end = performance.now();
    performanceInfo.collapseAll = end - start;
    performanceInfo = performanceInfo;
  }

  function handleShowNode() {
    const start = performance.now();
    const targetId =
      treeType === "large"
        ? 999
        : lastDeepNodeId !== null
        ? lastDeepNodeId
        : 100;
    if (treeview) {
      treeview.showNode(targetId);
    }
    const end = performance.now();
    performanceInfo.showNode = end - start;
    performanceInfo = performanceInfo;
  }
</script>

<Stack gap={4}>
  <ContentSwitcher {selectedIndex} on:change={handleTreeSwitch}>
    <Switch text="Large Tree (1000+ nodes)" />
    <Switch text="Deep Tree (100 levels)" />
  </ContentSwitcher>

  <ButtonSet>
    <Button on:click={handleExpandAll}>Expand All</Button>
    <Button on:click={handleCollapseAll}>Collapse All</Button>
    <Button on:click={handleShowNode}>Show Deep Node</Button>
  </ButtonSet>

  {#if performanceInfo.expandAll > 0 || performanceInfo.collapseAll > 0 || performanceInfo.showNode > 0}
    <Stack gap={2}>
      <div>Expand All: {performanceInfo.expandAll.toFixed(2)}ms</div>
      <div>Collapse All: {performanceInfo.collapseAll.toFixed(2)}ms</div>
      <div>Show Node: {performanceInfo.showNode.toFixed(2)}ms</div>
    </Stack>
  {/if}

  <TreeView
    bind:this={treeview}
    labelText={treeType === "large"
      ? "Large Tree (1000+ nodes)"
      : "Deep Tree (100 levels)"}
    {nodes}
  />
</Stack>
```

### Flat data structure

Convert flat data to a hierarchical structure using the `toHierarchy` utility.

```svelte
<script>
  import { TreeView, toHierarchy } from "carbon-components-svelte";
  import Analytics from "carbon-icons-svelte/lib/Analytics.svelte";

  let nodesFlat = [
    { id: 0, text: "AI / Machine learning", icon: Analytics },
    { id: 1, text: "Analytics" },
    { id: 2, text: "IBM Analytics Engine", pid: 1 },
    { id: 3, text: "Apache Spark", pid: 2 },
    { id: 4, text: "Hadoop", pid: 2 },
    { id: 5, text: "IBM Cloud SQL Query", pid: 1 },
    { id: 6, text: "IBM Db2 Warehouse on Cloud", pid: 1 },
    { id: 7, text: "Blockchain" },
    { id: 8, text: "IBM Blockchain Platform", pid: 7 },
    { id: 9, text: "Databases" },
    { id: 10, text: "IBM Cloud Databases for Elasticsearch", pid: 9 },
    { id: 11, text: "IBM Cloud Databases for Enterprise DB", pid: 9 },
    { id: 12, text: "IBM Cloud Databases for MongoDB", pid: 9 },
    { id: 13, text: "IBM Cloud Databases for PostgreSQL", pid: 9 },
    { id: 14, text: "Integration", disabled: true },
    { id: 15, text: "IBM API Connect", disabled: true, pid: 14 },
  ];
</script>

<TreeView
  labelText="Cloud Products"
  nodes={toHierarchy(nodesFlat, (node) => node.pid)}
/>
```

### Filter by text with search input

Combine a search input with `filterTreeByText` to create an interactive
searchable tree. Type to filter nodes by name (case-insensitive substring
matching). By default, matching nodes and their ancestors are included to
maintain valid tree structure.

```svelte
<script>
  import { filterTreeByText, Search, TreeView } from "carbon-components-svelte";

  const allNodes = [
    {
      id: "1",
      text: "Documents",
      nodes: [
        {
          id: "1-1",
          text: "Work",
          nodes: [
            { id: "1-1-1", text: "Report.docx" },
            { id: "1-1-2", text: "Presentation.pptx" },
            { id: "1-1-3", text: "Budget.xlsx" },
            { id: "1-1-4", text: "Meeting Notes.txt" },
          ],
        },
        {
          id: "1-2",
          text: "Personal",
          nodes: [
            { id: "1-2-1", text: "Resume.pdf" },
            { id: "1-2-2", text: "Cover Letter.pdf" },
            { id: "1-2-3", text: "Portfolio.pdf" },
          ],
        },
        {
          id: "1-3",
          text: "Projects",
          nodes: [
            {
              id: "1-3-1",
              text: "Website",
              nodes: [
                { id: "1-3-1-1", text: "index.html" },
                { id: "1-3-1-2", text: "styles.css" },
                { id: "1-3-1-3", text: "script.js" },
              ],
            },
            {
              id: "1-3-2",
              text: "App",
              nodes: [
                { id: "1-3-2-1", text: "main.py" },
                { id: "1-3-2-2", text: "config.json" },
              ],
            },
          ],
        },
      ],
    },
    {
      id: "2",
      text: "Pictures",
      nodes: [
        { id: "2-1", text: "Vacation.jpg" },
        { id: "2-2", text: "Family.jpg" },
        { id: "2-3", text: "Birthday.png" },
      ],
    },
    {
      id: "3",
      text: "Music",
      nodes: [
        {
          id: "3-1",
          text: "Rock",
          nodes: [
            { id: "3-1-1", text: "Song1.mp3" },
            { id: "3-1-2", text: "Song2.mp3" },
          ],
        },
        {
          id: "3-2",
          text: "Jazz",
          nodes: [
            { id: "3-2-1", text: "Song3.mp3" },
            { id: "3-2-2", text: "Song4.mp3" },
          ],
        },
        {
          id: "3-3",
          text: "Classical",
          nodes: [{ id: "3-3-1", text: "Symphony.mp3" }],
        },
      ],
    },
  ];

  let searchValue = "";
  let expandedIds = [];

  $: filteredNodes =
    searchValue.trim() === ""
      ? allNodes
      : filterTreeByText(allNodes, searchValue);

  $: if (searchValue.trim() !== "" && filteredNodes.length > 0) {
    const extractIds = (nodes) => {
      const ids = [];
      for (const node of nodes) {
        ids.push(node.id);
        if (node.nodes) {
          ids.push(...extractIds(node.nodes));
        }
      }
      return ids;
    };
    expandedIds = extractIds(filteredNodes);
  } else {
    expandedIds = [];
  }
</script>

<Search size="sm" placeholder="Search tree nodes..." bind:value={searchValue} />

<div style:margin-top="var(--cds-layout-01)">
  {#if filteredNodes.length > 0}
    <TreeView labelText="File System" nodes={filteredNodes} {expandedIds} />
  {:else}
    No matching nodes found for "{searchValue}"
  {/if}
</div>
```

### Filter by ID

Use `filterTreeById` to filter nodes by their ID. Accepts either a single ID or
an array of IDs. Click the buttons to filter by a single ID or multiple IDs.
Matching nodes and their ancestors are included by default.

```svelte
<script>
  import {
    Button,
    ButtonSet,
    filterTreeById,
    TreeView,
  } from "carbon-components-svelte";

  const allNodes = [
    {
      id: "1",
      text: "Documents",
      nodes: [
        {
          id: "1-1",
          text: "Work",
          nodes: [
            { id: "1-1-1", text: "Report.docx" },
            { id: "1-1-2", text: "Presentation.pptx" },
            { id: "1-1-3", text: "Budget.xlsx" },
          ],
        },
        {
          id: "1-2",
          text: "Personal",
          nodes: [
            { id: "1-2-1", text: "Resume.pdf" },
            { id: "1-2-2", text: "Cover Letter.pdf" },
          ],
        },
      ],
    },
    {
      id: "2",
      text: "Pictures",
      nodes: [
        { id: "2-1", text: "Vacation.jpg" },
        { id: "2-2", text: "Family.jpg" },
      ],
    },
    {
      id: "3",
      text: "Music",
      nodes: [
        {
          id: "3-1",
          text: "Rock",
          nodes: [
            { id: "3-1-1", text: "Song1.mp3" },
            { id: "3-1-2", text: "Song2.mp3" },
          ],
        },
      ],
    },
  ];

  let filteredNodes = allNodes;
  let expandedIds = [];

  function filterBySingleId() {
    filteredNodes = filterTreeById(allNodes, "1-1-1");
    expandedIds = ["1", "1-1", "1-1-1"];
  }

  function filterByMultipleIds() {
    filteredNodes = filterTreeById(allNodes, ["1-1-1", "1-2-1", "2-1"]);
    expandedIds = ["1", "1-1", "1-1-1", "1-2", "1-2-1", "2", "2-1"];
  }

  function resetFilter() {
    filteredNodes = allNodes;
    expandedIds = [];
  }
</script>

<ButtonSet style="margin-bottom: var(--cds-layout-01)">
  <Button size="sm" on:click={filterBySingleId}>Filter single ID</Button>
  <Button size="sm" on:click={filterByMultipleIds}>Filter multiple IDs</Button>
  <Button size="sm" kind="tertiary" on:click={resetFilter}>Reset</Button>
</ButtonSet>

<TreeView labelText="File System" nodes={filteredNodes} {expandedIds} />
```

### Filter with custom predicate

Use `filterTreeNodes` with a predicate function to implement custom filtering
logic. The example demonstrates filtering by file extension, filtering leaf
nodes only, and using the `includeChildren` option to include all descendants of
matching nodes. By default, matching nodes and their ancestors are included.

```svelte
<script>
  import {
    Button,
    ButtonSet,
    filterTreeNodes,
    TreeView,
  } from "carbon-components-svelte";

  const allNodes = [
    {
      id: "1",
      text: "Documents",
      nodes: [
        {
          id: "1-1",
          text: "Work",
          nodes: [
            { id: "1-1-1", text: "Report.docx" },
            { id: "1-1-2", text: "Presentation.pptx" },
            { id: "1-1-3", text: "Budget.xlsx" },
          ],
        },
        {
          id: "1-2",
          text: "Personal",
          nodes: [
            { id: "1-2-1", text: "Resume.pdf" },
            { id: "1-2-2", text: "Cover Letter.pdf" },
          ],
        },
      ],
    },
    {
      id: "2",
      text: "Pictures",
      nodes: [
        { id: "2-1", text: "Vacation.jpg" },
        { id: "2-2", text: "Family.jpg" },
      ],
    },
    {
      id: "3",
      text: "Music",
      nodes: [
        {
          id: "3-1",
          text: "Rock",
          nodes: [
            { id: "3-1-1", text: "Song1.mp3" },
            { id: "3-1-2", text: "Song2.mp3" },
          ],
        },
      ],
    },
  ];

  let filteredNodes = allNodes;
  let expandedIds = [];

  function filterByExtension() {
    filteredNodes = filterTreeNodes(
      allNodes,
      (node) => node.text?.endsWith(".pdf") || node.text?.endsWith(".docx")
    );
    expandedIds = ["1", "1-1", "1-1-1", "1-2", "1-2-1"];
  }

  function filterLeafNodes() {
    filteredNodes = filterTreeNodes(
      allNodes,
      (node) => !node.nodes || node.nodes.length === 0
    );
    expandedIds = [
      "1",
      "1-1",
      "1-1-1",
      "1-1-2",
      "1-1-3",
      "1-2",
      "1-2-1",
      "1-2-2",
      "2",
      "2-1",
      "2-2",
      "3",
      "3-1",
      "3-1-1",
      "3-1-2",
    ];
  }

  function filterWithChildren() {
    filteredNodes = filterTreeNodes(allNodes, (node) => node.id === "1-1", {
      includeChildren: true,
    });
    expandedIds = ["1", "1-1", "1-1-1", "1-1-2", "1-1-3"];
  }

  function resetFilter() {
    filteredNodes = allNodes;
    expandedIds = [];
  }
</script>

<ButtonSet style="margin-bottom: var(--cds-layout-01)">
  <Button size="sm" on:click={filterByExtension}>
    Filter by extension (.pdf, .docx)
  </Button>
  <Button size="sm" on:click={filterLeafNodes}>Filter leaf nodes</Button>
  <Button size="sm" on:click={filterWithChildren}>Filter with children</Button>
  <Button size="sm" kind="tertiary" on:click={resetFilter}>Reset</Button>
</ButtonSet>

<TreeView labelText="File System" nodes={filteredNodes} {expandedIds} />
```

---

### Component API

#### `TreeView` props

| Prop                     | Type                                                  | Description                                                                                                                                                                                              | Default     |
| ------------------------ | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `activeId` (Reactive)    | `Node["id"]`                                          | Set the current active node id.<br />Only one node can be active.                                                                                                                                        | `""`        |
| `selectedIds` (Reactive) | `ReadonlyArray<Node["id"]>`                           | Set the node ids to be selected.                                                                                                                                                                         | `[]`        |
| `expandedIds` (Reactive) | `ReadonlyArray<Node["id"]>`                           | Set the node ids to be expanded.                                                                                                                                                                         | `[]`        |
| `nodes`                  | `ReadonlyArray<Node>`                                 | Provide an array of nodes to render.                                                                                                                                                                     | `[]`        |
| `size`                   | `"default" \| "compact"`                              | Specify the TreeView size.                                                                                                                                                                               | `"default"` |
| `labelText`              | `string`                                              | Specify the label text                                                                                                                                                                                   | `""`        |
| `hideLabel`              | `boolean`                                             | Set to `true` to visually hide the label text                                                                                                                                                            | `false`     |
| `autoCollapse`           | `boolean`                                             | Set to `true` to automatically collapse sibling nodes when expanding a node.<br />When enabled, only one node at each level can be expanded at a time.                                                   | `false`     |
| `expandAll`              | `() => void`                                          | Programmatically expand all nodes                                                                                                                                                                        | _undefined_ |
| `collapseAll`            | `() => void`                                          | Programmatically collapse all nodes                                                                                                                                                                      | _undefined_ |
| `expandNodes`            | `(filterNode?: (node: Node) => boolean) => void`      | Programmatically expand a subset of nodes.<br />Expands all nodes if no argument is provided.<br />Filter function should return `true` for nodes to expand. If not provided, expands all nodes.         | _undefined_ |
| `collapseNodes`          | `(filterNode?: (node: Node) => boolean) => void`      | Programmatically collapse a subset of nodes.<br />Collapses all nodes if no argument is provided.<br />Filter function should return `true` for nodes to collapse. If not provided, collapses all nodes. | _undefined_ |
| `showNode`               | `(id: Node["id"], options?: ShowNodeOptions) => void` | Programmatically show a node by `id`.<br />By default, the matching node will be expanded, selected, and focused.<br />Use the options parameter to customize this behavior.                             | _undefined_ |

#### `TreeView` typedefs

```ts
type TreeNode<Id = string | number> = {
  id: Id;
  text: any;
  icon?: any;
  /** Whether the node is disabled */
  disabled?: boolean;
  nodes?: TreeNode<Id>[];
};

type ShowNodeOptions = {
  /** Whether to expand the node and its ancestors (default: true) */
  expand?: boolean;
  /** Whether to select the node (default: true) */
  select?: boolean;
  /** Whether to focus the node (default: true) */
  focus?: boolean;
};
```

#### `TreeView` slots

| Slot            | Detail                                                                                                          |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| `default`       | `{<br /> node: Node & {<br /> expanded: boolean;<br /> leaf: boolean;<br /> selected: boolean;<br /> };<br />}` |
| `labelChildren` | `Record<string, never>`                                                                                         |

#### `TreeView` forwarded events

| Event        |
| ------------ |
| `on:keydown` |

#### `TreeView` dispatched events

| Event       | Detail                                                                                   |
| ----------- | ---------------------------------------------------------------------------------------- |
| `on:select` | `Node & {<br /> expanded: boolean;<br /> leaf: boolean;<br /> selected: boolean;<br />}` |
| `on:toggle` | `Node & {<br /> expanded: boolean;<br /> leaf: boolean;<br /> selected: boolean;<br />}` |
| `on:focus`  | `Node & {<br /> expanded: boolean;<br /> leaf: boolean;<br /> selected: boolean;<br />}` |

#### `TreeView` $$restProps

`TreeView` spreads `$$restProps` to the `ul` element.


## Truncate

Truncate provides text truncation functionality for single-line content. It
implements Carbon's text truncation CSS classes and can be used as either a
component or an action.

### Default

Display truncated text using the default component. Text is wrapped in a
paragraph element and truncated at the end of the line.

```svelte
<script>
  import { Truncate } from "carbon-components-svelte";
</script>

<Truncate>
  Carbon Components Svelte is a Svelte component library that implements the
  Carbon Design System, an open source design system by IBM.
</Truncate>
```

### Clamp front

Truncate text from the beginning by setting `clamp` to `"front"`.

```svelte
<script>
  import { Truncate } from "carbon-components-svelte";
</script>

<Truncate clamp="front">
  Carbon Components Svelte is a Svelte component library that implements the
  Carbon Design System, an open source design system by IBM.
</Truncate>
```

### use:truncate

Apply truncation to any HTML element using the `truncate` action.

```svelte
<script>
  import { truncate } from "carbon-components-svelte";
</script>

<h4 use:truncate>
  Carbon Components Svelte is a Svelte component library that implements the
  Carbon Design System, an open source design system by IBM.
</h4>
<h4 use:truncate={{ clamp: "front" }}>
  Carbon Components Svelte is a Svelte component library that implements the
  Carbon Design System, an open source design system by IBM.
</h4>
```

---

### Component API

#### `Truncate` props

| Prop    | Type               | Description | Default |
| ------- | ------------------ | ----------- | ------- |
| `clamp` | `"end" \| "front"` |             | `"end"` |

#### `Truncate` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `Truncate` $$restProps

`Truncate` spreads `$$restProps` to the `p` element.


## UIShell

The UI shell provides a collection of components for building application shells
and navigation structures. It includes header, side navigation, and content
components that work together to create a cohesive user interface.

> [!NOTE] Currently, the UI Shell is not themable and only supports dark mode.

Open the following examples in a new tab to experience them in full.

### Header

Create a basic header with the header component.

```svelte
<script>
  import {
    Column,
    Content,
    Grid,
    Header,
    HeaderNav,
    HeaderNavItem,
    HeaderNavMenu,
    Row,
    SkipToContent,
  } from "carbon-components-svelte";

  let isSideNavOpen = false;
</script>

<Header companyName="IBM" platformName="Carbon Svelte" bind:isSideNavOpen>
  <svelte:fragment slot="skipToContent">
    <SkipToContent />
  </svelte:fragment>
  <HeaderNav>
    <HeaderNavItem href="/" text="Link 1" />
    <HeaderNavItem href="/" text="Link 2" />
    <HeaderNavItem href="/" text="Link 3" />
    <HeaderNavMenu text="Menu">
      <HeaderNavItem href="/" text="Link 1" />
      <HeaderNavItem href="/" text="Link 2" />
      <HeaderNavItem href="/" text="Link 3" />
    </HeaderNavMenu>
  </HeaderNav>
</Header>

<Content>
  <Grid>
    <Row>
      <Column>
        <h1>Welcome</h1>
      </Column>
    </Row>
  </Grid>
</Content>
```

### Header with side navigation

The hamburger menu will automatically be rendered if the side nav component is
used.

```svelte
<script>
  import {
    Column,
    Content,
    Grid,
    Header,
    HeaderNav,
    HeaderNavItem,
    HeaderNavMenu,
    Row,
    SideNav,
    SideNavDivider,
    SideNavItems,
    SideNavLink,
    SideNavMenu,
    SideNavMenuItem,
    SkipToContent,
  } from "carbon-components-svelte";

  let isSideNavOpen = false;
</script>

<Header companyName="IBM" platformName="Carbon Svelte" bind:isSideNavOpen>
  <svelte:fragment slot="skipToContent">
    <SkipToContent />
  </svelte:fragment>
  <HeaderNav>
    <HeaderNavItem href="/" text="Link 1" />
    <HeaderNavItem href="/" text="Link 2" />
    <HeaderNavItem href="/" text="Link 3" />
    <HeaderNavMenu text="Menu">
      <HeaderNavItem href="/" text="Link 1" />
      <HeaderNavItem href="/" text="Link 2" />
      <HeaderNavItem href="/" text="Link 3" />
    </HeaderNavMenu>
    <HeaderNavItem href="/" text="Link 4" />
  </HeaderNav>
</Header>

<SideNav bind:isOpen={isSideNavOpen}>
  <SideNavItems>
    <SideNavLink text="Link 1" />
    <SideNavLink text="Link 2" />
    <SideNavLink text="Link 3" />
    <SideNavMenu text="Menu">
      <SideNavMenuItem href="/" text="Link 1" />
      <SideNavMenuItem href="/" text="Link 2" />
      <SideNavMenuItem href="/" text="Link 3" />
    </SideNavMenu>
    <SideNavDivider />
    <SideNavLink text="Link 4" />
  </SideNavItems>
</SideNav>

<Content>
  <Grid>
    <Row>
      <Column>
        <h1>Welcome</h1>
      </Column>
    </Row>
  </Grid>
</Content>
```

### Header with fixed side navigation

Set `fixed` to `true` on the side nav to keep it always visible, regardless of
viewport width. The hamburger menu is not rendered because the side nav is not
collapsible.

```svelte
<script>
  import {
    Column,
    Content,
    Grid,
    Header,
    HeaderNav,
    HeaderNavItem,
    HeaderNavMenu,
    Row,
    SideNav,
    SideNavDivider,
    SideNavItems,
    SideNavLink,
    SideNavMenu,
    SideNavMenuItem,
    SkipToContent,
  } from "carbon-components-svelte";
</script>

<Header companyName="IBM" platformName="Carbon Svelte">
  <svelte:fragment slot="skipToContent">
    <SkipToContent />
  </svelte:fragment>
  <HeaderNav>
    <HeaderNavItem href="/" text="Link 1" />
    <HeaderNavItem href="/" text="Link 2" />
    <HeaderNavItem href="/" text="Link 3" />
    <HeaderNavMenu text="Menu">
      <HeaderNavItem href="/" text="Link 1" />
      <HeaderNavItem href="/" text="Link 2" />
      <HeaderNavItem href="/" text="Link 3" />
    </HeaderNavMenu>
    <HeaderNavItem href="/" text="Link 4" />
  </HeaderNav>
</Header>

<SideNav fixed isOpen>
  <SideNavItems>
    <SideNavLink text="Link 1" />
    <SideNavLink text="Link 2" />
    <SideNavLink text="Link 3" />
    <SideNavMenu text="Menu">
      <SideNavMenuItem href="/" text="Link 1" />
      <SideNavMenuItem href="/" text="Link 2" />
      <SideNavMenuItem href="/" text="Link 3" />
    </SideNavMenu>
    <SideNavDivider />
    <SideNavLink text="Link 4" />
  </SideNavItems>
</SideNav>

<Content>
  <Grid>
    <Row>
      <Column>
        <h1>Welcome</h1>
      </Column>
    </Row>
  </Grid>
</Content>
```

### Header with side navigation (rail)

Set `rail` to `true` on the side nav to use the rail variant. Expanded side nav
menu items automatically collapse when the rail is in its narrow state.

```svelte
<script>
  import {
    Column,
    Content,
    Grid,
    Header,
    HeaderNav,
    HeaderNavItem,
    HeaderNavMenu,
    Row,
    SideNav,
    SideNavDivider,
    SideNavItems,
    SideNavLink,
    SideNavMenu,
    SideNavMenuItem,
    SkipToContent,
  } from "carbon-components-svelte";
  import Fade from "carbon-icons-svelte/lib/Fade.svelte";

  let isSideNavOpen = false;
</script>

<Header companyName="IBM" platformName="Carbon Svelte" bind:isSideNavOpen>
  <svelte:fragment slot="skipToContent">
    <SkipToContent />
  </svelte:fragment>
  <HeaderNav>
    <HeaderNavItem href="/" text="Link 1" />
    <HeaderNavItem href="/" text="Link 2" />
    <HeaderNavItem href="/" text="Link 3" />
    <HeaderNavMenu text="Menu">
      <HeaderNavItem href="/" text="Link 1" />
      <HeaderNavItem href="/" text="Link 2" />
      <HeaderNavItem href="/" text="Link 3" />
    </HeaderNavMenu>
    <HeaderNavItem href="/" text="Link 4" />
  </HeaderNav>
</Header>

<SideNav bind:isOpen={isSideNavOpen} rail>
  <SideNavItems>
    <SideNavLink icon={Fade} text="Link 1" href="/" isSelected />
    <SideNavLink icon={Fade} text="Link 2" href="/" />
    <SideNavLink icon={Fade} text="Link 3" href="/" />
    <SideNavMenu expanded icon={Fade} text="Menu">
      <SideNavMenuItem href="/" text="Link 1" />
      <SideNavMenuItem href="/" text="Link 2" />
      <SideNavMenuItem href="/" text="Link 3" />
    </SideNavMenu>
    <SideNavDivider />
    <SideNavLink icon={Fade} text="Link 4" href="/" />
  </SideNavItems>
</SideNav>

<Content>
  <Grid>
    <Row>
      <Column>
        <h1>Welcome</h1>
      </Column>
    </Row>
  </Grid>
</Content>
```

### Header with app switcher

The header action component uses the
[transition:slide API](https://svelte.dev/docs#slide); you can customize the
transition duration, delay, and easing with the `transition` prop.

You can disable the `transition` by setting it to `false`.

```svelte
<script>
  import {
    Column,
    Content,
    Grid,
    Header,
    HeaderAction,
    HeaderPanelDivider,
    HeaderPanelLink,
    HeaderPanelLinks,
    HeaderUtilities,
    RadioTile,
    Row,
    SideNav,
    SideNavItems,
    SideNavLink,
    SideNavMenu,
    SideNavMenuItem,
    SkipToContent,
    TileGroup,
  } from "carbon-components-svelte";
  import { expoIn } from "svelte/easing";

  let isSideNavOpen = false;
  let isOpen = false;
  let selected = "0";
  let transitions = {
    0: {
      text: "Default (duration: 200ms)",
      value: { duration: 200 },
    },
    1: {
      text: "Custom (duration: 600ms, delay: 50ms, easing: expoIn)",
      value: { duration: 600, delay: 50, easing: expoIn },
    },
    2: {
      text: "Disabled",
      value: false,
    },
  };
</script>

<Header companyName="IBM" platformName="Carbon Svelte" bind:isSideNavOpen>
  <svelte:fragment slot="skipToContent">
    <SkipToContent />
  </svelte:fragment>
  <HeaderUtilities>
    <HeaderAction bind:isOpen transition={transitions[selected].value}>
      <HeaderPanelLinks>
        <HeaderPanelDivider>Switcher subject 1</HeaderPanelDivider>
        <HeaderPanelLink>Switcher item 1</HeaderPanelLink>
        <HeaderPanelDivider>Switcher subject 2</HeaderPanelDivider>
        <HeaderPanelLink>Switcher item 1</HeaderPanelLink>
        <HeaderPanelLink>Switcher item 2</HeaderPanelLink>
        <HeaderPanelLink>Switcher item 3</HeaderPanelLink>
        <HeaderPanelLink>Switcher item 4</HeaderPanelLink>
        <HeaderPanelLink>Switcher item 5</HeaderPanelLink>
      </HeaderPanelLinks>
    </HeaderAction>
  </HeaderUtilities>
</Header>

<SideNav bind:isOpen={isSideNavOpen}>
  <SideNavItems>
    <SideNavLink text="Link 1" />
    <SideNavLink text="Link 2" />
    <SideNavLink text="Link 3" />
    <SideNavMenu text="Menu">
      <SideNavMenuItem href="/" text="Link 1" />
      <SideNavMenuItem href="/" text="Link 2" />
      <SideNavMenuItem href="/" text="Link 3" />
    </SideNavMenu>
  </SideNavItems>
</SideNav>

<Content>
  <Grid>
    <Row>
      <Column>
        <h1>HeaderSwitcher</h1>
        <p>
          Select a transition option below and click on the App Switcher icon in
          the top right.
        </p>
        <TileGroup legendText="App switcher transitions" bind:selected>
          {#each Object.keys(transitions) as key}
            <RadioTile value={key}>{transitions[key].text}</RadioTile>
          {/each}
        </TileGroup>
      </Column>
    </Row>
  </Grid>
</Content>
```

### Header with multiple switchers

Multiple switchers can be used, and the switcher button can be customized. For
example, display a tooltip using `iconDescription`.

Control the tooltip alignment using `tooltipAlignment`.

Note that providing `text` overrides the tooltip.

```svelte
<script>
  import {
    Column,
    Content,
    Grid,
    Header,
    HeaderAction,
    HeaderPanelDivider,
    HeaderPanelLink,
    HeaderPanelLinks,
    HeaderUtilities,
    Row,
    SkipToContent,
  } from "carbon-components-svelte";
  import SettingsAdjust from "carbon-icons-svelte/lib/SettingsAdjust.svelte";
  import UserAvatarFilledAlt from "carbon-icons-svelte/lib/UserAvatarFilledAlt.svelte";

  let isOpen1 = false;
  let isOpen2 = false;
  let isOpen3 = false;
</script>

<Header companyName="IBM" platformName="Carbon Svelte" isSideNavOpen>
  <svelte:fragment slot="skipToContent">
    <SkipToContent />
  </svelte:fragment>
  <HeaderUtilities>
    <HeaderAction
      bind:isOpen={isOpen1}
      iconDescription="Settings"
      tooltipAlignment="start"
      icon={SettingsAdjust}
      on:open={() => {
        isOpen2 = false;
        isOpen3 = false;
      }}
    >
      <HeaderPanelLinks>
        <HeaderPanelDivider>Switcher subject 1</HeaderPanelDivider>
        <HeaderPanelLink>Switcher item 1</HeaderPanelLink>
        <HeaderPanelDivider>Switcher subject 2</HeaderPanelDivider>
        <HeaderPanelLink>Switcher item 1</HeaderPanelLink>
      </HeaderPanelLinks>
    </HeaderAction>
    <HeaderAction
      bind:isOpen={isOpen2}
      iconDescription="Profile"
      icon={UserAvatarFilledAlt}
      on:open={() => {
        isOpen1 = false;
        isOpen3 = false;
      }}
    >
      <HeaderPanelLinks>
        <HeaderPanelDivider>Switcher subject 1</HeaderPanelDivider>
        <HeaderPanelLink>Switcher item 1</HeaderPanelLink>
        <HeaderPanelDivider>Switcher subject 2</HeaderPanelDivider>
        <HeaderPanelLink>Switcher item 1</HeaderPanelLink>
      </HeaderPanelLinks>
    </HeaderAction>
    <HeaderAction
      bind:isOpen={isOpen3}
      text="Switcher text"
      on:open={() => {
        isOpen1 = false;
        isOpen2 = false;
      }}
    >
      <HeaderPanelLinks>
        <HeaderPanelDivider>Switcher subject 1</HeaderPanelDivider>
        <HeaderPanelLink>Switcher item 1</HeaderPanelLink>
      </HeaderPanelLinks>
    </HeaderAction>
  </HeaderUtilities>
</Header>

<Content>
  <Grid>
    <Row>
      <Column>
        <h1>Welcome</h1>
      </Column>
    </Row>
  </Grid>
</Content>
```

### Header with global search

Add a global search component to the header.

```svelte
<script>
  import {
    Button,
    Column,
    Content,
    Grid,
    Header,
    HeaderSearch,
    HeaderUtilities,
    Row,
    SkipToContent,
  } from "carbon-components-svelte";

  const data = [
    {
      href: "/",
      text: "Kubernetes Service",
      description:
        "Deploy secure, highly available apps in a native Kubernetes experience. IBM Cloud Kubernetes Service creates a cluster of compute hosts and deploys highly available containers.",
    },
    {
      href: "/",
      text: "Red Hat OpenShift on IBM Cloud",
      description:
        "Deploy and secure enterprise workloads on native OpenShift with developer focused tools to run highly available apps. OpenShift clusters build on Kubernetes container orchestration that offers consistency and flexibility in operations.",
    },
    {
      href: "/",
      text: "Container Registry",
      description:
        "Securely store container images and monitor their vulnerabilities in a private registry.",
    },
    {
      href: "/",
      text: "Code Engine",
      description:
        "Run your application, job, or container on a managed serverless platform.",
    },
  ];

  let ref = null;
  let active = false;
  let value = "";
  let selectedResultIndex = 0;
  let events = [];

  $: lowerCaseValue = value.toLowerCase();
  $: results =
    value.length > 0
      ? data.filter((item) => {
          return (
            item.text.toLowerCase().includes(lowerCaseValue) ||
            item.description.includes(lowerCaseValue)
          );
        })
      : [];

  $: console.log("ref", ref);
  $: console.log("active", active);
  $: console.log("value", value);
  $: console.log("selectedResultIndex", selectedResultIndex);
</script>

<Header companyName="IBM" platformName="Carbon Svelte">
  <svelte:fragment slot="skipToContent">
    <SkipToContent />
  </svelte:fragment>
  <HeaderUtilities>
    <HeaderSearch
      bind:ref
      bind:active
      bind:value
      bind:selectedResultIndex
      placeholder="Search services"
      {results}
      on:active={() => {
        events = [...events, { type: "active" }];
      }}
      on:inactive={() => {
        events = [...events, { type: "inactive" }];
      }}
      on:clear={() => {
        events = [...events, { type: "clear" }];
      }}
      on:select={(e) => {
        events = [...events, { type: "select", ...e.detail }];
      }}
    />
  </HeaderUtilities>
</Header>

<Content>
  <Grid>
    <Row>
      <Column>
        <h1>HeaderSearch</h1>
        <Button
          on:click={() => {
            active = true;
          }}
        >
          Activate the search bar
        </Button>
        <h2>Reactive values</h2>
        <p><strong>active</strong>: {active}</p>
        <p><strong>value</strong>: {value}</p>
        <p><strong>selectedResultIndex</strong>: {selectedResultIndex}</p>
        <h2>Events</h2>
        <p>
          Click the button and search for something. Dispatched events are
          logged below:
        </p>
        <div style:overflow-x="auto">
          {#each events as { type, ...rest }}
            <div style:margin-bottom="var(--cds-layout-01)">
              <div><strong>on:{type}</strong></div>
              {#if Object.keys(rest).length > 0}
                <pre>{JSON.stringify(rest, null, 2)}</pre>
              {/if}
            </div>
          {/each}
        </div>
      </Column>
    </Row>
  </Grid>
</Content>
```

### Header with utilities

Include utility components in the header using header utilities.

```svelte
<script>
  import {
    Column,
    Content,
    Grid,
    Header,
    HeaderGlobalAction,
    HeaderUtilities,
    Row,
    SideNav,
    SideNavItems,
    SideNavLink,
    SideNavMenu,
    SideNavMenuItem,
    SkipToContent,
  } from "carbon-components-svelte";
  import Logout from "carbon-icons-svelte/lib/Logout.svelte";
  import SettingsAdjust from "carbon-icons-svelte/lib/SettingsAdjust.svelte";
  import UserAvatarFilledAlt from "carbon-icons-svelte/lib/UserAvatarFilledAlt.svelte";

  let isSideNavOpen = false;
</script>

<Header companyName="IBM" platformName="Carbon Svelte" bind:isSideNavOpen>
  <svelte:fragment slot="skipToContent">
    <SkipToContent />
  </svelte:fragment>
  <HeaderUtilities>
    <HeaderGlobalAction
      iconDescription="Settings"
      tooltipAlignment="start"
      icon={SettingsAdjust}
    />
    <HeaderGlobalAction iconDescription="Profile" icon={UserAvatarFilledAlt} />
    <HeaderGlobalAction
      iconDescription="Log out"
      tooltipAlignment="end"
      icon={Logout}
    />
  </HeaderUtilities>
</Header>

<SideNav bind:isOpen={isSideNavOpen}>
  <SideNavItems>
    <SideNavLink text="Link 1" />
    <SideNavLink text="Link 2" />
    <SideNavLink text="Link 3" />
    <SideNavMenu text="Menu">
      <SideNavMenuItem href="/" text="Link 1" />
      <SideNavMenuItem href="/" text="Link 2" />
      <SideNavMenuItem href="/" text="Link 3" />
    </SideNavMenu>
  </SideNavItems>
</SideNav>

<Content>
  <Grid>
    <Row>
      <Column>
        <h1>Welcome</h1>
      </Column>
    </Row>
  </Grid>
</Content>
```

### Header with persisted hamburger menu

Create a header with a persistent hamburger menu state.

```svelte
<script>
  import {
    Column,
    Content,
    Grid,
    Header,
    HeaderNav,
    HeaderNavItem,
    HeaderNavMenu,
    Row,
    SideNav,
    SideNavItems,
    SideNavLink,
    SideNavMenu,
    SideNavMenuItem,
    SkipToContent,
  } from "carbon-components-svelte";

  let isSideNavOpen = false;
</script>

<Header
  persistentHamburgerMenu={true}
  companyName="IBM"
  platformName="Carbon Svelte"
  bind:isSideNavOpen
>
  <svelte:fragment slot="skipToContent">
    <SkipToContent />
  </svelte:fragment>
  <HeaderNav>
    <HeaderNavItem href="/" text="Link 1" />
    <HeaderNavItem href="/" text="Link 2" />
    <HeaderNavItem href="/" text="Link 3" />
    <HeaderNavMenu text="Menu">
      <HeaderNavItem href="/" text="Link 1" />
      <HeaderNavItem href="/" text="Link 2" />
      <HeaderNavItem href="/" text="Link 3" />
    </HeaderNavMenu>
  </HeaderNav>
</Header>

<SideNav bind:isOpen={isSideNavOpen}>
  <SideNavItems>
    <SideNavLink text="Link 1" />
    <SideNavLink text="Link 2" />
    <SideNavLink text="Link 3" />
    <SideNavMenu text="Menu">
      <SideNavMenuItem href="/" text="Link 1" />
      <SideNavMenuItem href="/" text="Link 2" />
      <SideNavMenuItem href="/" text="Link 3" />
    </SideNavMenu>
  </SideNavItems>
</SideNav>

<Content>
  <Grid>
    <Row>
      <Column>
        <h1>Welcome</h1>
      </Column>
    </Row>
  </Grid>
</Content>
```

### Header with toast notification

Integrate toasts with the UI Shell. This example triggers a toast, which appears
in the top right corner, below the header.

```svelte
<script>
  import {
    Button,
    ButtonSet,
    Column,
    Content,
    Grid,
    Header,
    NotificationQueue,
    Row,
    SkipToContent,
    Stack,
  } from "carbon-components-svelte";

  let queue;
  let queuePosition = "top-right";

  const triggerToast = (position) => {
    queuePosition = position;
    queue.add({
      kind: "success",
      title: "Success",
      subtitle: "Your action was completed successfully.",
      timeout: 5000,
    });
  };
</script>

<Header companyName="IBM" platformName="Carbon Svelte">
  <svelte:fragment slot="skipToContent">
    <SkipToContent />
  </svelte:fragment>
</Header>

<NotificationQueue bind:this={queue} position={queuePosition} />

<Content>
  <Grid>
    <Row>
      <Column>
        <Stack gap={6}>
          <h1>Welcome</h1>
          <p>
            Click the buttons below to trigger toast notifications in different
            positions.
          </p>
          <ButtonSet>
            <Button on:click={() => triggerToast("top-right")}>
              Top right
            </Button>
            <Button on:click={() => triggerToast("bottom-right")}>
              Bottom right
            </Button>
          </ButtonSet>
        </Stack>
      </Column>
    </Row>
  </Grid>
</Content>
```

---

### Component API

#### `Header` props

| Prop                       | Type                        | Description                                                                                                                                                                                                                                                                  | Default     |
| -------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `isSideNavOpen` (Reactive) | `boolean`                   | Set to `true` to open the side nav                                                                                                                                                                                                                                           | `false`     |
| `ref` (Reactive)           | `null \| HTMLAnchorElement` | Obtain a reference to the HTML anchor element                                                                                                                                                                                                                                | `null`      |
| `expandedByDefault`        | `boolean`                   | Set to `false` to hide the side nav by default                                                                                                                                                                                                                               | `true`      |
| `uiShellAriaLabel`         | `string`                    | Specify the ARIA label for the header.                                                                                                                                                                                                                                       | _undefined_ |
| `href`                     | `string`                    | Specify the `href` attribute.                                                                                                                                                                                                                                                | _undefined_ |
| `companyName`              | `string`                    | Specify the company name.<br /><br />Alternatively, use the named slot "company".                                                                                                                                                                                            | _undefined_ |
| `platformName`             | `string`                    | Specify the platform name.<br />Alternatively, use the named slot "platform".                                                                                                                                                                                                | `""`        |
| `persistentHamburgerMenu`  | `boolean`                   | Set to `true` to persist the hamburger menu                                                                                                                                                                                                                                  | `false`     |
| `expansionBreakpoint`      | `number`                    | The window width (px) at which the SideNav is expanded and the hamburger menu is hidden.<br />1056 represents the "large" breakpoint in pixels from the Carbon Design System:<br />- small: 320<br />- medium: 672<br />- large: 1056<br />- x-large: 1312<br />- max: 1584. | `1056`      |
| `iconMenu`                 | `any`                       | Specify the icon to render for the closed state.                                                                                                                                                                                                                             | `Menu`      |
| `iconClose`                | `any`                       | Specify the icon to render for the opened state.                                                                                                                                                                                                                             | `Close`     |
| `ariaLabelMenu`            | `string`                    | Specify the ARIA label for the hamburger menu.<br />Defaults to "Open menu" or "Close menu" based on `isSideNavOpen` state.                                                                                                                                                  | _undefined_ |

#### `Header` slots

| Slot            | Detail                  |
| --------------- | ----------------------- |
| `default`       | `Record<string, never>` |
| `company`       | `Record<string, never>` |
| `platform`      | `Record<string, never>` |
| `skipToContent` | `Record<string, never>` |

#### `Header` forwarded events

| Event      |
| ---------- |
| `on:click` |

#### `Header` $$restProps

`Header` spreads `$$restProps` to the `a` element.

#### `HeaderAction` props

| Prop                         | Type                                               | Description                                                                                                                       | Default             |
| ---------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `isOpen` (Reactive)          | `boolean`                                          | Set to `true` to open the panel                                                                                                   | `false`             |
| `ref` (Reactive)             | `null \| HTMLButtonElement`                        | Obtain a reference to the button HTML element                                                                                     | `null`              |
| `icon`                       | `any`                                              | Specify the icon to render when the action panel is closed.                                                                       | `Switcher`          |
| `closeIcon`                  | `any`                                              | Specify the icon to render when the action panel is open.                                                                         | `Close`             |
| `text`                       | `string`                                           | Specify the text displayed next to the icon.<br />Alternatively, use the named slot "textChildren".                               | _undefined_         |
| `iconDescription`            | `string`                                           | Specify an icon tooltip. The tooltip will not be displayed<br />if either the `text` prop or a named slot="textChildren" is used. | _undefined_         |
| `tooltipAlignment`           | `"start" \| "center" \| "end"`                     | Set the alignment of the tooltip relative to the icon.<br />Only applies when `iconDescription` is provided.                      | `"center"`          |
| `transition`                 | `false \| import("svelte/transition").SlideParams` | Customize the panel transition (i.e., `transition:slide`).<br />Set to `false` to disable the transition.                         | `{ duration: 200 }` |
| `preventCloseOnClickOutside` | `boolean`                                          | Set to `true` to prevent the panel from closing when clicking outside                                                             | `false`             |

#### `HeaderAction` slots

| Slot           | Detail                  |
| -------------- | ----------------------- |
| `default`      | `Record<string, never>` |
| `closeIcon`    | `Record<string, never>` |
| `icon`         | `Record<string, never>` |
| `textChildren` | `Record<string, never>` |

#### `HeaderAction` forwarded events

| Event      |
| ---------- |
| `on:click` |

#### `HeaderAction` dispatched events

| Event      | Detail |
| ---------- | ------ |
| `on:open`  | `null` |
| `on:close` | `null` |

#### `HeaderAction` $$restProps

`HeaderAction` spreads `$$restProps` to the `button` element.

#### `HeaderActionLink` props

| Prop             | Type                        | Description                                   | Default     |
| ---------------- | --------------------------- | --------------------------------------------- | ----------- |
| `ref` (Reactive) | `null \| HTMLAnchorElement` | Obtain a reference to the HTML anchor element | `null`      |
| `linkIsActive`   | `boolean`                   | Set to `true` to use the active state         | `false`     |
| `href`           | `string`                    | Specify the `href` attribute.                 | _undefined_ |
| `icon`           | `any`                       | Specify the icon to render.                   | _undefined_ |

#### `HeaderActionLink` slots

| Slot   | Detail                  |
| ------ | ----------------------- |
| `icon` | `Record<string, never>` |

#### `HeaderActionLink` forwarded events

| Event      |
| ---------- |
| `on:click` |

#### `HeaderActionLink` $$restProps

`HeaderActionLink` spreads `$$restProps` to the `a` element.

#### `HeaderSearch` props

| Prop                             | Type                       | Description                                        | Default |
| -------------------------------- | -------------------------- | -------------------------------------------------- | ------- |
| `value` (Reactive)               | `string`                   | Specify the search input value                     | `""`    |
| `active` (Reactive)              | `boolean`                  | Set to `true` to activate and focus the search bar | `false` |
| `ref` (Reactive)                 | `null \| HTMLInputElement` | Obtain a reference to the input HTML element       | `null`  |
| `selectedResultIndex` (Reactive) | `number`                   | Specify the selected result index.                 | `0`     |
| `results`                        | `ReadonlyArray<Result>`    | Render a list of search results.                   | `[]`    |

#### `HeaderSearch` typedefs

```ts
type HeaderSearchResult = {
  href: string;
  text: string;
  description?: string;
};
```

#### `HeaderSearch` slots

| Slot      | Detail                                                |
| --------- | ----------------------------------------------------- |
| `default` | `{<br /> result: Result;<br /> index: number;<br />}` |

#### `HeaderSearch` forwarded events

| Event        |
| ------------ |
| `on:change`  |
| `on:input`   |
| `on:focus`   |
| `on:blur`    |
| `on:keydown` |
| `on:paste`   |

#### `HeaderSearch` dispatched events

| Event         | Detail                                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------ |
| `on:active`   | `null`                                                                                           |
| `on:inactive` | `null`                                                                                           |
| `on:clear`    | `null`                                                                                           |
| `on:select`   | `{<br /> value: string;<br /> selectedResultIndex: number;<br /> selectedResult: Result;<br />}` |

#### `HeaderSearch` $$restProps

`HeaderSearch` spreads `$$restProps` to the `input` element.

#### `HeaderNav` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `HeaderNav` $$restProps

`HeaderNav` spreads `$$restProps` to the `nav` element.

#### `HeaderNavItem` props

| Prop             | Type                        | Description                                   | Default     |
| ---------------- | --------------------------- | --------------------------------------------- | ----------- |
| `ref` (Reactive) | `null \| HTMLAnchorElement` | Obtain a reference to the HTML anchor element | `null`      |
| `href`           | `string`                    | Specify the `href` attribute.                 | _undefined_ |
| `text`           | `string`                    | Specify the text.                             | _undefined_ |
| `isSelected`     | `boolean`                   | Set to `true` to select the item              | `false`     |

#### `HeaderNavItem` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `HeaderNavItem` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:keyup`      |
| `on:keydown`    |
| `on:focus`      |
| `on:blur`       |

#### `HeaderNavItem` $$restProps

`HeaderNavItem` spreads `$$restProps` to the `a` element.

#### `HeaderNavMenu` props

| Prop                  | Type                        | Description                                   | Default     |
| --------------------- | --------------------------- | --------------------------------------------- | ----------- |
| `expanded` (Reactive) | `boolean`                   | Set to `true` to toggle the expanded state    | `false`     |
| `ref` (Reactive)      | `null \| HTMLAnchorElement` | Obtain a reference to the HTML anchor element | `null`      |
| `href`                | `string`                    | Specify the `href` attribute                  | `"/"`       |
| `text`                | `string`                    | Specify the text.                             | _undefined_ |

#### `HeaderNavMenu` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `HeaderNavMenu` forwarded events

| Event           |
| --------------- |
| `on:keydown`    |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |
| `on:keyup`      |
| `on:focus`      |
| `on:blur`       |

#### `HeaderNavMenu` $$restProps

`HeaderNavMenu` spreads `$$restProps` to the `a` element.

#### `HeaderPanelDivider` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `HeaderPanelLink` props

| Prop             | Type                        | Description                                   | Default     |
| ---------------- | --------------------------- | --------------------------------------------- | ----------- |
| `ref` (Reactive) | `null \| HTMLAnchorElement` | Obtain a reference to the HTML anchor element | `null`      |
| `href`           | `string`                    | Specify the `href` attribute.                 | _undefined_ |

#### `HeaderPanelLink` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `HeaderPanelLink` forwarded events

| Event      |
| ---------- |
| `on:click` |

#### `HeaderPanelLink` $$restProps

`HeaderPanelLink` spreads `$$restProps` to the `a` element.

#### `HeaderPanelLinks` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `HeaderUtilities` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `SideNav` props

| Prop                  | Type      | Description                                                                                                                                                                                                                                                                  | Default     |
| --------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `isOpen` (Reactive)   | `boolean` | Set to `true` to toggle the expanded state                                                                                                                                                                                                                                   | `false`     |
| `fixed`               | `boolean` | Set to `true` to use the fixed variant                                                                                                                                                                                                                                       | `false`     |
| `rail`                | `boolean` | Set to `true` to use the rail variant                                                                                                                                                                                                                                        | `false`     |
| `ariaLabel`           | `string`  | Specify the ARIA label for the nav.                                                                                                                                                                                                                                          | _undefined_ |
| `expansionBreakpoint` | `number`  | The window width (px) at which the SideNav is expanded and the hamburger menu is hidden.<br />1056 represents the "large" breakpoint in pixels from the Carbon Design System:<br />- small: 320<br />- medium: 672<br />- large: 1056<br />- x-large: 1312<br />- max: 1584. | `1056`      |

#### `SideNav` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `SideNav` dispatched events

| Event              | Detail |
| ------------------ | ------ |
| `on:open`          | `null` |
| `on:close`         | `null` |
| `on:click:overlay` | `null` |

#### `SideNav` $$restProps

`SideNav` spreads `$$restProps` to the `nav` element.

#### `SideNavItems` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `SideNavLink` props

| Prop             | Type                        | Description                                   | Default     |
| ---------------- | --------------------------- | --------------------------------------------- | ----------- |
| `ref` (Reactive) | `null \| HTMLAnchorElement` | Obtain a reference to the HTML anchor element | `null`      |
| `isSelected`     | `boolean`                   | Set to `true` to select the current link      | `false`     |
| `href`           | `string`                    | Specify the `href` attribute.                 | _undefined_ |
| `text`           | `string`                    | Specify the text.                             | _undefined_ |
| `icon`           | `any`                       | Specify the icon to render.                   | _undefined_ |

#### `SideNavLink` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |
| `icon`    | `Record<string, never>` |

#### `SideNavLink` forwarded events

| Event      |
| ---------- |
| `on:click` |

#### `SideNavLink` $$restProps

`SideNavLink` spreads `$$restProps` to the `a` element.

#### `SideNavMenu` props

| Prop                  | Type                        | Description                                   | Default     |
| --------------------- | --------------------------- | --------------------------------------------- | ----------- |
| `expanded` (Reactive) | `boolean`                   | Set to `true` to toggle the expanded state    | `false`     |
| `ref` (Reactive)      | `null \| HTMLButtonElement` | Obtain a reference to the HTML button element | `null`      |
| `text`                | `string`                    | Specify the text.                             | _undefined_ |
| `icon`                | `any`                       | Specify the icon to render.                   | _undefined_ |

#### `SideNavMenu` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |
| `icon`    | `Record<string, never>` |

#### `SideNavMenu` forwarded events

| Event      |
| ---------- |
| `on:click` |

#### `SideNavMenu` $$restProps

`SideNavMenu` spreads `$$restProps` to the `button` element.

#### `SideNavMenuItem` props

| Prop             | Type                        | Description                                   | Default     |
| ---------------- | --------------------------- | --------------------------------------------- | ----------- |
| `ref` (Reactive) | `null \| HTMLAnchorElement` | Obtain a reference to the HTML anchor element | `null`      |
| `isSelected`     | `boolean`                   | Set to `true` to select the item              | `false`     |
| `href`           | `string`                    | Specify the `href` attribute.                 | _undefined_ |
| `text`           | `string`                    | Specify the item text.                        | _undefined_ |

#### `SideNavMenuItem` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `SideNavMenuItem` forwarded events

| Event      |
| ---------- |
| `on:click` |

#### `SideNavMenuItem` $$restProps

`SideNavMenuItem` spreads `$$restProps` to the `a` element.

#### `Content` props

| Prop | Type     | Description                         | Default          |
| ---- | -------- | ----------------------------------- | ---------------- |
| `id` | `string` | Specify the id for the main element | `"main-content"` |

#### `Content` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `Content` $$restProps

`Content` spreads `$$restProps` to the `main` element.

#### `SkipToContent` props

| Prop       | Type     | Description                  | Default           |
| ---------- | -------- | ---------------------------- | ----------------- |
| `href`     | `string` | Specify the `href` attribute | `"#main-content"` |
| `tabindex` | `string` | Specify the tabindex         | `"0"`             |

#### `SkipToContent` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `SkipToContent` forwarded events

| Event      |
| ---------- |
| `on:click` |

#### `SkipToContent` $$restProps

`SkipToContent` spreads `$$restProps` to the `a` element.

#### `HeaderGlobalAction` props

| Prop             | Type                | Description                                    | Default     |
| ---------------- | ------------------- | ---------------------------------------------- | ----------- |
| `ref` (Reactive) | `HTMLButtonElement` | Obtain a reference to the HTML button element. | `null`      |
| `isActive`       | `boolean`           | Set to `true` to use the active variant        | `false`     |
| `icon`           | `any`               | Specify the icon to render.                    | _undefined_ |

#### `HeaderGlobalAction` forwarded events

| Event      |
| ---------- |
| `on:click` |

#### `HeaderGlobalAction` $$restProps

`HeaderGlobalAction` spreads `$$restProps` to the `Button` component.


## UnorderedList

Unordered lists provide a styled unordered list that supports nested lists,
links, and expressive typography. They are ideal for displaying bulleted content
in your interface.

> [!TIP] Consider using the [RecursiveList](/components/RecursiveList#unordered)
> component for rendering tree structured data.

### Default

Create a basic unordered list with list item components.

```svelte
<script>
  import { ListItem, UnorderedList } from "carbon-components-svelte";
</script>

<UnorderedList>
  <ListItem>Unordered list item</ListItem>
  <ListItem>Unordered list item</ListItem>
  <ListItem>Unordered list item</ListItem>
</UnorderedList>
```

### With links

Add links to list items by wrapping them in link components.

```svelte
<script>
  import { Link, ListItem, UnorderedList } from "carbon-components-svelte";
</script>

<UnorderedList>
  <ListItem>
    <Link href="#">Unordered list item</Link>
  </ListItem>
  <ListItem>
    <Link href="#">Unordered list item</Link>
  </ListItem>
  <ListItem>
    <Link href="#">Unordered list item</Link>
  </ListItem>
</UnorderedList>
```

### Nested

Create nested lists by setting `nested` to `true` on child unordered list
components.

```svelte
<script>
  import { ListItem, UnorderedList } from "carbon-components-svelte";
</script>

<UnorderedList>
  <ListItem>
    Unordered list level 1
    <UnorderedList nested>
      <ListItem>Unordered list level 2</ListItem>
      <ListItem>
        Unordered list level 3
        <UnorderedList nested>
          <ListItem>Unordered list level 3</ListItem>
          <ListItem>Unordered list level 3</ListItem>
        </UnorderedList>
      </ListItem>
    </UnorderedList>
  </ListItem>
  <ListItem>Unordered list level 1</ListItem>
  <ListItem>Unordered list level 1</ListItem>
</UnorderedList>
```

### Expressive styles

Use Carbon's expressive typesetting by setting `expressive` to `true`.

```svelte
<script>
  import { Link, ListItem, UnorderedList } from "carbon-components-svelte";
</script>

<UnorderedList expressive>
  <ListItem><Link size="lg" href="#">Unordered list item</Link></ListItem>
  <ListItem>Unordered list item</ListItem>
  <ListItem>Unordered list item</ListItem>
</UnorderedList>
```

---

### Component API

#### `UnorderedList` props

| Prop         | Type      | Description                                          | Default |
| ------------ | --------- | ---------------------------------------------------- | ------- |
| `nested`     | `boolean` | Set to `true` to use the nested variant              | `false` |
| `expressive` | `boolean` | Set to `true` to use Carbon's expressive typesetting | `false` |

#### `UnorderedList` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `UnorderedList` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `UnorderedList` $$restProps

`UnorderedList` spreads `$$restProps` to the `ul` element.

#### `ListItem` slots

| Slot      | Detail                  |
| --------- | ----------------------- |
| `default` | `Record<string, never>` |

#### `ListItem` forwarded events

| Event           |
| --------------- |
| `on:click`      |
| `on:mouseover`  |
| `on:mouseenter` |
| `on:mouseleave` |

#### `ListItem` $$restProps

`ListItem` spreads `$$restProps` to the `li` element.