# Clipboard

URL: https://ark-ui.com/docs/components/clipboard
LLM: https://ark-ui.com/llms.txt/components/clipboard

A component to copy text to the clipboard

---



## Anatomy



```tsx
<Clipboard.Root>
  <Clipboard.Label />
  <Clipboard.Control>
    <Clipboard.Input />
    <Clipboard.Trigger>
      <Clipboard.Indicator />
    </Clipboard.Trigger>
  </Clipboard.Control>
</Clipboard.Root>
```

## Examples

```tsx
import { Clipboard } from '@ark-ui/react/clipboard'
import { CheckIcon, ClipboardCopyIcon } from 'lucide-react'
import styles from 'styles/clipboard.module.css'

export const Basic = () => {
  return (
    <Clipboard.Root className={styles.Root} value="https://ark-ui.com">
      <Clipboard.Label className={styles.Label}>Copy this link</Clipboard.Label>
      <Clipboard.Control className={styles.Control}>
        <Clipboard.Input className={styles.Input} />
        <Clipboard.Trigger className={styles.Trigger}>
          <Clipboard.Indicator className={styles.Indicator} copied={<CheckIcon />}>
            <ClipboardCopyIcon />
          </Clipboard.Indicator>
        </Clipboard.Trigger>
      </Clipboard.Control>
    </Clipboard.Root>
  )
}
```

### Controlled

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

```tsx
import { Clipboard } from '@ark-ui/react/clipboard'
import { CheckIcon, ClipboardCopyIcon } from 'lucide-react'
import { useState } from 'react'
import button from 'styles/button.module.css'
import styles from 'styles/clipboard.module.css'

export const Controlled = () => {
  const [url, setUrl] = useState('https://ark-ui.com')

  return (
    <div className="stack">
      <Clipboard.Root className={styles.Root} value={url} onValueChange={(details) => setUrl(details.value)}>
        <Clipboard.Label className={styles.Label}>Copy this link</Clipboard.Label>
        <Clipboard.Control className={styles.Control}>
          <Clipboard.Input className={styles.Input} />
          <Clipboard.Trigger className={styles.Trigger}>
            <Clipboard.Indicator className={styles.Indicator} copied={<CheckIcon />}>
              <ClipboardCopyIcon />
            </Clipboard.Indicator>
          </Clipboard.Trigger>
        </Clipboard.Control>
      </Clipboard.Root>

      <button className={button.Root} onClick={() => setUrl('https://chakra-ui.com')}>
        Change Url
      </button>
    </div>
  )
}
```

### Root Provider

An alternative way to control the clipboard is to use the `RootProvider` component and the `useClipboard` hook. This way
you can access the state and methods from outside the component.

```tsx
import { Clipboard, useClipboard } from '@ark-ui/react/clipboard'
import { CheckIcon, ClipboardCopyIcon } from 'lucide-react'
import styles from 'styles/clipboard.module.css'

export const RootProvider = () => {
  const clipboard = useClipboard({ value: 'https://ark-ui.com' })

  return (
    <div className="stack">
      <output>
        value: {clipboard.value}, copied: {String(clipboard.copied)}
      </output>
      <Clipboard.RootProvider className={styles.Root} value={clipboard}>
        <Clipboard.Label className={styles.Label}>Copy this link</Clipboard.Label>
        <Clipboard.Control className={styles.Control}>
          <Clipboard.Input className={styles.Input} />
          <Clipboard.Trigger className={styles.Trigger}>
            <Clipboard.Indicator className={styles.Indicator} copied={<CheckIcon />}>
              <ClipboardCopyIcon />
            </Clipboard.Indicator>
          </Clipboard.Trigger>
        </Clipboard.Control>
      </Clipboard.RootProvider>
    </div>
  )
}
```

### Context

Access the clipboard's state with `Clipboard.Context` or the `useClipboardContext` hook. You get properties like
`copied`, `value`, and `setValue`.

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

```tsx
import { Clipboard } from '@ark-ui/react/clipboard'
import { CheckIcon, ClipboardCopyIcon } from 'lucide-react'
import button from 'styles/button.module.css'
import styles from 'styles/clipboard.module.css'

export const Context = () => {
  return (
    <Clipboard.Root className={styles.Root} value="https://ark-ui.com">
      <Clipboard.Label className={styles.Label}>Copy this link</Clipboard.Label>
      <Clipboard.Context>
        {(clipboard) => (
          <button className={button.Root} onClick={() => clipboard.copy()}>
            {clipboard.copied ? <CheckIcon /> : <ClipboardCopyIcon />}
            {clipboard.copied ? 'Copied!' : 'Copy'}
          </button>
        )}
      </Clipboard.Context>
    </Clipboard.Root>
  )
}
```

