Security, Privacy, AI and CSR information for all Piano products now lives in one place. Explore our Compliance Center.
Subscriptions
English French
English French

Components

LIGHTWEIGHT TEMPLATES

SolidJS Components

Show

Attribute Name

Type

Required/Optional

Default Value

Description

when

condition (boolean)

Required

-

Item display condition.

fallback

JSX.Element | string

Optional

-

Renders its content if the condition in when is not met.

keyed

boolean

optional


when true, a function child receives the when value instead of an accessor, and the content is re-created whenever that value changes

HTML
<Show
 when={Number(context.custom.count) > 3}
 fallback={<div>I will be rendered if context.custom.count is {"<="} 3</div>}
>
  <div>I will be rendered if context.custom.count is > 3</div>
</Show>
HTML
<Show
 when={Number(context.custom.count) > 3}
  fallback={"string also valid"}
>
  <div>I will be rendered if context.custom.count is > 3</div>
</Show>

For

Attribute Name

Type

Required/Optional

Default Value

Description

each

array

Required

-

The array you want to expand.

fallback

JSX.Element | string | number

Optional

-

Renders its content if the array is empty.

HTML
<ul>
  <For
    each={context.termList}
    fallback={<div class="term-list-placeholder">Loading</div>}
  >
    {(item, index) => (
        <li class="term-item" onClick={(e) => context.startCheckout({ term: item })}>
          {index() + ". " + JSON.stringify(item.name)}
        </li>
      )
    }
  </For>
</ul>

The function inside For has 2 arguments:

  • item - array item

  • index - getter for index, to get index call index()

Switch and Match

Switch:

Attribute Name

Type

Required/Optional

Default Value

Description

fallback

JSX.Element | string

Optional

-

renders its content if no Match condition is met

Match:

Attribute Name

Type

Required/Optional

Default Value

Description

when

condition (boolean)

Required

-

Item display condition.

keyed

boolean

optional


when true, a function child receives the when value instead of an accessor, and the content is re-created whenever that value changes

XML
<Switch fallback={"Noname"}>
  <Match when={context.custom.name === "John"}>
    John
  </Match>
  <Match when={context.custom.name === "Alex"}>
    Alex
  </Match>
</Switch>

Index

Attribute name

type

required / optional

default value

description

each

array

required


the array you want to expand

fallback

JSX.Element | string | number

optional


renders its content if the array is empty

Like For, but the function inside Index gets item as a getter (to get the item call item()) and index as a plain number.

XML
<ul>
  <Index each={context.termList} fallback={<div>Loading</div>}>
    {(item, index) => <li>{index + ". " + item().name}</li>}
  </Index>
</ul>

Dynamic

Attribute name

type

required / optional

default value

description

component

string | Component

required


the HTML tag name or the component to render

All other attributes are passed to the rendered tag or component.

XML
<Dynamic component={context.isUserValid() ? "strong" : "span"}>
  <T>Welcome</T>
</Dynamic>

Buttons

PianoPrimaryButton

image-20260303-094416.png

Attribute Name

Type

Required/Optional

Default Value

Description

class

string

Optional

-

Optional CSS class name for the button element.

id

string

Optional

-

Optional ID for the button element.

classList

Record

Optional

-

Optional object for conditional CSS classes (e.g., { 'btn-active': true }).

style

Record

Optional

-

Optional inline styles as a key-value object.

children

JSX.Element

Required

-

The content to be rendered inside the button.

onClick

(e: Event) => void | Promise

Required

-

Click event handler. Can be synchronous or asynchronous.

name

string

Optional

-

Optional name attribute for the button (useful for forms).

disabled

boolean

Optional

-

Whether the button is disabled.

width

string

Optional

-

Optional CSS width value (e.g., '100px', '50%').

height

string

Optional

-

Optional CSS height value.

minHeight

string

Optional

-

Optional CSS min-height value.

minWidth

string

Optional

-

Optional CSS min-width value.

maxHeight

string

Optional

-

Optional CSS max-height value.

maxWidth

string

Optional

-

Optional CSS max-width value.

iconBefore

JSX.Element

Optional

-

Optional icon element to display before the children.

iconAfter

JSX.Element

Optional

-

Optional icon element to display after the children.

externalEventName

string

Optional

-

Optional name for an external event (e.g., for analytics tracking).

externalEventParams

Record

Optional

-

Optional parameters to accompany the external event.

ref

HTMLButtonElement | Setter<HTMLButtonElement>

Optional

-

Optional parameter provides button element.

ariaLabel

string

optional

-

Accessible label for screen readers.

XML
<PianoPrimaryButton
  width="200px"
  onClick={(e) => context.ding(item)}
  externalEventName="my-external-event-name"
  externalEventParams={{ param1: 'value', param2: 123 }}
>
  My button
</PianoPrimaryButton>

With dynamic externalEventName, externalEventParams:

XML
<PianoPrimaryButton
  width="200px"
  onClick={(e) => context.ding(item)}
  externalEventName={context.myExternalEventName}
  externalEventParams={context.myExternalEventParams}
>
  My button
</PianoPrimaryButton>

PianoSecondaryButton

image-20260303-094347.png

Supports the same properties as the PianoPrimaryButton.

XML
<PianoSecondaryButton
  width="200px"
  onClick={(e) => context.ding(item)}
  externalEventName={context.myExternalEventName}
  externalEventParams={context.myExternalEventParams}
>
  My secondary button
</PianoSecondaryButton>

PianoOutlineButton

Supports the same properties as the PianoPrimaryButton, including the optional iconBefore / iconAfter icons.

XML
<PianoOutlineButton
  width="200px"
  onClick={(e) => context.ding(item)}
  externalEventName="offer-outline"
>
  <T>Learn more</T>
</PianoOutlineButton>

PianoGhostButton

image-20260303-094506.png

Attribute Name

Type

Required/Optional

Default Value

Description

class

string

Optional

-

Optional CSS class name for the button element.

id

string

Optional

-

Optional ID for the button element.

classList

Record

Optional

-

Optional object for conditional CSS classes (e.g., { 'btn-active': true }).

style

Record

Optional

-

Optional inline styles as a key-value object.

children

JSX.Element

Required

-

The content to be rendered inside the button.

onClick

(e: Event) => void | Promise

Required

-

Click event handler. Can be synchronous or asynchronous.

name

string

Optional

-

Optional name attribute for the button (useful for forms).

disabled

boolean

Optional

-

Whether the button is disabled.

width

string

Optional

-

Optional CSS width value (e.g., '100px', '50%').

height

string

Optional

-

Optional CSS height value.

minHeight

string

Optional

-

Optional CSS min-height value.

minWidth

string

Optional

-

Optional CSS min-width value.

maxHeight

string

Optional

-

Optional CSS max-height value.

maxWidth

string

Optional

-

Optional CSS max-width value.

color

string

optional

-

Optional text color.

underlined

boolean

optional

-

Underlines the button text.

externalEventName

string

Optional

-

Optional name for an external event (e.g., for analytics tracking).

externalEventParams

Record

Optional

-

Optional parameters to accompany the external event.

ref

HTMLButtonElement | Setter<HTMLButtonElement>

Optional

-

Optional parameter provides button element.

ariaLabel

string

optional

-

Accessible label for screen readers.

XML
<PianoGhostButton
  width="200px"
  onClick={(e) => context.ding(item)}
  externalEventName="my-external-event-name"
  externalEventParams={{ param1: 'value', param2: 123 }}
>
  My ghost button
</PianoGhostButton>

PianoIconButton

image-20260303-094930.png

Attribute name

Type

Required/Optional

Default value

Description

class

string

optional

-

Optional CSS class name for the button element.

id

string

optional

-

Optional ID for the button element.

classList

Record<string, boolean>

optional

-

Optional object for conditional CSS classes (e.g., { 'btn-active': true }).

style

Record<string, string | undefined>

optional

-

Optional inline styles as a key-value object.

children

JSX.Element

required

-

The content to be rendered inside the button.

onClick

(e: Event) => void

required

-

Click event handler.

name

string

optional

-

Optional name attribute for the button (useful for forms).

disabled

boolean

optional

-

Whether the button is disabled.

width

string

optional

-

Optional CSS width value (e.g., '100px', '50%').

height

string

optional

-

Optional CSS height value.

minHeight

string

optional

-

Optional CSS min-height value.

minWidth

string

optional

-

Optional CSS min-width value.

maxHeight

string

optional

-

Optional CSS max-height value.

maxWidth

string

optional

-

Optional CSS max-width value.

externalEventName

string

optional

-

Optional name for an external event (e.g., for analytics tracking).

externalEventParams

Record<string, unknown>

optional

-

Optional parameters to accompany the external event.

ref

HTMLButtonElement | Setter<HTMLButtonElement>

optional

-

Optional ref to the button element.

ariaLabel

string

optional

-

Accessible label for screen readers.

ariaHaspopup

boolean

optional

-

Tells screen readers the button opens a popup.

ariaExpanded

boolean

optional

-

Tells screen readers whether the popup is open.

onaccent

boolean

optional

-

Uses the icon color meant for accent-colored backgrounds.

opacity

string

optional

-

Optional opacity value.

color

string

optional

-

Optional text color.

XML
<PianoIconButton onClick={(e) => handleClick(e)}>
   <svg>...</svg>
</PianoIconButton>

PianoCloseButton

Closes the widget on click and fires the onClose handler.

Supports the properties listed below. Use onClose rather than onClick: an onClick replaces the built-in close handler, so the element no longer closes..

Attribute name

Type

Required/Optional

Default value

Description

type

rounded | square

optional

square

Visual shape: "square" (default) or "rounded"

children

JSX.Element

optional

Built-in close icon

Optional custom icon (defaults to the built-in close icon).

onClose

(e: Event) => void

optional

-

Called when the button is clicked, right before the element closes.

name

string

optional

-

Optional name attribute for the button.

disabled

boolean

optional

-

Whether the button is disabled.

width

string

optional

63px (24px for the rounded type)

Optional CSS width value.

height

string

optional

63px (24px for the rounded type)

Optional CSS height value.

minHeight

string

optional

-

Optional CSS min-height value.

minWidth

string

optional

-

Optional CSS min-width value.

maxHeight

string

optional

-

Optional CSS max-height value.

maxWidth

