ShardsUI is in beta. APIs may change before 1.0.

Props & attributes

Shared props and data attributes.

Each component's API reference lists its own props and attributes. This page collects the ones that recur across the library, grouped by the part that takes them.

Element props

Every part that renders an element accepts these.

PropTypeDefault

Anything that isn't one of a part's own props is forwarded to the element, and your event handlers run alongside the part's rather than replacing them — see Composition.

Every part that renders an element also exposes it through ref, populated once the element mounts:

<Popover.Trigger bind:ref={trigger}>Open</Popover.Trigger>

Providers that render no element of their own, such as Dialog.Root, don't.

Availability

PropTypeDefault

Value and selection

PropTypeDefault

Open state

For overlays with open state (dialog, menu, popover, select, …).

PropTypeDefault

Detached triggers

Dialog, Alert Dialog, Drawer, Popover, Menu, Tooltip, and Preview Card can link a trigger to a root that isn't its ancestor, through a handle created from the component's Handle class. See Composition.

PropTypeDefault

Positioner

On the Positioner part of floating components (Popover, Menu, Select, Tooltip, …).

PropTypeDefault

The resolved side and alignment come back as data-side and data-align, and the positioner sets --anchor-width, --anchor-height, --available-width, --available-height and --transform-origin for the popup to size and animate against — see Styling.

Mounting

Overlays reach the DOM through an explicit <*.Portal> part, which wraps the Backdrop and the Positioner — or, for Dialog, Alert Dialog and Drawer, the Popup. Toast.Portal takes container only; every other Portal also takes keepMounted.

PropTypeDefault

Triggers

Triggers render a real <button> wherever the pattern allows it, so type="button", activation on Enter and Space, and the disabled state come from the platform. Point as at another tag — <a> for a link, <span> where a <button> can't nest — and the part adds role="button", tabindex and the keyboard handlers a native button would have given you.

Focus and hover

For dialogs, popups, and hover-openable components.

PropTypeDefault

List navigation

For menus, lists, and composite widgets.

PropTypeDefault

Form

PropTypeDefault

Machinery specific to one component family — a list's items / filter / itemToStringValue, or a range's min / max / format — stays on that component's page.

For the full controlled and uncontrolled patterns, see State.

Data attributes

Every part mirrors its live state onto its element as data-* attributes, so you style against state instead of tracking it yourself — see Styling.

Open and closed

AttributeDescription
data-openPresent while the element is open.
data-closedPresent while the element is closed.
data-popup-openPresent on a trigger while its popup is open.
data-hiddenPresent once a closed panel has finished animating out.

Selection and pressed

AttributeDescription
data-checkedPresent when checked or selected.
data-uncheckedPresent when not checked.
data-indeterminatePresent in the indeterminate state.
data-selectedPresent on the item holding the selected value.
data-highlightedPresent on the item the keyboard or pointer has highlighted in a list.
data-pressedPresent when a toggle is pressed, or a trigger's popup is open.
data-placeholderPresent while no value is selected.

Availability

AttributeDescription
data-disabledPresent when disabled.
data-readonlyPresent when read-only.
data-requiredPresent when required.

Field validation

Present within a Field, reflecting the control's validation state.

AttributeDescription
data-validPresent when the control is valid.
data-invalidPresent when the control is invalid.
data-dirtyPresent after the value has changed.
data-touchedPresent after the control has been blurred.
data-filledPresent when the control has a value.
data-focusedPresent while the control is focused.

Orientation and position

AttributeDescription
data-orientation'horizontal' | 'vertical' — the component's orientation.
data-sideThe side the popup landed on relative to its anchor, after collision handling.
data-alignHow the popup is aligned along that side.
data-anchor-hiddenPresent when the anchor has been scrolled or clipped out of view, so the popup has nothing to point at.
data-activation-directionWhich way the newly active item sits from the last one. Tabs and Navigation Menu emit one of left, right, up, down, and Tabs emits none until a tab is activated; a popup Viewport emits a horizontal and vertical pair, such as right down.

Animation

Set the resting styles as the default and the transitional styles behind these attributes — see Animation.

AttributeDescription
data-starting-stylePresent on the frame an element mounts — the "from" of an enter transition.
data-ending-stylePresent while an element is leaving — the "to" of an exit transition.
data-instantPresent when the change should skip its animation. Its value names why, such as 'dismiss' or 'focus'.
data-transitioningPresent on a Viewport while it swaps one popup's content for another's.
data-currentOn the Viewport wrapper holding the current content.
data-previousOn the Viewport wrapper holding the outgoing content, during that swap.
data-draggingPresent while the element is being dragged.
data-swipingPresent while the element is being swiped.
data-swipe-direction'up' | 'down' | 'left' | 'right' — the direction of the swipe.

Progress

AttributeDescription
data-progressingPresent while the task is in progress.
data-completePresent once the task has completed.

Scroll area

AttributeDescription
data-scrollingPresent while the user is scrolling.
data-has-overflow-xPresent when the content is wider than the viewport.
data-has-overflow-yPresent when the content is taller than the viewport.
data-overflow-x-startPresent when content is scrolled past the horizontal start.
data-overflow-x-endPresent when content extends past the horizontal end.
data-overflow-y-startPresent when content is scrolled past the vertical start.
data-overflow-y-endPresent when content extends past the vertical end.

Nesting

AttributeDescription
data-nestedPresent when the element is nested within another of its kind.
data-nested-dialog-openPresent on a dialog while a dialog nested inside it is open.