# Clipboard

URL: https://ark-ui.com/docs/components/clipboard
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/clipboard.mdx

A component to copy text to the clipboard

---

<ComponentPreview id="Clipboard" />

## Anatomy

To set up the Clipboard correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="clipboard" />

## Examples

Learn how to use the `Clipboard` component in your project. Let's take a look at the most basic example:

<Example id="basic" />

### Using Context

Access the clipboard state and methods using `Clipboard.Context`. This provides access to properties like `copied`,
`value`, and `setValue`

> Alternatively, you can use the `useClipboardContext` hook to access the clipboard context.

<Example id="context" />

### Copy Status

Use the `onStatusChange` prop to listen for copy operations. It exposes a `copied` property that you can use to display
a success message.

<Example id="copy-status" />

### Controlled

Control the clipboard value externally by managing the state yourself and using `onValueChange` to handle updates.

<Example id="controlled" />

### Root Provider

Use the `useClipboard` hook to create the clipboard store and pass it to the `Clipboard.RootProvider` component. This
allows you to have maximum control over the clipboard programmatically.

> If you're using the `Clipboard.RootProvider` component, you don't need to use the `Clipboard.Root` component.

<Example id="root-provider" />

### Custom Timeout

Configure the copy status timeout duration using the `timeout` prop. Default is 3000ms (3 seconds).

<Example id="custom-timeout" />

### Programmatic Copy

Trigger copy operations programmatically using the context's `copy()` method.

<Example id="programmatic" />

### Value Text

Use `Clipboard.ValueText` to display the current clipboard value.

<Example id="value-text" />

## API Reference

### Props

**Component API Reference**

#### React

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `string` | No | The initial value to be copied to the clipboard when rendered.
Use when you don't need to control the value of the clipboard. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; input: string; label: string }>` | No | The ids of the elements in the clipboard. Useful for composition. |
| `onStatusChange` | `(details: CopyStatusDetails) => void` | No | The function to be called when the value is copied to the clipboard |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | The function to be called when the value changes |
| `timeout` | `number` | No | The timeout for the copy operation |
| `value` | `string` | No | The controlled value of the clipboard |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | root |
| `[data-copied]` | Present when copied state is true |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | control |
| `[data-copied]` | Present when copied state is true |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `copied` | `string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...>` | No |  |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | input |
| `[data-copied]` | Present when copied state is true |
| `[data-readonly]` | Present when read-only |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | label |
| `[data-copied]` | Present when copied state is true |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseClipboardReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | trigger |
| `[data-copied]` | Present when copied state is true |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Solid

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `string` | No | The initial value to be copied to the clipboard when rendered.
Use when you don't need to control the value of the clipboard. |
| `ids` | `Partial<{ root: string; input: string; label: string }>` | No | The ids of the elements in the clipboard. Useful for composition. |
| `onStatusChange` | `(details: CopyStatusDetails) => void` | No | The function to be called when the value is copied to the clipboard |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | The function to be called when the value changes |
| `timeout` | `number` | No | The timeout for the copy operation |
| `value` | `string` | No | The controlled value of the clipboard |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | root |
| `[data-copied]` | Present when copied state is true |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | control |
| `[data-copied]` | Present when copied state is true |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `copied` | `number | boolean | Node | ArrayElement | (string & {})` | No |  |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | input |
| `[data-copied]` | Present when copied state is true |
| `[data-readonly]` | Present when read-only |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | label |
| `[data-copied]` | Present when copied state is true |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseClipboardReturn` | Yes |  |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | trigger |
| `[data-copied]` | Present when copied state is true |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Vue

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `string` | No | The initial value to be copied to the clipboard when rendered.
Use when you don't need to control the value of the clipboard. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; input: string; label: string }>` | No | The ids of the elements in the clipboard. Useful for composition. |
| `modelValue` | `string` | No | The v-model value of the clipboard |
| `timeout` | `number` | No | The timeout for the copy operation |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | root |
| `[data-copied]` | Present when copied state is true |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | control |
| `[data-copied]` | Present when copied state is true |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | input |
| `[data-copied]` | Present when copied state is true |
| `[data-readonly]` | Present when read-only |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | label |
| `[data-copied]` | Present when copied state is true |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `ClipboardApi<PropTypes>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | trigger |
| `[data-copied]` | Present when copied state is true |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Svelte

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `string` | No | The initial value to be copied to the clipboard when rendered.
Use when you don't need to control the value of the clipboard. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; input: string; label: string }>` | No | The ids of the elements in the clipboard. Useful for composition. |
| `onStatusChange` | `(details: CopyStatusDetails) => void` | No | The function to be called when the value is copied to the clipboard |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | The function to be called when the value changes |
| `ref` | `Element` | No |  |
| `timeout` | `number` | No | The timeout for the copy operation |
| `value` | `string` | No | The controlled value of the clipboard |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | root |
| `[data-copied]` | Present when copied state is true |


**Context Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `render` | `Snippet<[UseClipboardContext]>` | No |  |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | control |
| `[data-copied]` | Present when copied state is true |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `copied` | `Snippet<[]>` | No |  |
| `ref` | `Element` | No |  |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | input |
| `[data-copied]` | Present when copied state is true |
| `[data-readonly]` | Present when read-only |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | label |
| `[data-copied]` | Present when copied state is true |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseClipboardReturn` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | clipboard |
| `[data-part]` | trigger |
| `[data-copied]` | Present when copied state is true |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


### Context

These are the properties available when using `Clipboard.Context`, `useClipboardContext` hook or `useClipboard` hook.

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `copied` | `boolean` | Whether the value has been copied to the clipboard |
| `value` | `string` | The value to be copied to the clipboard |
| `setValue` | `(value: string) => void` | Set the value to be copied to the clipboard |
| `copy` | `VoidFunction` | Copy the value to the clipboard |