Copy Button

Usage

When to use

• To copy plain text, large code snippets, and input values.
• When needing separation between the text-to-copy and the copy interaction.

When not to use

• To copy short code snippets, such as URLs, tokens, IDs, use a Copy Snippet.

Sizes

The Copy Button comes in small and medium sizes. Use the size that best fits the hierarchy of the UI.

Placement

Place the Copy Button as close to the content being copied as possible. Avoid too much visual separation between the content and the button to ensure users understand what will be copied to the clipboard.

Composition with other components

Since the CopyButton can target almost any associated DOM element, it can be composed with other Helios components to create and support more complex scenarios and use cases.

With form inputs

When combining the CopyButton with form inputs:

• Use the Fieldset form primitive.
• Wrap the Base input control (generally a TextInput, MaskedInput, or Textarea) and CopyButton in a container with an 8px gap between each element. This is not supported by the component out of the box, but can accomplished using a custom layout wrapper.
• Use the isIconOnly variant of the CopyButton as there is a enough visual association using this layout method.

This ensures that other form primitives (helper text, error, etc) will span the combined width of the input control and the CopyButton.

Single line inputs

A simple example composition of a CopyButton and TextInput or MaskedInput.

A more complex composition with helper and error text.

Multi-line inputs

In the case of a multi-line input (e.g., a Textarea or multi-line MaskedInput), align the CopyButton to the top of the control.

How to use this component

The basic invocation requires text and targetToCopy to be passed:

<p id="clipboardTarget">
  The button will copy the text in this paragraph element.
</p>
<Hds::Copy::Button @text="Copy" @targetToCopy="#clipboardTarget" />

Icon-only

<p id="clipboardTarget2">
  The button will copy the text in this paragraph element.
</p>
<Hds::Copy::Button @text="Copy" @isIconOnly={{true}} @targetToCopy="#clipboardTarget2" />

Sizes

The component supports small and medium sizes (medium is the default):

<p id="clipboardTarget3">
  The button will copy the text in this paragraph element.
</p>
<Hds::Copy::Button @text="Copy" @size="small" @targetToCopy="#clipboardTarget3" />

Full-width

This indicates that the component should take up the full-width of the parent container. It’s set to false by default.

<p id="clipboardTarget4">
  The button will copy the text in this paragraph element.
</p>
<Hds::Copy::Button @text="Copy" @targetToCopy="#clipboardTarget4" @isFullWidth={{true}} />

Text to Copy

The consumer can also indicate a string to be copied instead of indicating a target element:

<Hds::Copy::Button @text="Copy your secret key" @textToCopy="someSecretThingGoesHere" />

Composition with form inputs

These representative examples showcase the compositional recommendations in the guidelines using the Fieldset primitive.

With single line inputs

<Hds::Form::Fieldset @layout="vertical" as |F|>
  <F.Legend>Cluster name</F.Legend>
  <F.HelperText>This is some example helper text.</F.HelperText>
  <F.Control>
    <div class="doc-copy-button-composition-input-control">
      <Hds::Form::TextInput::Base
        @value="aws-east-cluster-01"
        id="cluster-name-example-text-input"
      />
      <Hds::Copy::Button
        @text="Copy"
        @isIconOnly={{true}} 
        @targetToCopy="#cluster-name-example-text-input"
      />
    </div>
  </F.Control>
  <F.Error>This is example error text.</F.Error>
</Hds::Form::Fieldset>

With multi-line inputs

<Hds::Form::Fieldset @layout="vertical" as |F|>
  <F.Legend>Cluster secret</F.Legend>
  <F.HelperText>This is some example helper text.</F.HelperText>
  <F.Control>
    <div class="doc-copy-button-composition-input-control">
      <Hds::Form::Textarea::Base
        @value="C9WhJuvE70CnTcqvNqptMhmnBHmMNXuj"
        id="cluster-name-example-textarea"
      />
      <Hds::Copy::Button
        @text="Copy"
        @isIconOnly={{true}}
        @targetToCopy="#cluster-name-example-textarea"
      />
    </div>
  </F.Control>
  <F.Error>This is example error text.</F.Error>
</Hds::Form::Fieldset>

Component API

This component uses the Clipboard API under the hood.

Copy::Button

Anatomy

States

Conformance rating

When used as recommended, there should not be any WCAG conformance issues with this component.

Applicable WCAG Success Criteria

This section is for reference only. This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.

4.15.0

Updated

Aligned private class properties to follow a standardized notation