### 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.

```tsx
import { Clipboard } from '@ark-ui/react/clipboard'
import { CheckIcon, ClipboardCopyIcon } from 'lucide-react'
import { useState } from 'react'
import styles from 'styles/clipboard.module.css'

export const CopyStatus = () => {
  const [copyCount, setCopyCount] = useState(0)

  return (
    <Clipboard.Root
      className={styles.Root}
      value="https://ark-ui.com"
      onStatusChange={(details) => {
        if (details.copied) setCopyCount((prev) => prev + 1)
      }}
    >
      <Clipboard.Control className={styles.Control}>
        <Clipboard.Trigger className={styles.Trigger}>
          <Clipboard.Indicator className={styles.Indicator} copied={<CheckIcon />}>
            <ClipboardCopyIcon />
          </Clipboard.Indicator>
          <Clipboard.ValueText />
        </Clipboard.Trigger>
      </Clipboard.Control>
      <p>Copied {copyCount} times</p>
    </Clipboard.Root>
  )
}
```

### Timeout

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

```tsx
import { Clipboard } from '@ark-ui/react/clipboard'
import { CheckIcon, ClipboardCopyIcon } from 'lucide-react'
import styles from 'styles/clipboard.module.css'

export const Timeout = () => {
  return (
    <Clipboard.Root className={styles.Root} value="https://ark-ui.com" timeout={5000}>
      <Clipboard.Label className={styles.Label}>Copy this link (5 second timeout)</Clipboard.Label>
      <Clipboard.Control className={styles.Control}>
        <Clipboard.Input className={styles.Input} />
        <Clipboard.Trigger className={styles.Trigger}>
          <Clipboard.Indicator className={styles.Indicator} copied={<CheckIcon />}>
            <ClipboardCopyIcon />
          </Clipboard.Indicator>
        </Clipboard.Trigger>
      </Clipboard.Control>
    </Clipboard.Root>
  )
}
```

### Value Text

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

```tsx
import { Clipboard } from '@ark-ui/react/clipboard'
import { CheckIcon, ClipboardCopyIcon } from 'lucide-react'
import styles from 'styles/clipboard.module.css'

export const ValueText = () => {
  return (
    <Clipboard.Root className={styles.Root} value="https://ark-ui.com">
      <Clipboard.Control className={styles.Control}>
        <Clipboard.ValueText className={styles.ValueText} />
        <Clipboard.Trigger className={styles.Trigger}>
          <Clipboard.Indicator className={styles.Indicator} copied={<CheckIcon />}>
            <ClipboardCopyIcon />
          </Clipboard.Indicator>
        </Clipboard.Trigger>
      </Clipboard.Control>
    </Clipboard.Root>
  )
}
```

## API Reference

### Props

### Root

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`defaultValue`**
Type: `string`
Required: false
Default Value: `undefined`
Description: 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`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The unique identifier of the machine.

**`ids`**
Type: `Partial<{ root: string; input: string; label: string }>`
Required: false
Default Value: `undefined`
Description: The ids of the elements in the clipboard. Useful for composition.

**`onStatusChange`**
Type: `(details: CopyStatusDetails) => void`
Required: false
Default Value: `undefined`
Description: The function to be called when the value is copied to the clipboard

**`onValueChange`**
Type: `(details: ValueChangeDetails) => void`
Required: false
Default Value: `undefined`
Description: The function to be called when the value changes

**`timeout`**
Type: `number`
Required: false
Default Value: `3000`
Description: The timeout for the copy operation

**`translations`**
Type: `IntlTranslations`
Required: false
Default Value: `undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`value`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The controlled value of the clipboard

#### Data Attributes

**`data-scope`**: clipboard
**`data-part`**: root
**`data-copied`**: Present when copied state is true

### Control

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: clipboard
**`data-part`**: control
**`data-copied`**: Present when copied state is true

### Indicator

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`copied`**
Type: `string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...>`
Required: false
Default Value: `undefined`
Description: undefined

### Input

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: clipboard
**`data-part`**: input
**`data-copied`**: Present when copied state is true
**`data-readonly`**: Present when read-only

### Label

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: clipboard
**`data-part`**: label
**`data-copied`**: Present when copied state is true

### RootProvider

#### Props

**`value`**
Type: `UseClipboardReturn`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Trigger

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: clipboard
**`data-part`**: trigger
**`data-copied`**: Present when copied state is true

### ValueText

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Context

**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 |