string

optional

-

Optional CSS max-width value.

opacity

string

optional

-

Optional CSS opacity value.

externalEventName

string

optional

-

Optional external event name (analytics).

externalEventParams

Record<string, unknown>

optional

-

Optional external event params.

ref

HTMLButtonElement | Setter<HTMLButtonElement>

optional

-

Optional ref to the button element.

ariaLabel

string

optional

Close modal

Accessible label for screen readers.

class

string

optional

-

Optional CSS class name for the button element.

id

string

optional

-

Optional ID for the button element.

classList

Record<string, boolean>

optional

-

Optional object for conditional CSS classes.

style

Record<string, string | undefined>

optional

-

Optional inline styles as a key-value object.

XML
<PianoCloseButton name="my button" onClose={(e) => console.log("closed")} />

You can pass your icon to change the default close icon:

XML
<PianoCloseButton onClose={(e) => handleClose(e)}>
   <svg>...</svg>
</PianoCloseButton>

See this article for an explanation of how the "Allow user to close modal" checkbox works for Lightweight templates.

PianoStartCheckoutButton

image-20260304-113604.png

A wrapper component that starts checkout for its term when clicked: the classic checkout flow, or the new checkout when the term's behavior.checkoutVersion is "2". Renders one of the supported button components based on the as prop. Supports all props of the rendered button.

Attribute Name

Type

Required/Optional

Default Value

Description

as

PianoPrimaryButton | PianoSecondaryButton | PianoGhostButton | PianoIconButton

Optional

PianoPrimaryButton

Button variant to render.

term

ITerm

Required

-

Term for checkout.

children

JSX.Element

Required

-

The content to be rendered inside the button.

onClick

(e: Event) => void | Promise

Optional

-

Optional callback fired after checkout is triggered.

asGift

boolean

optional

false

Starts the checkout as a gift when the term allows purchase as a gift; only the classic checkout flow reads it.

ref

HTMLButtonElement | Setter<HTMLButtonElement>

Optional

-

Optional parameter provides button element.

class

string

Optional

-

Optional CSS class name for the button element.

id

string

Optional

-

Optional ID for the button element.

classList

Record

Optional

-

Optional object for conditional CSS classes (e.g., { 'btn-active': true }).

style

Record

Optional

-

Optional inline styles as a key-value object.

name

string

Optional

-

Optional name attribute for the button (useful for forms).

disabled

boolean

Optional

-

Whether the button is disabled.

width

string

Optional

-

Optional CSS width value (e.g., '100px', '50%').

height

string

Optional

-

Optional CSS height value.

minHeight

string

Optional

-

Optional CSS min-height value.

minWidth

string

Optional

-

Optional CSS min-width value.

maxHeight

string

Optional

-

Optional CSS max-height value.

maxWidth

string

Optional

-

Optional CSS max-width value.

externalEventName

string

Optional

-

Optional name for an external event (e.g., for analytics tracking).

externalEventParams

Record

Optional

{}

Optional parameters to accompany the external event.

ariaLabel

string

Optional

-

Accessible label for screen readers.

XML
<PianoStartCheckoutButton
  term={term}
  class="pn-offer__subscribe-button"
  externalEventName="offer-subscribe"
>
  <T>Subscribe</T>
</PianoStartCheckoutButton>

With a different button variant:

XML
<PianoStartCheckoutButton
  as="PianoSecondaryButton"
  term={item}
  externalEventName="offer-subscribe"
>
  <T>Subscribe</T>
</PianoStartCheckoutButton>

PianoBuyAsAGiftButton

A wrapper component that starts a gift checkout for its term when clicked: the classic checkout flow, or the new checkout when the term's behavior.checkoutVersion is "2". Renders one of the supported button components based on the as prop. Supports all props of the rendered button.

Attribute name

Type

Required/Optional

Default value

Description

as

PianoPrimaryButton | PianoSecondaryButton | PianoGhostButton | PianoIconButton

optional

PianoGhostButton

Button variant to render.

term

ITerm

required

—

Term object to start a gift checkout with. The button is rendered only when term.allowPurchaseAsGift is true.

children

JSX.Element

required

—

The content to be rendered inside the button.

onClick

(e: Event) => void | Promise

optional

—

Optional callback fired after checkout is triggered.

ref

HTMLButtonElement | Setter<HTMLButtonElement>

optional

—

Optional parameter provides button element.

class

string

optional

""

Optional CSS class name for the button element.

id

string

optional

—

Optional ID for the button element.

classList

Record

optional

—

Optional object for conditional CSS classes (e.g., { 'btn-active': true }).

style

Record

optional

—

Optional inline styles as a key-value object.

name

string

optional

—

Optional name attribute for the button (useful for forms).

disabled

boolean

optional

—

Whether the button is disabled.

width

string

optional

—

Optional CSS width value (e.g., '100px', '50%').

height

string

optional

—

Optional CSS height value.

minHeight

string

optional

—

Optional CSS min-height value.

minWidth

string

optional

—

Optional CSS min-width value.

maxHeight

string

optional

—

Optional CSS max-height value.

maxWidth

string

optional

—

Optional CSS max-width value.

externalEventName

string

optional

—

Optional name for an external event (e.g., for analytics tracking).

externalEventParams

Record

optional

{}

Optional parameters to accompany the external event.

ariaLabel

string

optional

—

Accessible label for screen readers.

Example
XML
<PianoBuyAsAGiftButton
  term={term}
  externalEventName="offer-gift"
>
  <T>Buy as a gift</T>
</PianoBuyAsAGiftButton>

PianoBackButton

An icon button with a back arrow. Available in Adblocker templates only.

The button renders its own arrow icon, so it takes no children. It is 63px wide and 63px high unless width and height set another size.

Attribute name

Type

Required/Optional

Default value

Description

class

string

optional

-

Optional CSS class name for the button element.

id

string

optional

-

Optional ID for the button element.

classList

Record<string, boolean>

optional

-

Optional object for conditional CSS classes (e.g., { 'btn-active': true }).

style

Record<string, string | undefined>

optional

-

Optional inline styles as a key-value object.

onClick

(e: Event) => void | Promise<void>

required

-

Called when the button is clicked. Can be synchronous or asynchronous.

name

string

optional

-

Optional name attribute for the button (useful for forms).

disabled

boolean

optional

-

Whether the button is disabled.

width

string

optional

63px

Optional CSS width value (e.g., '100px', '50%').

height

string

optional

63px

Optional CSS height value.

minHeight

string

optional

-

Optional CSS min-height value.

minWidth

string

optional

-

Optional CSS min-width value.

maxHeight

string

optional

-

Optional CSS max-height value.

maxWidth

string

optional

-

Optional CSS max-width value.

externalEventName

string

optional

-

Optional name for an external event (e.g., for analytics tracking).

externalEventParams

Record<string, unknown>

optional

-

Optional parameters to accompany the external event.

ref

HTMLButtonElement | Setter<HTMLButtonElement>

optional

-

Optional ref to the button element.

ariaLabel

string

optional

-

Optional accessible label for screen readers.

ariaHaspopup

boolean

optional

-

Tells screen readers the button opens a popup.

ariaExpanded

boolean

optional

-

Tells screen readers whether the popup is open.

onaccent

boolean

optional

-

Uses the icon color meant for accent-colored backgrounds.

opacity

string

optional

-

Optional opacity value.

color

string

optional

-

Optional text color.

e2e

string

optional

-

Sets data-e2e on the button element, for automated tests.

XML
<PianoBackButton onClick={(e) => context.toScreen('home')} ariaLabel={context.t('back')} />

Forms

PianoInput

Default view:

image-20260317-091147.png

Inline view:

image-20260317-091319.png

Attribute Name

Type

Required/Optional

Default Value

Description

name

string

Required

—

The name attribute of the input.

onChange

(event: InputEvent | Event) => unknown

Optional

undefined

Callback function triggered when the input value changes.

type

string

Required

—

The type of the input (e.g., 'text', 'password', 'email').

placeholder

string

Optional

undefined

Placeholder text displayed when the input is empty.

invalid

boolean

Optional

false

Indicates whether the input is in an invalid state.

required

boolean

Optional

false

Marks the input as required for form validation.

disabled

boolean

Optional

false

Disables the input, making it non‑interactive.

readonly

boolean

Optional

false

Makes the input read‑only, preventing changes.

value

string

Optional

""

The current value of the input.

autofocus

boolean

Optional

false

Automatically focuses the input when the page loads.

minLength

number

Optional

undefined

Minimum number of characters allowed.

maxLength

number

Optional

undefined

Maximum number of characters allowed.

max

number

Optional

undefined

Maximum value (for number inputs).

min

number

Optional

undefined

Minimum value (for number inputs).

autocomplete

string

Optional

undefined

Autocomplete hint for the browser (e.g., 'on', 'off', 'name').

height

string

Optional

undefined

Custom CSS height value.

textAlign

CSS.Property.TextAlign

Optional

undefined

Text alignment inside the input (e.g., 'left', 'center', 'right').

onEnter

(event: KeyboardEvent) => unknown

Optional

undefined

Callback function triggered when the Enter key is pressed while the input is focused.

ref

HTMLInputElement

Optional

undefined

Reference to the underlying HTML input element.

width

string

Optional

undefined

Custom CSS width value.

padding

string

Optional

undefined

Custom CSS padding value.

inputMode

"none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search"

Optional

undefined

Hint to the browser about the type of virtual keyboard to display.

pattern

string

Optional

undefined

Regular expression pattern for input validation.

class

string

Optional

undefined

CSS class name(s) to apply to the root element.

classList

Record

Optional

undefined

Object mapping class names to boolean flags for conditional styling.

id

string

Optional

undefined

The unique identifier for the root element; the input element itself takes name as its id.

style

Record

Optional

undefined

Inline styles as a key‑value object.

label

string

Optional

undefined

Text label associated with the input.

iconLeft

JSX.Element

Optional

undefined

Icon element displayed on the left side of the input.

iconRight

JSX.Element

Optional

undefined

Icon element displayed on the right side of the input.

view

default | inline

Optional

default

View mode.

error

string

Optional

undefined

Error message to display when the input is invalid.

ariaLabel

string

Optional

undefined

Accessible label for screen readers.

autocorrect

"on" | "off"

Optional

undefined

Native autocorrect attribute.

autocapitalize

"on" | "off" | "none" | "sentences" | "words" | "characters"

Optional

undefined

Native autocapitalize attribute.

e2e

string

Optional

undefined

Sets data-e2e on the input, for automated tests.

PianoCheckbox

image-20260317-092946.png

Attribute Name

Type

Required/Optional

Default Value

Description

class

string

Optional

undefined

CSS class name(s) to apply to the component.

id

string

Optional

undefined

Unique identifier for the element.

classList

Record

Optional

undefined

Object mapping class names to boolean flags for conditional styling.

style

Record

Optional

undefined

Inline styles as a key‑value object.

name

string

Required

—

The name attribute of the input.

label

JSX.Element

Optional

undefined

Text label associated with the input.

invalid

boolean

Optional

false

Indicates whether the input is in an invalid state.

required

boolean

Optional

false

Marks the input as required for form validation.

disabled

boolean

Optional

false

Disables the input, making it non‑interactive.

readonly

boolean

Optional

false

Makes the input read‑only, preventing changes.

checked

boolean

Optional

false

Indicates whether a checkbox or radio input is checked.

onChange

(event: Event) => unknown

Optional

undefined

Callback function triggered when the input value changes.

error

JSX.Element

Optional

undefined

Error message to display when the input is invalid.

ariaLabel

string

Optional

undefined

ARIA label for accessibility.

ariaLabelledBy

string

Optional

undefined

ID of an element whose text labels the checkbox for screen readers.

describedById

string

Optional

{name}-error

ID of your own error element, if you render the error message outside this component. Used while invalid is true.

e2e

string

Optional

undefined

Sets data-e2e on the checkbox input, for automated tests.

PianoToggle

image-20260622-071049.png

 

Attribute name

Type

Required/Optional

Default value

Description

name

string

Required

-

Form field name; used as input id and label target.

leftLabel

JSX.Element

Optional

-

Label rendered before (left of) the toggle.

rightLabel

JSX.Element

Optional

-

Label rendered after (right of) the toggle.

checked

boolean

Optional

false

Initial checked state.

disabled

boolean

Optional

false

Disables interaction and applies disabled styling.

readonly

boolean

Optional

false

Locks the value without the disabled cursor.

required

boolean

Optional

false

Marks the field required for form validation.

invalid

boolean

Optional

false

Applies the invalid (danger) outline.

error

JSX.Element

Optional

-

Error message rendered below the toggle.

ariaLabel

string

Optional

-

ARIA label for screen readers when no visible label is set.

onChange

(event: Event) => unknown

Optional

-

Called when the toggle state changes.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<PianoToggle
  name="darkMode"
  leftLabel="Off"
  rightLabel="On"
  checked={true}
  onChange={(e) => console.log(e)}
/>

PianoTextarea

image-20260317-093050.png

Attribute Name

Type

Required/Optional

Default Value

Description

class

string

Optional

undefined

CSS class name(s) to apply to the root element.

id

string

Optional

undefined

Unique identifier for the root element; the textarea element itself takes name as its id.

classList

Record

Optional

undefined

Object mapping class names to boolean flags for conditional styling.

style

Record

Optional

undefined

Inline styles as a key‑value object.

label

string

Optional

undefined

Text label associated with the textarea.

view

string

Optional

default

Visual variant: "default" (boxed) or "inline" (underline).

error

string

Optional

undefined

Error message to display when the textarea is invalid.

describedById

string

Optional

{name}-error

ID of your own error element, if you render the error message outside this component. Used while invalid is true.

name

string

Required

—

The name attribute of the textarea.

invalid

boolean

Optional

false

Indicates whether the textarea is in an invalid state.

required

boolean

Optional

false

Marks the textarea as required for form validation.

disabled

boolean

Optional

false

Disables the textarea, making it non‑interactive.

readonly

boolean

Optional

false

Makes the textarea read‑only, preventing changes.

value

string

Optional

""

The current value of the textarea.

onChange

(event: InputEvent | Event) => unknown

Optional

undefined

Callback function triggered when the textarea value changes.

placeholder

string

Required

—

Placeholder text displayed when the textarea is empty.

autofocus

boolean

Optional

false

Automatically focuses the textarea when the page loads.

minLength

number

Optional

undefined

Minimum number of characters allowed.

maxLength

number

Optional

undefined

Maximum number of characters allowed.

rows

number

Optional

undefined

Number of visible text lines (height in rows).

cols

number

Optional

undefined

Average character width (width in columns).

maxWidth

string

Optional

undefined

Maximum width of the textarea (CSS max-width).

height

string

Optional

undefined

Custom CSS height value.

width

string

Optional

undefined

Custom CSS width value.

ref

HTMLTextAreaElement

Optional

undefined

Reference to the underlying HTML textarea element.

resize

Property.Resize

Optional

undefined

CSS resize property controlling whether the textarea can be resized (e.g., 'none', 'both', 'horizontal', 'vertical').

PianoRadioButton

image-20260317-093152.png

Attribute Name

Type

Required/Optional

Default Value

Description

class

string

Optional

undefined

CSS class name(s) to apply to the component.

id

string

Optional

undefined

Unique identifier for the input element.

classList

Record

Optional

undefined

Object mapping class names to boolean flags for conditional styling.

style

Record

Optional

undefined

Inline styles as a key‑value object.

name

string

Required

—

The name attribute of the radio input (used to group radio buttons).

value

string

Required

—

The value associated with this radio option (submitted when the radio is selected).

selected

string

Optional

undefined

The currently selected value in the radio group. Used to determine if this radio is checked by comparing with value.

label

string

Optional

undefined

Text label displayed next to the radio button.

invalid

boolean

Optional

false

Indicates whether the radio is in an invalid state.

required

boolean

Optional

false

Marks the radio group as required (at least one option must be selected).

disabled

boolean

Optional

false

Disables the radio button, making it non‑interactive.

readonly

boolean

Optional

false

Makes the radio read‑only (selection cannot be changed).

checked

boolean

Optional

false

Explicitly sets the checked state of the radio button.

onChange

(event: Event) => unknown

Optional

undefined

Callback function triggered when the radio selection changes.

PianoRadioGroup

image-20260317-093152.png

Attribute name

Type

Required/Optional

Default value

Description

name

string

Required

-

Form field name; shared by every radio input in the group.

options

{ value: string; label: string; disabled?: boolean }[]

Required

-

The selectable options ({ value, label, disabled? }).

selected

string

Optional

-

Value of the currently selected option.

label

string

Optional

-

Group label rendered above the options.

error

string

Optional

-

Error message rendered below the options.

disabled

boolean

Optional

false

Disables every option and applies disabled styling.

readonly

boolean

Optional

false

Locks the value without the disabled cursor.

required

boolean

Optional

false

Marks the group required for form validation.

invalid

boolean

Optional

false

Applies the invalid (danger) styling and aria-invalid.

describedById

string

Optional

{name}-error

ID of your own error element, if you render the error message outside this component. Used while invalid is true.

onChange

(event: InputEvent | Event) => unknown

Optional

-

Called when a different option is selected.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<PianoRadioGroup
  name="plan"
  label="Choose a plan"
  selected="monthly"
  options={[
    { value: "monthly", label: "Monthly" },
    { value: "yearly", label: "Yearly" },
  ]}
  error="Please choose a plan"
  onChange={(e) => console.log(e.target)}
/>


PianoCheckboxGroup

piano-checkbox-group-states.png

Ready-made checkbox group - the multi-select counterpart of PianoRadioGroup. Every option is visible at once and independently selectable, so each option is its own tab stop. Used by the MULTI_SELECT_LIST custom field when the field's view mode is list (the default dropdown view mode renders PianoMultiSelect; a SINGLE_SELECT_LIST field in list view mode renders PianoRadioGroup).

Attribute name

Type

Required/Optional

Default value

Description

Attribute name

Type

Required/Optional

Default value

Description

name

string

Required

-

Form field name; shared by every checkbox input in the group.

options

{ value: string; label: string; disabled?: boolean }[]

Required

-

The selectable options ({ value, label, disabled? }).

selected

string[]

Optional

[]

Values of the currently selected options.

label

string

Optional

-

Group label rendered above the options.

error

string

Optional

-

Error message rendered below the options.

disabled

boolean

Optional

false

Disables every option and applies disabled styling.

readonly

boolean

Optional

false

Locks the value without the disabled cursor.

required

boolean

Optional

false

Marks the group required for form validation.

invalid

boolean

Optional

false

Applies the invalid (danger) styling and aria-invalid.

describedById

string

Optional

{name}-error

Id of an externally rendered error element, used for aria-describedby when the group is invalid.

onChange

(event: InputEvent | Event) => unknown

Optional

-

Called when an option is toggled with the native checkbox change event: target.value is the option, target.checked its new state.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<PianoCheckboxGroup
  name="topics"
  label="Pick your topics"
  selected={["news"]}
  options={[
    { value: "news", label: "News" },
    { value: "sport", label: "Sport" },
  ]}
  error="Please pick at least one"
  onChange={(e) => console.log(e.target)}
/>

 

PianoSelect

image-20260317-095236.png

Default view:

image-20260317-095317.png

Inline view:

image-20260317-095342.png

Attribute Name

Type

Required/Optional

Default Value

Description

class

string

Optional

undefined

CSS class name(s) to apply to the select component.

id

string

Optional

undefined

Unique identifier for the select element.

classList

Record

Optional

undefined

Object mapping class names to boolean flags for conditional styling.

style

Record

Optional

undefined

Inline styles as a key‑value object.

name

string

Required

—

The name attribute of the select.

label

string

Optional

undefined

Text label associated with the select.

invalid

boolean

Optional

false

Indicates whether the select is in an invalid state.

required

boolean

Optional

false

Marks the select as required for form validation.

disabled

boolean

Optional

false

Disables the select, making it non‑interactive.

readonly

boolean

Optional

false

Makes the select read‑only (selection cannot be changed).

onChange

(event: InputEvent | Event) => unknown

Optional

undefined

Callback function triggered when the select value changes.

options

ISelectOption[]

Required

—

Array of options to display in the dropdown. Each option has id and text.

selected

string

Optional

undefined

The id of the currently selected option.

maxVisibleRows

number

Optional

4

