Component

Copy and download

Published on

Description

Write the button you want, then mark it up as <button is="ds-copy"> or <button is="ds-download">. One writes a value to the clipboard, the other saves it as a text file. Without JavaScript neither button is upgraded, so give them nothing to do that the page cannot already do another way.

Both read the value the same way. data-value carries it directly; data-elem is a selector for the element holding it, read from value for a form control and trimmed text content for anything else. That selector is tried on the button’s parent before the document, so a button sitting beside what it acts on says code or output and needs no id. data-value wins when both are set.

Use them when the value is shown somewhere the reader can see, a DNS record, an API key, a header value, and the button sits beside it. For a whole block of preformatted text that carries its own controls, use Codeblock actions instead.

Example

Open in new tab
View HTML markup 
<p><code id="dns-record">tardisec-verification=abc123def456</code></p>
<div class="group"><button type="button" is="ds-copy" data-elem="#dns-record"><svg class="icon" aria-hidden="true">
      <use href="/img/icons.svg#copy"></use>
    </svg><span>Copy</span></button> <button type="button" is="ds-download" data-elem="#dns-record" data-filename="dns.txt"><svg class="icon" aria-hidden="true">
      <use href="/img/icons.svg#download"></use>
    </svg><span>Download</span></button> <button type="button" is="ds-copy" data-value="tardisec-verification=abc123def456" data-i18n-copied="Record copied"><svg class="icon" aria-hidden="true">
      <use href="/img/icons.svg#copy"></use>
    </svg><span>Copy record</span></button></div>

Accessibility

  • Both are native <button> elements, so they are reachable by keyboard and activated with Enter or Space.
  • The accessible name comes from the markup you write. Add class="visually-hidden" to the label for an icon-only button rather than dropping it.
  • ds-copy swaps the text of the button's <span> to Copied for two seconds and marks it aria-live="polite", so success is announced rather than shown only in colour. The authored text is what it restores, so translation stays in the markup.
  • A button with no <span> still copies, it just has nothing to announce with.

References

  • Codeblock actions — the same two actions, built into a block of preformatted text
  • Codeblock — for code samples that also need syntax highlighting
  • Buttons — for the button markup itself

Variables

  • data-value — the value, written literally
  • data-elem — selector for the element holding the value, resolved inside the button’s parent first and then the document, used when data-value is absent
  • data-i18n-copied — ds-copy confirmation, defaults to Copied
  • data-i18n-copy-failed — ds-copy failure notice, defaults to Copy failed
  • data-filename — ds-download file name, defaults to download.txt