Clipboard copy
A button that copies text to the clipboard: a value rendered by the server, or the text of another element on the page. It emits an event once the text is copied, or when it couldn't be, and enters a short feedback state you can style. It shows and announces nothing of its own: how the user is told, with a toast, an icon swap, or not at all, is up to your app.
Usage
<%= render(Impulse::ClipboardCopyComponent.new(value: "https://example.com/meetings/123", class: "btn btn-primary")) do %>
Copy link
<% end %>The component renders <awc-clipboard-copy>, which is the button itself. It is announced as a button, takes focus, and is pressed with a click, Enter, or Space, like a native <button>. Its content is what the button shows: a label, an icon, or the value itself.
Arguments
Keyword arguments
| Name | Default | Description |
|---|---|---|
| value | nil | The text to copy. When it isn't empty, it is copied instead of the copy source's text. |
| for | nil | The id of the copy source, the element whose text is copied when there is no value. |
| disabled | false | Whether the button ignores presses. A disabled button takes no focus and is announced as disabled. |
| feedback_duration | 2000 | How long, in milliseconds, the button stays in its feedback state after a press. See Styling the feedback state. |
Any other keyword arguments, such as class or aria, are passed to the <awc-clipboard-copy> element as HTML attributes. The component adds no classes of its own.
Examples
Copying another element's text
Name the copy source by its id with for. A form control (<input>, <textarea> or <select>) gives its value; any other element gives its text as rendered, without its hidden content and with a line break between blocks. The text is read when the button is pressed, so changes made after rendering are copied.
<pre id="setup-command">bundle exec rails db:setup</pre>
<%= render(Impulse::ClipboardCopyComponent.new(for: "setup-command", class: "btn btn-sm btn-outline-secondary")) do %>
Copy command
<% end %>To copy something other than what the page shows, such as the text with a prefix, render it as the value.
Icon-only button
A button that shows only an icon needs an accessible name, given with aria-label.
<%= render(Impulse::ClipboardCopyComponent.new(value: reference_number, class: "btn btn-sm", aria: { label: "Copy reference number" })) do %>
<i class="bi bi-clipboard" aria-hidden="true"></i>
<% end %>When the button has a visible label, leave out aria-label, or start it with the visible label, so that speech input users can say what they see.
Styling the feedback state
For a short while after a press, the button is in a feedback state: :state(copied) once the text is copied, or :state(error) when nothing was. Style it to swap the icon, with no JavaScript. The state lasts 2 seconds; change it with feedback_duration:, in milliseconds. Another press starts it over.
<%= render(Impulse::ClipboardCopyComponent.new(value: meeting_link, feedback_duration: 1000, class: "btn btn-sm copy-link", aria: { label: "Copy link" })) do %>
<i class="bi bi-clipboard" aria-hidden="true"></i>
<i class="bi bi-check2" aria-hidden="true"></i>
<% end %>.copy-link .bi-check2,
.copy-link:state(copied) .bi-clipboard {
display: none;
}
.copy-link:state(copied) .bi-check2 {
display: inline;
}The state is a custom state, not an attribute, so a DOM morph doesn't end it early. Browsers without :state() (before Chrome 125, Firefox 126 and Safari 17.4) still copy, without the feedback state.
Announcing a copy
An icon swap is only seen. Screen reader users need to hear whether it copied too (WCAG 4.1.3), and the button doesn't announce it. Listen for awc-clipboard-copy:copied and awc-clipboard-copy:error, which bubble, and put a message in a live region, such as an element with role="status". A toast that is one already does this.
<div id="copy-status" role="status" class="sr-only"></div>// Emptied first, so that copying twice announces twice.
function announce(message) {
const status = document.getElementById('copy-status');
status.textContent = '';
setTimeout(() => {
status.textContent = message;
}, 100);
}
document.addEventListener('awc-clipboard-copy:copied', () => announce('Copied to clipboard'));
document.addEventListener('awc-clipboard-copy:error', () => announce('Copying to the clipboard failed'));The clipboard is only available on pages served over HTTPS or from localhost. Elsewhere, every press emits awc-clipboard-copy:error. See the JS API for each event's detail.
Disabling the button
<%= render(Impulse::ClipboardCopyComponent.new(value: "Hello", disabled: true, class: "btn btn-primary")) do %>
Copy
<% end %>Like a native disabled button, it takes no focus, and listeners on it and its ancestors don't hear its clicks. Bootstrap's .btn:disabled styles only match native form controls. Style a disabled button with awc-clipboard-copy[disabled], or add Bootstrap's disabled class.
Imports
import '@ambiki/impulse-view-components/clipboard-copy';The component has no styles of its own.