Maximum number of visible rows in the dropdown before scrolling.

searchable

boolean

Optional

false

Renders a search filter at the top of the dropdown.

placeholder

string

Required

—

Placeholder text displayed when no option is selected.

maxWidth

string

Optional

undefined

Maximum width of the select component (CSS max-width).

view

default | inline

Optional

default

Visual variant of the select.

iconLeft

JSX.Element

Optional

undefined

Icon element displayed on the left side of the select.

error

string

Optional

undefined

Error message to display when the select is invalid.

describedById

string

Optional

{name}-error

ID of your own error element, if you render the error message outside this component. Used while invalid is true.

PianoMultiSelect

Multi-select dropdown (used by the MULTI_SELECT_LIST custom field in the default dropdown view mode; the list view mode renders PianoCheckboxGroup). Same dropdown as PianoSelect - the trigger shows a removable chip per selected option, the list renders a tick per selected option, and picking toggles the option in/out of the selection without closing the dropdown.

Attribute name

Type

Required/Optional

Default value

Description

name

string

Required

-

Form field name.

options

{ id: string; text: string }[]

Required

-

The selectable options.

selected

string[]

Optional

[]

Ids of the currently selected options.

label

string

Optional

-

Label text rendered above the control.

placeholder

string

Optional

""

Text shown when nothing is selected.

required

boolean

Optional

false

Marks the field required for form validation.

disabled

boolean

Optional

false

Disables the control and applies disabled styling.

invalid

boolean

Optional

false

Applies the invalid (danger) styling.

error

string

Optional

-

Error message rendered under the control; also switches the control to the invalid styling.

describedById

string

Optional

{name}-error

Id of an externally rendered error element for aria-describedby. Overrides the internal {name}-error.

searchable

boolean

Optional

false

Renders a search filter at the top of the dropdown.

view

string

Optional

default

Visual variant: "default" (boxed) or "inline" (underline).

onChange

(selected: string[]) => void

Optional

-

Called with the full new selection array on every toggle.

XML
<PianoMultiSelect
  name="topics"
  label="Topics"
  options={options}
  selected={topics()}
  searchable={true}
  onChange={(selected) => setTopics(selected)}
/>

PianoDatepicker

Date picker (used by the ISO_DATE custom field). Replaces the browser's native <input type="date"> with a styled calendar popover; the value is read and emitted in the given client date format.

Attribute name

Type

Required/Optional

Default value

Description

name

string

Required

-

Form field name.

clientFormat

string

Required

-

The client date format, e.g. "MM/dd/yyyy".

value

string

Optional

""

Current value in the client format.

label

string

Optional

-

Label text rendered above the control.

placeholder

string

Optional

""

Placeholder shown while the input is empty and unfocused.

required

boolean

Optional

false

Marks the field required for form validation.

disabled

boolean

Optional

false

Disables the control and applies disabled styling.

invalid

boolean

Optional

false

Applies the invalid (danger) styling.

error

string

Optional

-

Error message rendered under the control.

describedById

string

Optional

-

Id of an externally rendered error element for aria-describedby.

weekStartsOn

0 | 1

Optional

0

First day of week: 0 = Sunday, 1 = Monday.

view

string

Optional

-

Visual variant: "default" (boxed) or "inline" (underline).

labels

{ cancel?; done?; open?; formatHint? }

Optional

-

Overrides for the popover's translated strings.

onChange

(value: string) => void

Optional

-

Called with the new value in the client format.

XML
<PianoDatepicker
  name="birthday"
  label="Birthday"
  clientFormat="MM/dd/yyyy"
  value={birthday()}
  onChange={(value) => setBirthday(value)}
/>

PianoSlider

Scale/range control (used by the NUMBER-with-scale custom field). Renders a slider with a track split into one section per step (up to maxSectionsCount), a value popup and min/max labels; supports RTL mirroring and arrow-key stepping. Emits its value as a string.

Attribute name

Type

Required/Optional

Default value

Description

name

string

Required

-

Form field name.

value

string

Optional

-

Current value.

min

number

Optional

0

Lower bound of the scale.

max

number

Optional

10

Upper bound of the scale.

step

number

Optional

1

Step between values.

label

string

Optional

-

Label text rendered above the control.

minLabel

string

Optional

min

Text shown under the left end of the track.

maxLabel

string

Optional

max

Text shown under the right end of the track.

maxSectionsCount

number

Optional

10

Maximum number of step sections drawn on the track; with more steps the track has no sections.

required

boolean

Optional

false

Marks the field required for form validation.

disabled

boolean

Optional

false

Disables the control.

invalid

boolean

Optional

false

Marks the control invalid for assistive tech (aria only).

error

string

Optional

-

Error message rendered under the control.

describedById

string

Optional

-

Id of an externally rendered error element for aria-describedby.

ariaLabelledBy

string

Optional

-

Id of an external label element.

onChange

(value: string) => void

Optional

-

Called with the new value as a string.

XML
<PianoSlider
  name="satisfaction"
  label="How satisfied are you?"
  min={1}
  max={10}
  value={score()}
  onChange={(value) => setScore(value)}
/>

PianoCustomField

Renders one field of the Piano ID custom form, picked by its name, with the control that matches the field's data type (text, multi-line text, number, scale, boolean, date, single-select or multi-select list) and the field's error messages. A field placed this way is not rendered again by PianoCustomFields. Renders nothing when the form has no field with that name or the field is hidden. Available in Piano ID Custom Form templates only.

Attribute name

Type

Required/Optional

Default value

Description

fieldName

string

Required

-

Name of the custom field to render.

XML
<PianoCustomField fieldName="company" />
<PianoCustomFields />

PianoCustomFields

Renders, in the form's order, every field of the Piano ID custom form that is not placed with PianoCustomField; in a multi-step form, only the fields of the current step. Each field is rendered the way PianoCustomField renders it. It takes no properties. Available in Piano ID Custom Form templates only.

XML
<PianoCustomFields />

PianoIdEmbeddedCustomForm

Embeds the Piano ID custom form named by formName: its error messages, its fields (with a step indicator, the step title and a back button when the form has several steps), a submit button and a skip button. The form posts the answers itself. Available in Active Churn Prevention templates only.

Attribute name

Type

Required/Optional

Default value

Description

formName

string

Required

-

Name of the Piano ID custom form to embed.

submitLabel

string

Optional

-

Label of the submit button on the last step; without it the button reads "Send" in a single-step form and "Finish" in a multi-step form. On earlier steps the button reads "Next".

skipLabel

string

Optional

Skip

Label of the skip button.

skipVariant

"ghost" | "secondary"

Optional

ghost

Look and position of the skip button: "ghost" renders a ghost button below the buttons row, "secondary" a secondary button in the row next to the submit button.

classes

{ root?: string; actions?: string; submit?: string; skip?: string }

Optional

-

Extra CSS class names for the form root, the buttons row, the submit button and the skip button.

onSubmit

(submittedFields: ISubmittedField[]) => void

Optional

-

Called with the answered fields once the last step is submitted successfully.

onSkip

() => void

Optional

-

Called when the skip button is clicked.

XML
<PianoIdEmbeddedCustomForm
  formName={context.churnReasons().formName}
  submitLabel={context.t('Send')}
  skipLabel={context.t('Skip')}
  skipVariant="secondary"
  classes={{
    root: 'pn-churn-reasons-form',
    actions: 'pn-churn-reasons-actions',
    submit: 'pn-churn-reasons-accept-button',
    skip: 'pn-churn-reasons-decline-button',
  }}
  onSubmit={(submittedFields) => context.submitChurnReasonsForm(submittedFields)}
  onSkip={() => context.skipChurnReasonsForm()}
/>

Typography

Attribute Name

Type

Required/Optional

Default Value

Description

class

string

Optional

-

Optional CSS class name for the element.

id

string

Optional

-

Optional ID for the element.

classList

Record

Optional

-

Optional object for conditional CSS classes.

style

Record

Optional

-

Optional inline styles as a key-value object.

children

JSX.Element | string

Required

-

The content to be rendered inside the typography component.

PianoHeadline

image-20260303-105257.png
XML
<PianoHeadline>Lorem ipsum dolor sit amet</PianoHeadline>

PianoSubHeadline

image-20260303-105324.png
XML
<PianoSubHeadline>Lorem ipsum dolor sit amet</PianoSubHeadline>

PianoText

image-20260303-105406.png
XML
<PianoText>Lorem ipsum dolor sit amet</PianoText>

PianoText also accepts the optional textRole prop: the ARIA role of the paragraph, set as its role attribute.

PianoAccentedText

image-20260303-105440.png
XML
<PianoAccentedText>Lorem ipsum dolor sit amet</PianoAccentedText>

Complex

PianoHeader

Attribute name

type

required / optional

default

description

isUserControlHidden

boolean

optional

false

hide user control

isLocaleSelectorHidden

boolean

optional

false

hide locale selector

isCloseButtonHidden

boolean

optional

undefined

hide close button; when not set, follows the element's show close button setting

isUserLogoutHidden

boolean

optional

undefined

hide logout button

onClose

(e: Event) => void

optional

undefined

close handler forwarded to PianoCloseButton

renderLeftControls

JSX.Element

optional

undefined

custom controls shown on the left

class

string

optional

undefined

CSS class name for the header element

id

string

optional

undefined

ID for the header element

classList

Record<string, boolean>

optional

undefined

object for conditional CSS classes

style

Record<string, string | undefined>

optional

undefined

inline styles as a key-value object

PianoTabs

image-20260622-070913.png

 

Attribute name

Type

Required/Optional

Default value

Description

value

string

Optional

-

Controlled active tab value. When provided, the component is controlled.

defaultValue

string

Optional

first enabled tab

Initial active tab value in uncontrolled mode.

onChange

(value: string) => void

Optional

-

Called when the active tab changes via user interaction.

children

JSX.Element

Required

-

PianoTab elements.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

PianoTab

Attribute name

Type

Required/Optional

Default value

Description

value

string

Required

-

Identifier shared by the trigger and its panel.

label

JSX.Element

Required

-

Label rendered inside the tab trigger.

disabled

boolean

Optional

-

When true the tab cannot be activated.

children

JSX.Element

Required

-

Panel content (lazy: created only when the tab is active).

<PianoTabs defaultValue="account" onChange={(value) => console.log(value)}>
  <PianoTab value="account" label="Account">Account panel</PianoTab>
  <PianoTab value="password" label="Password">Password panel</PianoTab>
</PianoTabs>

PianoCountdown

image-20260622-070437.png

 

Attribute name

Type

Required/Optional

Default value

Description

endDate

Date

Required

-

Target date the countdown ticks toward.

format

string

Required

-

Colon-separated units to display, e.g. "dd:hh:mm:ss".

onComplete

() => void

Optional

-

Called once when the countdown reaches zero.

children

JSX.Element

Optional

-

Pre-translated title rendered above the timer.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<PianoCountdown
  endDate={new Date("12.31.2026")}
  format="dd:hh:mm:ss"
  onComplete={() => console.log("done")}
>
  Limited offer ends in
</PianoCountdown>

PianoStepIndicator

Shows the steps of a multi-step Piano ID custom form with their icons and marks the current step; steps that do not fit the available width are collapsed. Renders nothing when the form is not multi-step. It takes no properties. Available in Piano ID Custom Form templates only.

XML
<Show when={context.stepCount() > 1}>
  <PianoStepIndicator />
</Show>

Utility

PianoImg

image-20260303-105711.png

Renders an image and displays a placeholder icon when src is empty or not set.

Attribute Name

Type

Required/Optional

Default Value

Description

class

string

Optional

-

Optional CSS class name for the image element.

id

string

Optional

-

Optional ID for the image element.

classList

Record

Optional

-

Optional object for conditional CSS classes.

style

Record

Optional

-

Optional inline styles as a key-value object.

src

string

Optional

""

Source URL of the image.

width

string | number

Optional

64

Width of the image (can be a string with units or a number).

height

string | number

Optional

64

Height of the image (can be a string with units or a number).

alt

string

Optional

-

Alternative text for the image (accessibility).

XML
<PianoImg src="image-src" width="64" height="64" alt="alt-text"></PianoImg>

PianoUserName

Renders Piano user name, full name or email.

Attribute Name

Type

Required/Optional

Default Value

Description

class

string

Optional

-

Optional CSS class name for the element.

id

string

Optional

-

Optional ID for the element.

classList

Record

Optional

-

Optional object for conditional CSS classes.

style

Record

Optional

-

Optional inline styles as a key-value object.

children

JSX.Element | string

Optional

-

Optional content to be rendered inside the component.

display

"name" | "fullName" | "email"

Required

-

How the username will be presented.

fallback

JSX.Element

Optional

-

Shown when no user is logged in and no children are given

XML
<PianoUserName
 display="fullName"
  fallback="Lorem ipsum"
  class="username"
>
  My external name(optional)
</PianoUserName>

PianoExternalEvent

Fire external event and sends auto micro conversion when the wrapped content is clicked.

Attribute Name

Type

Required/Optional

Default Value

Description

name

string

Required

-

External event name.

params

object

Optional

""

External event options.

class

string

optional


CSS class name for the wrapper element

id

string

optional


ID for the wrapper element

classList

Record<string, boolean>

optional


object for conditional CSS classes

style

Record<string, string | undefined>

optional


inline styles as a key-value object

children

JSX.Element

required


content that sends the event when clicked

HTML
<PianoExternalEvent name="some-event" params={{ myParam:'my-param-value' }}>
  <button>Test event</button>
</PianoExternalEvent>

To know more how to set up click tracking and reporting of multiple clickable elements e.g. buttons follow this FAQ.

A

Adds _ptid to the href and sends an auto micro conversion when the link is clicked.

Important: Do not change to . Our conversion-tracking implementation relies on the uppercase tag and will not track conversions otherwise.
Lowercase a is the standard HTML element without tracking, while uppercase A is our component with tracking.

Attribute Name

Type

Required/Optional

Default Value

Description

class

string

Optional

-

CSS class name for the element.

id

string

Optional

-

Unique identifier for the element.

classList

Record

Optional

-

Optional object for conditional CSS classes.

style

Record

Optional

-

Optional inline styles as a key-value object.

children

JSX.Element

Required

-

Child elements to render inside the component.

noptid

boolean

Optional

-

If true, _ptid is not added to href. The click is still sent as an auto micro conversion.

href

string

Optional

""

The URL to navigate to when the link is clicked.

target

string

Optional

_blank for links whose href starts with http

Specifies where to open the linked document (e.g., "_blank", "_self"). A link whose href starts with http opens in _blank unless target is _self, _parent or _top.

Other tag attributes

-

Optional

-

Standard HTML anchor attributes: hreflang, media, ping, referrerpolicy, rel, type.

HTML
<A href="my-external-link">
  link text
</A>

PianoLocaleSelector

image-20260303-110611.png

Renders the locale selector.

Attribute Name

Type

Required/Optional

Default Value

Description

class

string

Optional

-

CSS class name for the element.

id

string

Optional

-

Unique identifier for the element.

classList

Record

Optional

-

Optional object for conditional CSS classes.

style

Record

Optional

-

Optional inline styles as a key-value object.

XML
<PianoLocaleSelector></PianoLocaleSelector>

PianoUserControl

image-20260303-111011.png

Renders a user control menu.

Attribute Name

Type

Required/Optional

Default Value

Description

class

string

Optional

-

CSS class name for the element.

id

string

Optional

-

Unique identifier for the element.

classList

Record

Optional

-

Optional object for conditional CSS classes.

style

Record

Optional

-

Optional inline styles as a key-value object.

disabled

boolean

optional

-

Disables the control, so its dropdown cannot be opened.

XML
<PianoUserControl></PianoUserControl>

T (Translate)

Translates the passed string. See the Localization section for more details.

Attribute Name

Type

Required/Optional

Default Value

Description

context

string

Optional

Translation context of the element (e.g. offer.component)

The context from which translations will be taken.

template

Record<string, string | number | boolean>

Optional

-

Inserts variables into the translated string.

children

string

required

-

Text to translate. Must be plain text.

XML
<T>string to translate</T>
<T context="offer.component">string to translate</T>
<T
  template={{ templateVariable: item, otherTemplateVariable: userName }}
>
  string to translate [[templateVariable]] with template [[otherTemplateVariable]]
</T>

MediaQuery

Conditionally renders its children based on the viewport or widget container width.

Attribute name

Type

Required/Optional

Default value

Description

class

string

optional

 

CSS class name for the root element.

id

string

optional

 

ID for the root element.

classList

Record<string, boolean>

optional

 

Object for conditional CSS classes.

style

Record<string, string | undefined>

optional

 

Inline styles as a key-value object.

layout

"viewport" | "widget"

optional

"viewport"

Source of the measured width: viewport compares against window.innerWidth, widget against the #root container width.

bound

"min" | "max"

required

 

Comparison direction: min keeps children visible while width >= width; max while width <= width.

width

number

required

 

Width threshold in pixels.

children

JSX.Element

required

 

Content gated by the width condition.

<MediaQuery layout="viewport" bound="min" width={800}>
  Visible when viewport is at least 800px wide
</MediaQuery>

Term icons

Icons for the term type of an upgrade option. Available in Upgrade Offer templates only. The icons take no properties.

Component

Icon

PianoPaymentTermIcon

Payment term

PianoRegistrationTermIcon

Registration term

PianoGiftTermIcon

Gift term

PianoExternalTermIcon

External term

PianoDynamicTermIcon

Dynamic term

XML
<For each={context.upgradeVariants()}>
  {(upgradeVariant) => (
    <For each={upgradeVariant.upgradeTo}>
      {(upgradeTo) => (
        <Switch>
          <Match when={upgradeTo.termToType === 'payment'}><PianoPaymentTermIcon /></Match>
          <Match when={upgradeTo.termToType === 'registration'}><PianoRegistrationTermIcon /></Match>
          <Match when={upgradeTo.termToType === 'gift'}><PianoGiftTermIcon /></Match>
          <Match when={upgradeTo.termToType === 'external'}><PianoExternalTermIcon /></Match>
          <Match when={upgradeTo.termToType === 'dynamic'}><PianoDynamicTermIcon /></Match>
        </Switch>
      )}
    </For>
  )}
</For>

Primitives

The header bar (root). A flex row that lays out its groups with space-between, so the first group sits at the start and the last at the end. It is purely structural - it holds no state; the visible parts are composed from Header.Group with controls placed directly inside.

A Header.Group is reused for either side - its position (start / end) is determined by the order it appears in the header and the root's space-between layout, not by the group itself.

Primitive

Description

Header

Root flex row that lays out its groups with space-between.

Header.Group

A flex group of controls inside Header. The same group is reused for either side.

Header primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

Header.Group parts.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Header.Group primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

The controls to render (buttons, selectors, etc.).

class

string

Optional

-

CSS class name for the group element.

id

string

Optional

-

ID for the group element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<Header>
  <Header.Group>
    <PianoLocaleSelector />
  </Header.Group>
  <Header.Group>
    <PianoUserControl />
    <PianoCloseButton />
  </Header.Group>
</Header>

CloseButton

Compound close button. On click, it first calls the optional onClose , then dispatches the global closeButtonClicked signal. The icon (CloseButton.Icon, the default close icon, overridable via children) is composed as a child.

Primitive

Description

CloseButton

Root interactive button. Dispatches the global close signal and calls onClose.

CloseButton.Icon

The decorative icon (aria-hidden). Renders the built-in close icon by default.

CloseButton primitive

Attribute name

Type

Required/Optional

Default value

Description

onClose

(e: Event) => void

Optional

-

Called after the close signal is dispatched.

type

"rounded" | "square"

Optional

"square"

Visual shape: "square" (63px) or "rounded" (circular, 24px default size).

ariaLabel

string

Optional

"Close modal"

Explicit accessible label.

name

string

Optional

-

Name attribute for the button.

disabled

boolean

Optional

-

Whether the button is disabled.

width

string

Optional

"63px" ("24px" when type is "rounded")

CSS width value.

height

string

Optional

"63px" ("24px" when type is "rounded")

CSS height value.

minWidth

string

Optional

-

CSS min-width value.

minHeight

string

Optional

-

CSS min-height value.

maxWidth

string

Optional

-

CSS max-width value.

maxHeight

string

Optional

-

CSS max-height value.

opacity

string

Optional

-

