Copy Button

Copies text data to the clipboard when the user clicks the trigger.

<pc-copy-button value="Placer Toolkit rocks!"></pc-copy-button>

Code

Copy buttons use the browser’s clipboard.writeText() method, which requires a secure context (HTTPS) in most browsers.

Demos

Custom labels

Copy buttons display feedback in a tooltip. You can customise the labels using the copy-label, success-label and error-label attributes.

<pc-copy-button
  value="Custom labels are easy"
  copy-label="Click to copy"
  success-label="You did it!"
  error-label="Whoops, your browser doesn’t support this!"
></pc-copy-button>

Code

Custom icons

Use the copy-icon, success-icon and error-icon slots to customise the icons that get displayed for each state. You can use <pc-icon> or your own images.

<pc-copy-button value="Copied from a copy button with custom icons">
  <pc-icon
      library="default"
      icon-style="regular"
      name="clipboard"
      slot="copy-icon"
  ></pc-icon>
  <pc-icon
      library="default"
      icon-style="regular"
      name="thumbs-up"
      slot="success-icon"
  ></pc-icon>
  <pc-icon
      library="default"
      icon-style="regular"
      name="thumbs-down"
      slot="error-icon"
  ></pc-icon>
</pc-copy-button>

Code

Copying values from other elements

Normally, the data that gets copied will come from the component’s value attribute, but you can copy data from any element within the same document by providing its id to the from attribute.

When using the from attribute, the element’s textContent will be copied by default. Passing an attribute or property modifier will let you copy data from one of the element’s attributes or properties instead.

To copy data from an attribute, use from="id[attribute]" where id is the id of the target element and attribute is the name of the attribute you’d like to copy. To copy data from a property, use from="id.property" where id is the id of the target element and property is the name of the property you’d like to copy.

<!-- Copies the span’s textContent -->
<span id="my-phone">+44 1234 567890</span>
<pc-copy-button from="my-phone"></pc-copy-button>

<br />

<!-- Copies the input’s “value” property -->
<pc-input
  type="text"
  id="my-input"
  value="User input"
  style="display: inline-block; max-width: 300px"
></pc-input>
<pc-copy-button from="my-input.value" style="vertical-align: 10px"></pc-copy-button>

<br />

<!-- Copies the link’s “href” attribute -->
<a href="https://example.com" id="my-link">Example website</a>
<pc-copy-button from="my-link[href]"></pc-copy-button>

Code

Handling errors

A copy error will occur if the value is an empty string, if the from attribute points to a non‐existent id or if the browser rejects the operation for any reason. When this happens, the pc-error event will be emitted.

This example demonstrates what happens when a copy error occurs. You can customise the error label and icon using the error-label attribute and the error-icon slot, respectively.

<pc-copy-button from="i-do-not-exist"></pc-copy-button>

Code

Disabled

Copy buttons can be disabled by adding the disabled attributes.

<pc-copy-button value="You can’t copy me!" disabled></pc-copy-button>

Code

Changing feedback duration

A success indicator is briefly shown after copying. You can customise the length of time the indicator is shown using the feedback-duration attribute.

<pc-copy-button
  value="Placer Toolkit rocks!"
  feedback-duration="250"
></pc-copy-button>

Code

Custom styles

You can customise the button to your liking with CSS.

<pc-copy-button value="I’m so stylish!" class="custom-pink-copy-button">
  <pc-icon
      library="default"
      icon-style="solid"
      name="asterisk"
      slot="copy-icon"
  ></pc-icon>
  <pc-icon
      library="default"
      icon-style="solid"
      name="check"
      slot="success-icon"
  ></pc-icon>
  <pc-icon
      library="default"
      icon-style="solid"
      name="xmark"
      slot="error-icon"
  ></pc-icon>
</pc-copy-button>

