Clipboard

A button that copies a value to the clipboard, with an optional input that shows it.

Copy to clipboard

<ui:clipboard.root value="composer require jramke/fluid-primitives">
    <ui:clipboard.label>Copy to clipboard</ui:clipboard.label>
    <ui:clipboard.control class="flex items-center gap-2">
        <ui:clipboard.input class="field-sizing-content" />
        <ui:clipboard.trigger asChild="{true}">
            <ui:button>
                <ui:clipboard.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ClipboardIndicatorState::Idle')}">Copy</ui:clipboard.indicator>
                <ui:clipboard.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ClipboardIndicatorState::Copied')}">Copied!</ui:clipboard.indicator>
            </ui:button>
        </ui:clipboard.trigger>
    </ui:clipboard.control>
</ui:clipboard.root>

Features

Copies text to the clipboard
Switches to a copied state as visual feedback
Custom duration of the copied state with timeout (3000 ms by default)

Anatomy

<primitives:clipboard.root>
    <primitives:clipboard.label />
    <primitives:clipboard.control>
        <primitives:clipboard.input />
        <primitives:clipboard.trigger>
            <primitives:clipboard.indicator />
        </primitives:clipboard.trigger>
    </primitives:clipboard.control>
</primitives:clipboard.root>

Installation

typo3 ui:add clipboard

Read more about installing Components and Primitives.

Examples

Copy button on its own

Leave out the input for a copy button on its own. The demo copies a share link.

<ui:clipboard.root value="https://example.com/share/abc123">
    <ui:clipboard.trigger>
        <ui:clipboard.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ClipboardIndicatorState::Idle')}">Copy Link</ui:clipboard.indicator>
        <ui:clipboard.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ClipboardIndicatorState::Copied')}">Link Copied!</ui:clipboard.indicator>
    </ui:clipboard.trigger>
</ui:clipboard.root>

Custom timeout

Set timeout in milliseconds to change how long the copied state stays. The button in the demo reads "Copied for 5 seconds!" for timeout="5000".

<ui:clipboard.root value="Copy me!" timeout="5000">
    <ui:clipboard.control class="flex items-center gap-2">
        <ui:clipboard.input class="w-32" />
        <ui:clipboard.trigger asChild="{true}">
            <ui:button>
                <ui:clipboard.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ClipboardIndicatorState::Idle')}">Copy</ui:clipboard.indicator>
                <ui:clipboard.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ClipboardIndicatorState::Copied')}">Copied for 5 seconds!</ui:clipboard.indicator>
            </ui:button>
        </ui:clipboard.trigger>
    </ui:clipboard.control>
</ui:clipboard.root>

Localization

The trigger labels for the idle and the copied state ship in the language file and follow the site language. Pass translations with one string per state to override them for one clipboard.

<f:variable
    name="clipboardTranslations"
    value="{
        triggerLabelIdle: '{f:translate(key: \'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:clipboard.copy\')}',
        triggerLabelCopied: '{f:translate(key: \'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:clipboard.copied\')}'
    }"
/>

<ui:clipboard.root value="SUMMER24" translations="{clipboardTranslations}"> ... </ui:clipboard.root>

A client script passes a triggerLabel function of the copied state instead of the two strings.

API Reference

The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.

clipboard.root

Provides the clipboard state and shared context for the composed parts. Renders a <div> element.

Name	Description	Required	Default
`value`	`string` The value to copy to the clipboard.	Yes	-
`timeout`	`integer` The timeout for the copied state in milliseconds.	No	3000
`translations`	`array` Localized clipboard trigger labels, `triggerLabelIdle` and `triggerLabelCopied`. A client script can pass a `triggerLabel` function of the copied state instead. Use `f:translate` for per-template localization overrides when needed.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`rootId`	`string` The root ID of the component, used for hydration and identification.	No	-
`ids`	`array` The IDs of of the component parts for composition.	No	[]
`autoMount`	`boolean` Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()`	No	true
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-clipboard-root`	<uid>
`data-copied`	Present when copied state is true

clipboard.label

Labels the clipboard input. Renders a <label> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-clipboard-label`	<uid>
`data-copied`	Present when copied state is true

clipboard.control

Groups the input and trigger into a single layout container. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-clipboard-control`	<uid>
`data-copied`	Present when copied state is true

clipboard.input

Displays the text value that can be copied. Renders an <input> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-clipboard-input`	<uid>
`data-copied`	Present when copied state is true
`data-readonly`	Present when read-only

clipboard.trigger

Copies the current value to the clipboard when activated. Renders a <button> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-clipboard-trigger`	<uid>
`data-copied`	Present when copied state is true

clipboard.indicator

Displays UI for a specific clipboard state like idle or copied. Renders a <span> element.

Name	Description	Required	Default
`state`	`Enum\ClipboardIndicatorState` The indicator state to render.	Yes	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Machine JavaScript API

Name	Type	Description
`copied`	`boolean`	Whether the value has been copied to the clipboard
`value`	`string`	The value to be copied to the clipboard
`setValue`	`(value: string) => void`	Set the value to be copied to the clipboard
`copy`	`VoidFunction`	Copy the value to the clipboard
`getIndicatorState`	`(props: IndicatorProps) => IndicatorState`	Returns the state of the indicator