CSS opacity value.

externalEventName

string

Optional

-

External event name (analytics).

externalEventParams

Record<string, unknown>

Optional

-

External event params (analytics).

ref

HTMLButtonElement | Setter<HTMLButtonElement>

Optional

-

Ref to the button element.

children

JSX.Element

Optional

-

CloseButton.Icon.

class

string

Optional

-

CSS class name for the button element.

id

string

Optional

-

ID for the button element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

CloseButton.Icon primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Optional

Built-in close icon

Optional custom icon.

class

string

Optional

-

CSS class name for the icon wrapper.

id

string

Optional

-

ID for the icon wrapper.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<CloseButton onClose={(e) => handleClose(e)}>
  <CloseButton.Icon />
</CloseButton>
<CloseButton onClose={(e) => handleClose(e)}>
  <CloseButton.Icon>
    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-circle-x-icon lucide-circle-x"><circle cx="12" cy="12" r="10"/><path d="m15 9-6 6"/><path d="m9 9 6 6"/></svg>
  </CloseButton.Icon>
</CloseButton>

Countdown

Counts down toward endDate. The visible parts (title, timer, units, separators) are composed as children; each Countdown.Unit reads its value from context. When the countdown reaches zero, onComplete is fired once and the whole component unmounts itself.

The remaining time is recomputed from Date.now() on every tick, so it stays accurate even if the tab was throttled in the background. Pass a stable endDate reference.

Primitive

Description

Countdown

Root. Ticks toward endDate and exposes the remaining time via context.

Countdown.Title

The heading rendered above the timer.

Countdown.Timer

Row wrapper laying out Countdown.Unit and Countdown.Separator parts.

Countdown.Unit

A single time unit: the two-digit value above its label.

Countdown.Separator

The decorative divider placed between units (aria-hidden). Renders ":" by default.

Countdown primitive

Attribute name

Type

Required/Optional

Default value

Description

endDate

Date

Required

-

Target date the countdown ticks toward.

onComplete

() => void

Optional

-

Called once when the countdown reaches zero.

children

JSX.Element

Required

-

Countdown.Title / Countdown.Timer parts.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Countdown.Title primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

Title content.

class

string

Optional

-

CSS class name for the title element.

id

string

Optional

-

ID for the title element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Countdown.Timer primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

Countdown.Unit and Countdown.Separator parts.

class

string

Optional

-

CSS class name for the timer element.

id

string

Optional

-

ID for the timer element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Countdown.Unit primitive

Attribute name

Type

Required/Optional

Default value

Description

unit

"dd" | "hh" | "mm" | "ss"

Required

-

Which time unit to display.

children

JSX.Element

Optional

Translated unit name

Optional label override.

class

string

Optional

-

CSS class name for the unit element.

id

string

Optional

-

ID for the unit element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Countdown.Separator primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Optional

":"

Optional separator content.

class

string

Optional

-

CSS class name for the separator element.

id

string

Optional

-

ID for the separator element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<Countdown endDate={new Date("12.12.2027")}>
  <Countdown.Title>Extended sale # days only</Countdown.Title>
  <Countdown.Timer>
    <Countdown.Unit unit="dd" />
    <Countdown.Separator />
    <Countdown.Unit unit="hh" />
    <Countdown.Separator />
    <Countdown.Unit unit="mm" />
  </Countdown.Timer>
</Countdown>

Tabs

A set of layered sections of content - known as tab panels - displayed one at a time. The component is composed from Tabs.List / Tabs.Trigger / Tabs.Content, matched to each other by their value. Inactive panels are not mounted (lazy rendering).When no tab is active on mount, the first enabled trigger is auto-selected.

Primitive

Description

Tabs

Root. Holds the active-tab state and wires the primitives together by value.

Tabs.List

Container with role="tablist" wrapping the triggers; owns keyboard navigation.

Tabs.Trigger

A tab button (role="tab") tied to a value; activates its matching Tabs.Content.

Tabs.Content

A tab panel (role="tabpanel") tied to a value; rendered only while active.

Tabs primitive

Attribute name

Type

Required/Optional

Default value

Description

value

string

Optional

-

Controlled active tab value. When provided, the component is controlled.

defaultValue

string

Optional

First enabled tab

Initial active tab value in uncontrolled mode.

onChange

(value: string) => void

Optional

-

Called when the active tab changes via user interaction.

children

JSX.Element

Required

-

Tabs.List and Tabs.Content elements.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Tabs.List primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

Tabs.Trigger elements.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Tabs.Trigger primitive

Attribute name

Type

Required/Optional

Default value

Description

value

string

Required

-

Identifier matching a Tabs.Content value.

disabled

boolean

Optional

-

When true the trigger cannot be activated.

children

JSX.Element

Required

-

Label rendered inside the button.

class

string

Optional

-

CSS class name for the button element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Tabs.Content primitive

Attribute name

Type

Required/Optional

Default value

Description

value

string

Required

-

Identifier matching a Tabs.Trigger value.

children

JSX.Element

Required

-

Panel content.

class

string

Optional

-

CSS class name for the panel element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<Tabs defaultValue="account" onChange={(value) => console.log(value)}>
  <Tabs.List>
    <Tabs.Trigger value="account">Account</Tabs.Trigger>
    <Tabs.Trigger value="password">Password</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="account">Account panel</Tabs.Content>
  <Tabs.Content value="password">Password panel</Tabs.Content>
</Tabs>

Toggle

A compound on/off switch. The root holds the form-field state (name, checked, validation flags) and shares it via context; the visible parts - the switch control, label(s), and error message - are composed as children. Two labels can be placed around the control (e.g. "Off" / "On"). Validation styling (invalid) is applied to the control, and an ariaLabel provides an accessible name when no visible label is composed.

Primitive

Description

Toggle

Root. Owns the toggle state (name, checked, disabled/readonly/required/invalid) and change handler.

Toggle.Control

The visual switch track with a sliding thumb.

Toggle.Label

Label for the toggle (can appear on either side of the control).

Toggle.Error

Error message for the toggle.

Toggle primitive

Attribute name

Type

Required/Optional

Default value

Description

name

string

Required

-

Form field name; used as input id and label target.

checked

boolean

Optional

false

Whether the toggle is on.

disabled

boolean

Optional

-

Disables interaction and applies disabled styling.

readonly

boolean

Optional

-

Locks the value without the disabled cursor.

required

boolean

Optional

-

Marks the field required for form validation.

invalid

boolean

Optional

-

Applies the invalid (danger) outline.

ariaLabel

string

Optional

-

ARIA label for screen readers when no visible label is composed.

onChange

(event: Event) => unknown

Optional

-

Called when the toggle state changes.

children

JSX.Element

Required

-

Toggle.Control, Toggle.Label and Toggle.Error parts.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Toggle.Control primitive

Toggle.Control takes no props - it renders the switch track and thumb and reads the toggle state from context.

Toggle.Label primitive

Attribute name

Type

Required/Optional

Default value

Description

ariaLabel

string

Optional

-

ARIA label override.

children

JSX.Element

Required

-

Label content.

class

string

Optional

-

CSS class name for the label element.

id

string

Optional

-

ID for the label element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Toggle.Error primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

Error message content.

class

string

Optional

-

CSS class name for the error element.

id

string

Optional

Control's aria error id

ID for the error element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<Toggle name="darkMode" checked={true} onChange={(e) => console.log(e)}>
  <Toggle.Label>Off</Toggle.Label>
  <Toggle.Control />
  <Toggle.Label>On</Toggle.Label>
  <Toggle.Error>Error message</Toggle.Error>
</Toggle>

Input

A compound text input field. The visible parts - label, the underlying <input>, and the error message - are composed as children. Validation styling (invalid) and aria-invalid are applied to the field, and the label, input, and error are wired together with the matching id / for / aria attributes.

Primitive

Description

Input

Root. Owns the field state (name, value, disabled/readonly/required/invalid) and change handlers.

Input.Label

Label for the input.

Input.Field

Renders the underlying <input> element.

Input.Error

Error message for the input.

Input primitive

Attribute name

Type

Required/Optional

Default value

Description

name

string

Required

-

Form field name; used as input id and label target.

value

string

Optional

""

Controlled input value.

disabled

boolean

Optional

-

Disables interaction and applies disabled styling.

readonly

boolean

Optional

-

Locks the value without the disabled cursor.

required

boolean

Optional

-

Marks the field required for form validation.

invalid

boolean

Optional

-

Applies the invalid (danger) styling and aria-invalid.

onChange

(event: InputEvent | Event) => unknown

Optional

-

Called when the input value changes.

onEnter

(event: KeyboardEvent) => unknown

Optional

-

Called when the user presses Enter inside the input.

children

JSX.Element

Required

-

Input.Label, Input.Field and Input.Error parts.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Input.Label primitive

Attribute name

Type

Required/Optional

Default value

Description

view

string

Optional

"default"

Visual label variant forwarded to InputLabel.

ariaLabel

string

Optional

-

ARIA label override.

children

JSX.Element

Required

-

Label content.

class

string

Optional

-

CSS class name for the label element.

id

string

Optional

-

ID for the label element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Input.Field primitive

Attribute name

Type

Required/Optional

Default value

Description

type

string

Required

-

Native input type (e.g. "text", "email", "password", "number").

placeholder

string

Optional

-

Placeholder text.

autofocus

boolean

Optional

-

When true the input is focused on mount.

autocomplete

string

Optional

-

Native autocomplete attribute.

minLength

number

Optional

-

Native minlength attribute.

maxLength

number

Optional

-

Native maxlength attribute.

min

number

Optional

-

Native min attribute (numeric inputs).

max

number

Optional

-

Native max attribute (numeric inputs).

height

string

Optional

-

CSS height applied as inline style.

width

string

Optional

-

CSS width applied as inline style.

padding

string

Optional

-

CSS padding applied as inline style.

textAlign

CSS.Property.TextAlign

Optional

-

CSS text-align applied as inline style.

inputMode

"none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search"

Optional

-

Native inputmode hint.

pattern

string

Optional

-

Native pattern attribute.

iconLeft

boolean

Optional

-

When true reserves padding for a left icon.

iconRight

boolean

Optional

-

When true reserves padding for a right icon.

ariaLabel

string

Optional

-

Accessible label for screen readers.

