---
title: "Clipboard"
description: "Copy buttons and copy tags: copy text, an input's value or an element's text, and show a green tick for a moment, on every browser."
url: "https://susonwaiba.github.io/htmx-ui/docs/components/clipboard"
section: "Components"
---
# Clipboard
Copy buttons and copy tags: copy text, an input's value or an element's text, and show a green tick for a moment, on every browser.
```html
```
## Markup
- Any [button](https://susonwaiba.github.io/htmx-ui/docs/components/button) with `data-clipboard` copies when clicked. Say what with `data-clipboard-text` (see [What it copies](#source)).
- Add `.clipboard` and put both of its looks inside: `.clipboard-idle` (a copy icon, a label or both) and `.clipboard-done` (a tick, "Copied").
- After a copy the button gets `data-copied` for two seconds, which shows `.clipboard-done` with a green tick. The two looks share one space, so the button keeps its width when "Copy" becomes "Copied".
- An icon-only button needs `aria-label="Copy"` (or "Copy link", "Copy API key"…).
Screen readers hear "Copied" (or "Copy failed") through a polite live region, because a button's changed text isn't read out by itself. Set `data-clipboard-announce` to say something else, and `data-clipboard-timeout` (ms) to keep the tick longer.
## Icon, label or both
Leave out what you don't need: the icons, the labels, or one of each.
```html
```
## Variants
Every [button variant](https://susonwaiba.github.io/htmx-ui/docs/components/button) works. The tick is green on outline, ghost, secondary and link buttons; on a filled primary or danger button it keeps the button's text colour, so it stays readable.
```html
```
```html
```
## Sizes
The button sizes: `.btn-xs`, `.btn-sm`, default and `.btn-lg`, with or without `.btn-icon`.
```html
```
## Copy tag
A `.clipboard-tag` is a monospace chip that copies the text it shows: an install command, an id, a coupon code. The whole chip is the button. Put the text in a `data-clipboard-content` element and the two icons in a `.clipboard` span; give the button an `aria-label`. Long text is cut short with an ellipsis, but the whole of it is copied.
```html
```
The last one shows a shortened key but copies the whole of it: `copy=` in the macro, which writes `data-clipboard-text`. `.clipboard-tag-sm` / `.clipboard-tag-lg` size it and `.clipboard-tag-outline` gives it a border instead of a fill.
## What it copies
The first of these that is set:
| Attribute | Copies |
| --- | --- |
| `data-clipboard-text="…"` | That text. |
| `data-clipboard-url="/page.md"` | The text of that URL, fetched when clicked. The docs' "Copy Markdown" button works this way. |
| `data-clipboard-target="selector"` | The nearest element matching the selector, looking outward from the button: its own block first, then further out, so `#id` works and so does a class shared by many blocks (`.message-content`, or `pre:not([hidden]) code` in code blocks). For an input, textarea or select, its value, read when clicked (so it copies what the user typed); for any other element, its text. |
| `data-clipboard-content` | The text of that element inside the button (a copy tag). |
An input with a copy button: a read-only API key in an [input group](https://susonwaiba.github.io/htmx-ui/docs/components/input-group), and a share link the user can edit before copying.
```html
```
An element's text, such as an address:
```html
Ada Lovelace 12 Analytical Way London NW1 6XE
```
## Browsers and platforms
- **Secure pages** (https, and localhost while developing) copy with the asynchronous Clipboard API, supported by every current browser on desktop, Android and iOS.
- **Plain http, older browsers and iframes** without the `clipboard-write` permission fall back to `document.execCommand("copy")` on a hidden, read-only textarea. It is selected the way iOS Safari needs, doesn't open the phone keyboard or zoom the page, and focus goes back where it was.
- If both fail (a browser that blocks clipboard access), the button gets `data-copy-failed` for the same two seconds, its icon turns red, "Copy failed" is announced and `clipboard:error` fires.
- Browsers only allow copying in response to the user, so call it from a click, not on page load. With `data-clipboard-url`, the fetch is handed to the clipboard as a promise where the browser accepts one (Safari, Chrome), so the click still counts once the text arrives.
## Events and htmx
A copy fires a bubbling `clipboard:copy` with `detail.text` (or `clipboard:error`). Use it as an htmx trigger to record the copy, or add a [toast](https://susonwaiba.github.io/htmx-ui/docs/components/toast) with `data-toast` on the same button:
```html
```
```html Count copies on the server
```
Copy buttons htmx swaps in work at once: the behaviour runs again on new content.
## Nunjucks macros
`clipboard()` writes a copy button, `clipboard_tag()` a copy tag.
```jinja page.html
{% from "components/clipboard/clipboard.html" import clipboard, clipboard_tag %}
{{ clipboard(text="npm i htmx-ui") }}
{{ clipboard(target="#api-key", icon_only=true, variant="ghost", size="sm", label="Copy API key") }}
{{ clipboard(text=url, label="Copy link", copied="Link copied", variant="secondary", timeout=3000) }}
{{ clipboard(text=code, icon=false, copied_icon=false) }}
{{ clipboard_tag("npm i htmx-ui") }}
{{ clipboard_tag("hx_secret_••••3f9a", copy=key, variant="outline", size="sm", label="Copy secret key") }}
```
## Reference
| Class / attribute | Description |
| --- | --- |
| `data-clipboard` | Copy when clicked. On a button or a .clipboard-tag. |
| `.clipboard` | Stacks .clipboard-idle and .clipboard-done in one space. On the button, or a span inside a tag. |
| `.clipboard-idle / .clipboard-done` | The look before / after copying (shown while data-copied is set). |
| `.clipboard-tag` | A monospace chip that copies its text. Sizes: .clipboard-tag-sm / -lg. .clipboard-tag-outline. |
| `data-clipboard-text` | The text to copy. |
| `data-clipboard-target` | A selector: copy the nearest match's value or text. |
| `data-clipboard-url` | Copy the text of this URL, fetched when clicked. |
| `data-clipboard-content` | Inside the button: copy this element's text. |
| `data-clipboard-timeout` | How long data-copied stays, in ms (2000). |
| `data-clipboard-announce` | What screen readers hear ("Copied"). |
| `data-copied / data-copy-failed` | Set for the timeout after a copy / a failed copy. |
| `clipboard:copy / clipboard:error` | Events with detail { text }. |