<style>
  pc-copy-button.custom-pink-copy-button::part(button) {
      background-color: #ff1493;
      border: 2px solid;
      border-top-color: #ff7ac1;
      border-left-color: #ff7ac1;
      border-bottom-color: #ad005c;
      border-right-color: #ad005c;
      border-radius: 6px;
      color: #fff;
      box-shadow: 0 2px 10px #0002;
      transition: all var(--pc-transition-fast) ease-in-out;
  }

  pc-copy-button.custom-pink-copy-button::part(button):hover {
      transform: scale(1.05) rotate(-1deg);
  }

  pc-copy-button.custom-pink-copy-button::part(button):active {
      border-top-color: #ad005c;
      border-right-color: #ff7ac1;
      border-bottom-color: #ff7ac1;
      border-left-color: #ad005c;
      transform: translateY(1px) rotate(-1deg);
  }

  pc-copy-button.custom-pink-copy-button::part(button):focus-visible {
      outline: 2px dashed deeppink;
      outline-offset: 2px;
  }
</style>

Code

Properties

Name	Description	Default
`value`	The text value to copy. `string`	`""`
`from`	An id that references an element in the same document from which data will be copied. If both this and `value` are present, this value will take precedence. By default, the target element’s `textContent` will be copied. To copy an attribute, append the attribute name wrapped in square brackets (e.g., `from="element[value]"`). To copy a property, append a dot and the property name (e.g., `from="element.value"`). `string`	`""`
`disabled`	Disables the copy button. `boolean`	`false`
`copyLabel` `copy-label`	A custom label to show in the tooltip. `string`	`""`
`successLabel` `success-label`	A custom label to show in the tooltip after copying. `string`	`""`
`errorLabel` `error-label`	A custom label to show in the tooltip when a copy error occurs. `string`	`""`
`feedbackDuration` `feedback-duration`	The length of time to show feedback before restoring the default trigger. `number`	`1000`
`tooltipPlacement` `tooltip-placement`	The preferred placement of the tooltip. `"top" \| "right" \| "bottom" \| "left"`	`"top"`
`hoist`	Enable this option to prevent the tooltip from being clipped when the component is placed inside a container with `overflow: auto\|hidden\|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all situations. `boolean`	`false`
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	-

Learn more about attributes and properties.

Slots

Name	Description
`copy-icon`	The icon to show in the default copy state. Works best with `<pc-icon>`.
`success-icon`	The icon to show when the content is copied. Works best with `<pc-icon>`.
`error-icon`	The icon to show when a copy error occurs. Works best with `<pc-icon>`.

Learn more about using slots.

Events

Name	Description	Event detail
`pc-copy`	Emitted when the data has been copied.	-
`pc-error`	Emitted when the data could not be copied.	-

Learn more about events.

Custom properties

Name	Description	Default
`--success-color`	The colour to use for success feedback.	-
`--error-color`	The colour to use for error feedback.	-

Learn more about customising custom properties.

Parts

Name	Description
`button`	The internal `<button>` element.
`copy-icon`	The container that holds the copy icon.
`success-icon`	The container that holds the success icon.
`error-icon`	The container that holds the error icon.
`tooltip__base`	The tooltip’s `base` part.
`tooltip__base__popup`	The tooltip’s `popup` part.
`tooltip__base__arrow`	The tooltip’s `arrow` part.
`tooltip__body`	The tooltip’s `body` part.

Learn more about customising CSS parts.

Animations

Name	Description
`copy.in`	The animation to use when the icons animate in.
`copy.out`	The animation to use when the icons animate out.

Learn more about customising animations.

Importing

If you’re using the autoloader or the standard loader, you can ignore this section. If you’re cherry picking, you can use any of the following snippets to import this component.

Script

Import

Bundler

To import this component from the CDN with a script tag, copy this snippet and paste it in your HTML.

<script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@0.5.1/dist/components/copy-button/copy-button.js"></script>

To import this component from the CDN using a JavaScript import, copy this snippet and paste it in your JavaScript:

import "https://cdn.jsdelivr.net/npm/placer-toolkit@0.5.1/dist/components/copy-button/copy-button.js";

To import this component with a bundler using a JavaScript import, copy this snippet and paste it in your JavaScript:

import "placer-toolkit/dist/components/copy-button/copy-button.js";

Dependencies

This component automatically imports these components: