Skip to content

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 ​

erb
<%= 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 ​

NameDefaultDescription
valuenilThe text to copy. When it isn't empty, it is copied instead of the copy source's text.
fornilThe id of the copy source, the element whose text is copied when there is no value.
disabledfalseWhether the button ignores presses. A disabled button takes no focus and is announced as disabled.
feedback_duration2000How 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.

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

erb
<%= 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.

erb
<%= 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 %>
css
.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.

html
<div id="copy-status" role="status" class="sr-only"></div>
js
// 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 ​

erb
<%= 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 ​

js
import '@ambiki/impulse-view-components/clipboard-copy';

The component has no styles of its own.

JS API ​

Read here.

Released under the MIT License.