autocorrect

"on" | "off"

Optional

-

Native autocorrect attribute.

autocapitalize

"on" | "off" | "none" | "sentences" | "words" | "characters"

Optional

-

Native autocapitalize attribute.

e2e

string

Optional

-

Sets data-e2e on the input, for automated tests.

id

string

Optional

Field name from context

ID for the input element.

class

string

Optional

-

CSS class for the input element.

classList

Record<string, boolean>

Optional

-

Conditional CSS classes for the input element.

style

Record<string, string | undefined>

Optional

-

Inline styles merged with the field's internal style.

Input.Error primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

Error message content.

class

string

Optional

-

CSS class name for the error element.

id

string

Optional

Input's aria error id

ID for the error element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<Input name="email" onChange={(e) => console.log(e.target)}>
  <Input.Label>Email</Input.Label>
  <Input.Field type="email" placeholder="you@example.com" />
  <Input.Error>Invalid email</Input.Error>
</Input>

Checkbox

A compound checkbox. The visible parts - the box control, label, and error message - are composed as children. The label is natively associated with the input via for (clicking it toggles the control) and can be placed before or after the control to render it on the left or right. Validation styling (invalid) is applied to the control, and an ariaLabel provides an accessible name when no visible label is composed.

Primitive

Description

Checkbox

Root. Owns the field state (name, checked, disabled/readonly/required/invalid) and change handler.

Checkbox.Control

The visual checkbox box, showing the tick icon when checked.

Checkbox.Label

Label for the checkbox, natively associated with the input via for.

Checkbox.Error

Error message for the checkbox. Rendered in place; nothing is shown while empty.

Checkbox primitive

Attribute name

Type

Required/Optional

Default value

Description

name

string

Required

-

Form field name; used as input id and label target.

checked

boolean

Optional

false

Whether the checkbox is checked.

disabled

boolean

Optional

-

Disables interaction and applies disabled styling.

readonly

boolean

Optional

-

Locks the value without the disabled cursor.

required

boolean

Optional

-

Marks the field required for form validation.

invalid

boolean

Optional

-

Applies the invalid (danger) border.

ariaLabel

string

Optional

-

ARIA label for screen readers when no visible label is composed.

ariaLabelledBy

string

Optional

-

ID of an element whose text labels the checkbox for screen readers.

describedById

string

Optional

-

ID of your own error element, if you render the error message outside this component. Used while invalid is true.

e2e

string

Optional

-

Sets data-e2e on the checkbox input, for automated tests.

onChange

(event: Event) => unknown

Optional

-

Called when the checked state changes.

children

JSX.Element

Required

-

Checkbox.Control, Checkbox.Label and Checkbox.Error parts.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Checkbox.Control primitive

Checkbox.Control takes no props - it renders the box (with the tick icon when checked) and reads the checkbox state from context.

Checkbox.Label primitive

Attribute name

Type

Required/Optional

Default value

Description

ariaLabel

string

Optional

-

ARIA label override.

children

JSX.Element

Required

-

Label content.

class

string

Optional

-

CSS class name for the label element.

id

string

Optional

-

ID for the label element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Checkbox.Error primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

Error message content.

class

string

Optional

-

CSS class name for the error element.

id

string

Optional

Control's aria error id

ID for the error element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<Checkbox name="acceptTerms" required={true} onChange={(e) => console.log(e)}>
  <Checkbox.Control />
  <Checkbox.Label>I accept the terms</Checkbox.Label>
  <Checkbox.Error>This field is required</Checkbox.Error>
</Checkbox>

Textarea

A compound multi-line text field.The visible parts - label, the underlying <textarea>, and the error message - are composed as children. Validation styling (invalid) and aria-invalid are applied to the field, and the label, textarea, and error are wired together with the matching id / for / aria attributes.

Primitive

Description

Textarea

Root. Owns the field state (name, value, disabled/readonly/required/invalid) and change handler.

Textarea.Label

Label for the textarea.

Textarea.Field

Renders the underlying <textarea> element.

Textarea.Error

Error message for the textarea.

Textarea primitive

Attribute name

Type

Required/Optional

Default value

Description

name

string

Required

-

Form field name; used as textarea id and label target.

value

string

Optional

""

Controlled textarea value.

disabled

boolean

Optional

-

Disables interaction and applies disabled styling.

readonly

boolean

Optional

-

Locks the value without the disabled cursor.

required

boolean

Optional

-

Marks the field required for form validation.

invalid

boolean

Optional

-

Applies the invalid (danger) styling and aria-invalid.

describedById

string

Optional

{name}-error

ID of your own error element, if you render the error message outside this component. Used while invalid is true.

onChange

(event: InputEvent | Event) => unknown

Optional

-

Called when the textarea value changes.

children

JSX.Element

Required

-

Textarea.Label, Textarea.Field and Textarea.Error parts.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Textarea.Label primitive

Attribute name

Type

Required/Optional

Default value

Description

view

string

Optional

"default"

Visual label variant forwarded to InputLabel.

ariaLabel

string

Optional

-

ARIA label override.

children

JSX.Element

Required

-

Label content.

class

string

Optional

-

CSS class name for the label element.

id

string

Optional

-

ID for the label element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Textarea.Field primitive

Attribute name

Type

Required/Optional

Default value

Description

placeholder

string

Required

-

Placeholder text.

autofocus

boolean

Optional

-

When true the textarea is focused on mount.

minLength

number

Optional

-

Native minlength attribute.

maxLength

number

Optional

-

Native maxlength attribute.

rows

number

Optional

-

Native rows attribute.

cols

number

Optional

-

Native cols attribute.

maxWidth

string

Optional

-

CSS max-width applied as inline style.

height

string

Optional

-

CSS height applied as inline style.

width

string

Optional

-

CSS width applied as inline style.

resize

Property.Resize

Optional

-

CSS resize behaviour applied as inline style.

class

string

Optional

-

CSS class for the textarea element.

classList

Record<string, boolean>

Optional

-

Conditional CSS classes for the textarea element.

Textarea.Error primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

Error message content.

class

string

Optional

-

CSS class name for the error element.

id

string

Optional

Textarea's aria error id

ID for the error element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<Textarea name="comment" onChange={(e) => console.log(e.target)}>
  <Textarea.Label>Your comment</Textarea.Label>
  <Textarea.Field placeholder="Type here..." rows={4} />
  <Textarea.Error>This field is required</Textarea.Error>
</Textarea>

Select

A compound dropdown select. The root holds the form-field state (name, options, selection, validation flags) and shares it via context. The visible parts - label, the clickable trigger box, the dropdown listbox, and the error message - are composed as children. The options are provided to the root as data (options), and Select.Content renders them. Validation styling (invalid) is applied to the control, and label / trigger / error are wired together with the matching id / aria attributes.

Primitive

Description

Select

Root. Owns the field state (name, options, selected, disabled/readonly/required/invalid, view, sizing).

Select.Label

Label for the select.

Select.Trigger

The clickable selector box (selected text / placeholder + chevron) that opens the dropdown.

Select.Content

The dropdown listbox of options (rendered from the Select's options).

Select.Error

Error message for the select.

Select primitive

Attribute name

Type

Required/Optional

Default value

Description

name

string

Required

-

Form field name.

options

{ id: string; text: string }[]

Required

-

The selectable options ({ id, text }).

selected

string

Optional

-

Id of the currently selected option.

disabled

boolean

Optional

-

Disables the control and applies disabled styling.

readonly

boolean

Optional

-

Locks the value without the disabled cursor.

invalid

boolean

Optional

-

Applies the invalid (danger) styling.

describedById

string

Optional

{name}-error

ID of your own error element, if you render the error message outside this component. Used while invalid is true.

view

"default" | "inline"

Optional

"default"

Visual variant: "default" (boxed) or "inline" (underline).

maxVisibleRows

number

Optional

4

Max options visible before the dropdown scrolls.

maxWidth

string

Optional

-

CSS max-width applied to the root.

searchable

boolean

Optional

false

Renders a search filter at the top of the dropdown.

searchPlaceholder

string

Optional

"Search"

Placeholder text of the search box.

onChange

(event: InputEvent | Event) => unknown

Optional

-

Called whenever an option is picked, including the option that is already selected.

children

JSX.Element

Required

-

Select.Label, Select.Trigger, Select.Content and Select.Error parts.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Select.Label primitive

Attribute name

Type

Required/Optional

Default value

Description

ariaLabel

string

Optional

-

ARIA label override.

children

JSX.Element

Required

-

Label content.

class

string

Optional

-

CSS class name for the label element.

id

string

Optional

-

ID for the label element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

Select.Trigger primitive

Attribute name

Type

Required/Optional

Default value

Description

placeholder

string

Required

-

Text shown when nothing is selected.

iconLeft

JSX.Element

Optional

-

Icon rendered on the left of the box.

Select.Content primitive

Select.Content takes no props - it renders the dropdown listbox.

Select.Error primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

Error message content.

class

string

Optional

-

CSS class name for the error element.

id

string

Optional

Select's aria error id

ID for the error element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<Select name="country" options={options} onChange={(e) => console.log(e.target)}>
  <Select.Label>Country</Select.Label>
  <Select.Trigger placeholder="Select a country" />
  <Select.Content />
  <Select.Error>Required</Select.Error>
</Select>

MultiSelect

A compound multi-select dropdown. Same anatomy as Select - the root holds the form-field state and shares it via context, and the visible parts are composed as children - but picking an option toggles it in and out of the selection without closing the dropdown. Fully controlled: the selection comes from the selected array and every toggle calls onValuesChange with the full new array. The trigger shows a removable chip for each selected option.

Primitive

Description

MultiSelect

Root. Owns the field state (name, options, selected ids, disabled/readonly/required/invalid, view, sizing) and the toggle handler.

MultiSelect.Label

Label for the multi-select.

MultiSelect.Trigger

The clickable selector box (a removable chip per selected option / placeholder + chevron) that opens the dropdown.

MultiSelect.Content

The dropdown listbox with a tick per selected option; picking toggles the option and keeps the list open.

MultiSelect.Error

Error message, wired to the control with the matching aria attributes.

MultiSelect primitive

Attribute name

Type

Required/Optional

Default value

Description

name

string

Required

-

Form field name.

options

{ id: string; text: string }[]

Required

-

The selectable options.

selected

string[]

Optional

[]

Ids of the currently selected options.

disabled

boolean

Optional

-

Disables the control and applies disabled styling.

readonly

boolean

Optional

-

Locks the value without the disabled cursor.

invalid

boolean

Optional

-

Applies the invalid (danger) styling.

describedById

string

Optional

{name}-error

Id of an externally rendered error element for aria-describedby. Overrides the internal {name}-error.

view

string

Optional

default

Visual variant: "default" (boxed) or "inline" (underline).

maxVisibleRows

number

Optional

4

Max options visible before the dropdown scrolls.

maxWidth

string

Optional

-

CSS max-width applied to the root.

searchable

boolean

Optional

false

Renders a search filter at the top of the dropdown.

searchPlaceholder

string

Optional

Search

Placeholder for the search filter input.

onValuesChange

(selected: string[]) => void

Optional

-

Called with the full new selection array on every toggle.

children

JSX.Element

Required

-

MultiSelect.Label, MultiSelect.Trigger, MultiSelect.Content and MultiSelect.Error parts.

class

string

Optional

-

CSS class name(s) to apply to the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

MultiSelect.Label primitive

Attribute name

Type

Required/Optional

Default value

Description

ariaLabel

string

Optional

-

ARIA label override.

children

JSX.Element

Required

-

Label content.

class

string

Optional

-

CSS class name(s) to apply to the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

MultiSelect.Trigger primitive

Attribute name

Type

Required/Optional

Default value

Description

placeholder

string

Required

-

Text shown when nothing is selected.

iconLeft

JSX.Element

Optional

-

Icon rendered on the left of the box.

MultiSelect.Content primitive

MultiSelect.Content takes no props - it renders the dropdown listbox with a tick per selected option; picking toggles the option and keeps the list open.

MultiSelect.Error primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

Error message content.

class

string

Optional

-

CSS class name(s) to apply to the root element.

id

string

Optional

MultiSelect's aria error id

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

XML
<MultiSelect name="topics" options={options} selected={topics()} onValuesChange={(selected) => setTopics(selected)}>
  <MultiSelect.Label>Topics</MultiSelect.Label>
  <MultiSelect.Trigger placeholder="Select topics" />
  <MultiSelect.Content />
  <MultiSelect.Error>Required</MultiSelect.Error>
</MultiSelect>

RadioGroup

A compound group of mutually exclusive radio options. The visible parts - a group label, the option rows (each with its control and label), and an error message - are composed as children. Every option shares the group's name. Validation styling (invalid) and aria-invalid are applied to the group, the group label is referenced via aria-labelledby, and each option label is natively associated with its radio input via for.

Primitive

Description

RadioGroup

Root. Owns the group state (name, selected, disabled/readonly/required/invalid) and change handler.

RadioGroup.Label

Group-level label (the question), referenced by the group's aria-labelledby.

RadioGroup.Item

A single option row. Owns the option value for its control and label.

RadioGroup.Control

The radio dot.

RadioGroup.ItemLabel

Per-option label, natively associated with its radio input via for.

RadioGroup.Error

Group-level error message.

RadioGroup primitive

Attribute name

Type

Required/Optional

Default value

Description

name

string

Required

-

Form field name; shared by every radio input in the group.

selected

string

Optional

-

Value of the currently selected option.

disabled

boolean

Optional

-

Disables every option and applies disabled styling.

readonly

boolean

Optional

-

Locks the value; the radio dots take the disabled background and the not-allowed cursor.

required

boolean

Optional

-

Marks the group as required.

invalid

boolean

Optional

-

Applies the invalid (danger) styling and aria-invalid.

describedById

string

Optional

{name}-error

ID of your own error element, if you render the error message outside this component.

onChange

(event: InputEvent | Event) => unknown

Optional

-

Called when a different option is selected.

children

JSX.Element

Required

-

RadioGroup.Label, RadioGroup.Item and RadioGroup.Error parts.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

RadioGroup.Label primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

Label content.

class

string

Optional

-

CSS class name for the label element.

id

string

Optional

Group's label id ({name}-label)

ID for the label element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

RadioGroup.Item primitive

Attribute name

Type

Required/Optional

Default value

Description

value

string

Required

-

Value submitted when this option is selected.

disabled

boolean

Optional

Group's disabled value

Disables this option only.

children

JSX.Element

Required

-

RadioGroup.Control and RadioGroup.ItemLabel parts.

class

string

Optional

-

CSS class name for the row element.

id

string

Optional

-

ID for the row element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

RadioGroup.Control primitive

RadioGroup.Control takes no props - it renders the radio dot and reads name / selected / disabled / readonly / invalid from the group context and value from the enclosing RadioGroup.Item.

RadioGroup.ItemLabel primitive

Attribute name

Type

Required/Optional

Default value

Description

ariaLabel

string

Optional

-

ARIA label override.

children

JSX.Element

Required

-

Label content.

class

string

Optional

-

CSS class name for the label element.

id

string

Optional

-

ID for the label element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

RadioGroup.Error primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

Error message content.

class

string

Optional

-

CSS class name for the error element.

id

string

Optional

Group's aria error id

ID for the error element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<RadioGroup name="plan" selected="monthly" onChange={(e) => console.log(e.target)}>
  <RadioGroup.Label>Choose a plan</RadioGroup.Label>
  <RadioGroup.Item value="monthly">
    <RadioGroup.Control />
    <RadioGroup.ItemLabel>Monthly</RadioGroup.ItemLabel>
  </RadioGroup.Item>
  <RadioGroup.Item value="yearly">
    <RadioGroup.Control />
    <RadioGroup.ItemLabel>Yearly</RadioGroup.ItemLabel>
  </RadioGroup.Item>
  <RadioGroup.Error>Please choose a plan</RadioGroup.Error>
</RadioGroup>


CheckboxGroup

A compound group of independently selectable checkbox options - the multi-select counterpart of RadioGroup. The visible parts - a group label, the option rows (each with its control and label), and an error message - are composed as children. Every option shares the group's name but keeps its own checkbox input, so each option is its own tab stop and the root is a labelled group (role="group") rather than a single composite widget. Validation styling (invalid) and aria-invalid are applied to the group, the group label is referenced via aria-labelledby, and each option label is natively associated with its checkbox input via for.

Primitive

Description

CheckboxGroup

Root. Owns the group state (name, selected, disabled/readonly/required/invalid) and change handler.

CheckboxGroup.Label

Group-level label (the question), referenced by the group's aria-labelledby.

CheckboxGroup.Item

A single option row. Owns the option value for its control and label.

CheckboxGroup.Control

The checkbox box with the tick icon, backed by a visually hidden <input type="checkbox">.

CheckboxGroup.ItemLabel

Per-option label, natively associated with its checkbox input via for.

CheckboxGroup.Error

Group-level error message.

CheckboxGroup primitive

Attribute name

Type

Required/Optional

Default value

Description

name

string

Required

-

Form field name; shared by every checkbox input in the group.

selected

string[]

Optional

[]

Values of the currently selected options.

disabled

boolean

Optional

-

Disables every option and applies disabled styling.

readonly

boolean

Optional

-

Locks the value without the disabled cursor.

required

boolean

Optional

-

Marks the group as required.

invalid

boolean

Optional

-

Applies the invalid (danger) styling and aria-invalid.

describedById

string

Optional

{name}-error

Id of an externally rendered error element, used for aria-describedby when the group is invalid.

onChange

(event: InputEvent | Event) => unknown

Optional

-

Called when an option is toggled with the native checkbox change event: target.value is the option, target.checked its new state.

children

JSX.Element

Required

-

CheckboxGroup.Label, CheckboxGroup.Item and CheckboxGroup.Error parts.

class

string

Optional

-

CSS class name for the root element.

id

string

Optional

-

ID for the root element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

CheckboxGroup.Label primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

Label content.

class

string

Optional

-

CSS class name for the label element.

id

string

Optional

Group's label id ({name}-label)

ID for the label element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

CheckboxGroup.Item primitive

Attribute name

Type

Required/Optional

Default value

Description

value

string

Required

-

Value submitted when this option is selected.

disabled

boolean

Optional

Group's disabled value

Disables this option only (the option is also disabled when the whole group is).

children

JSX.Element

Required

-

CheckboxGroup.Control and CheckboxGroup.ItemLabel parts.

class

string

Optional

-

CSS class name for the row element.

id

string

Optional

-

ID for the row element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

CheckboxGroup.Control primitive

CheckboxGroup.Control takes no props - it renders the checkbox box (with the tick icon when checked) backed by a real, visually hidden <input type="checkbox">, and reads name / selected / disabled / readonly / invalid from the group context and value from the enclosing CheckboxGroup.Item. Clicking the visual box forwards the activation to the hidden input, so the group's onChange always receives a standard change event.

CheckboxGroup.ItemLabel primitive

Attribute name

Type

Required/Optional

Default value

Description

ariaLabel

string

Optional

-

ARIA label override.

children

JSX.Element

Required

-

Label content.

class

string

Optional

-

CSS class name for the label element.

id

string

Optional

-

ID for the label element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

CheckboxGroup.Error primitive

Attribute name

Type

Required/Optional

Default value

Description

children

JSX.Element

Required

-

Error message content.

class

string

Optional

-

CSS class name for the error element.

id

string

Optional

Group's aria error id

ID for the error element.

classList

Record<string, boolean>

Optional

-

Object for conditional CSS classes.

style

Record<string, string | undefined>

Optional

-

Inline styles as a key-value object.

<CheckboxGroup name="topics" selected={["news"]} onChange={(e) => console.log(e.target)}>
  <CheckboxGroup.Label>Pick your topics</CheckboxGroup.Label>
  <CheckboxGroup.Item value="news">
    <CheckboxGroup.Control />
    <CheckboxGroup.ItemLabel>News</CheckboxGroup.ItemLabel>
  </CheckboxGroup.Item>
  <CheckboxGroup.Item value="sport">
    <CheckboxGroup.Control />
    <CheckboxGroup.ItemLabel>Sport</CheckboxGroup.ItemLabel>
  </CheckboxGroup.Item>
  <CheckboxGroup.Error>Please pick at least one</CheckboxGroup.Error>
</CheckboxGroup>


Last updated: