Copy Button

<pc-copy-button>

0.5.1

experimental

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

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

Code

Edit

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, didn’t work for some reason."
></pc-copy-button>

Code

Edit

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

Edit

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 class="pc-align-items-center pc-gap-s">
    <span id="my-phone">+1 555 555 0123</span>
    <pc-copy-button from="my-phone"></pc-copy-button>
</span>

<br />

<!-- Copies the input’s value property -->
<span class="pc-align-items-center pc-gap-s">
    <pc-input
        type="text"
        id="my-input"
        value="User input"
        style="display: inline-block; max-inline-size: 300px"
    ></pc-input>
    <pc-copy-button from="my-input.value"></pc-copy-button>
</span>

<br />

<!-- Copies the link’s href attribute -->
<span class="pc-align-items-center pc-gap-s">
    <a href="https://example.com" id="my-link">Example website</a>
    <pc-copy-button from="my-link[href]"></pc-copy-button>
</span>

Code

Edit

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

Edit

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

Edit

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

Edit

Custom styles

You can customise the button to your liking with CSS.

<pc-copy-button value="I’m awesome!" class="awesome-copy-button">
    <pc-icon
        library="default"
        icon-style="solid"
        name="clipboard"
        slot="copy-icon"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="thumbs-up"
        slot="success-icon"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="thumbs-down"
        slot="error-icon"
    ></pc-icon>
</pc-copy-button>

<style>
    pc-copy-button.awesome-copy-button::part(button) {
        background-color: var(--pc-color-warning-fill-normal);
        color: var(--pc-color-warning-on-normal);
        border: var(--pc-border-width-m) var(--pc-border-style)
            var(--pc-color-warning-border-normal);
        border-radius: 0.5rem;
        box-shadow: 0 0.25rem 0 var(--pc-color-warning-border-normal);
        transition: none;
    }

    @media (hover: hover) {
        pc-copy-button.awesome-copy-button::part(button):hover {
            background-color: color-mix(
                in oklab,
                var(--pc-color-warning-fill-normal),
                var(--pc-color-mix-hover)
            );
            color: color-mix(
                in oklab,
                var(--pc-color-warning-on-normal),
                var(--pc-color-mix-hover)
            );
            border-color: color-mix(
                in oklab,
                var(--pc-color-warning-border-normal),
                var(--pc-color-mix-hover)
            );
            box-shadow: 0 0.25rem 0 color-mix(
                in oklab,
                var(--pc-color-warning-border-normal),
                var(--pc-color-mix-hover)
            );
        }
    }

    pc-copy-button.awesome-copy-button::part(button):active {
        background-color: color-mix(
            in oklab,
            var(--pc-color-warning-border-normal),
            var(--pc-color-mix-hover)
        );
        color: color-mix(
            in oklab,
            var(--pc-color-warning-on-normal),
            var(--pc-color-mix-hover)
        );
        border-color: color-mix(
            in oklab,
            var(--pc-color-warning-border-normal),
            var(--pc-color-mix-hover)
        );
        box-shadow: none;
        translate: 0 0.25rem;
    }
</style>

Code

Edit

Properties

Name	Description	Default
`value`	The text value to copy. Type: `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"`). Type: `string`	`""`
`disabled`	Disables the copy button. Type: `boolean`	`false`
`copyLabel` `copy-label`	A custom label to show in the tooltip. Type: `string`	`""`
`successLabel` `success-label`	A custom label to show in the tooltip after copying. Type: `string`	`""`
`errorLabel` `error-label`	A custom label to show in the tooltip when a copy error occurs. Type: `string`	`""`
`feedbackDuration` `feedback-duration`	The length of time to show feedback before restoring the default trigger. Type: `number`	`1000`
`tooltipPlacement` `tooltip-placement`	The preferred placement of the tooltip. Type: `"top" \| "right" \| "bottom" \| "left"`	`"top"`
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	‐

Learn more about customising animations.

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.	`var(--pc-color-success-on-quiet)`
`--error-color`	The colour to use for error feedback.	`var(--pc-color-danger-on-quiet)`

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 skip this section. But if you’re cherry picking, you can use any of the following snippets to import this component.

CDN (script tag)

CDN (import)

npm (import)

To manually import this component from the CDN, copy this code snippet and paste it in your HTML.

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

To manually import this component from the CDN, copy this code snippet and paste it in your JavaScript file.

  import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/copy-button/copy-button.js"; 

To manually import this component from npm, copy this code snippet and paste it in your JavaScript file.

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

Dependencies

This component automatically imports these components: