HySplitterHandle
Usage examples on this page are written for Lit / plain HTML (
<hy-splitter-handle>). The same component ships asHySplitterHandlein@whitespaceux/harmony-react(native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.
Used inside <hy-splitter> — it only means something as part of it.
An interactive separator handle within an hy-splitter group. Implements the WAI-ARIA separator role with keyboard support. Provides a draggable divider between adjacent panels.
This component is not designed to be used standalone - it must be placed between hy-splitter-panel elements inside an hy-splitter.
When not to use
- A line that separates content but resizes nothing:
hy-divider.
Accessibility: your part
- Set
labelto say what the handle resizes ("Resize sidebar"). The fallback "Resize" does not tell handles apart.
Examples
Basic handle
<hy-splitter-handle></hy-splitter-handle>With accessible label
<hy-splitter-handle label="Resize sidebar"></hy-splitter-handle>Collapsed state
When a panel next to the handle is collapsed, the parent splitter sets collapsed to the side it sits on (before / after). The handle then shows a tab flush against the bar, on the side of the open panel, holding a chevron that points the way the hidden panel opens (mirrored in right-to-left). A click on the handle (a press that does not move it), or Enter, opens the panel again.
API
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | false | Whether this handle is disabled (non-interactive). |
label | label | string | 'Resize' | Accessible label for the separator (used as aria-label). An empty value falls back to 'Resize' too, so the separator is never unnamed. |
orientation | orientation | 'horizontal' | 'vertical' | 'horizontal' | Orientation (set by parent splitter). |
dragging | dragging | boolean | false | Whether the handle is currently being dragged (set by parent splitter). |
collapsed | collapsed | 'before' | 'after' | — | Which neighboring panel is collapsed, if any (set by parent splitter). Shows the collapsed tab; see "Collapsed state". |
groupDisabled | group-disabled | boolean | false | Whether the parent group is disabled (set by parent splitter). |
valueNow | value-now | number | 0 | Current value for aria-valuenow. |
valueMin | value-min | number | 0 | Minimum value for aria-valuemin. |
valueMax | value-max | number | 100 | Maximum value for aria-valuemax. |
CSS Parts
| Part | Description |
|---|---|
handle | The separator container |
handle-bar | The visible bar element |
CSS Custom Properties
The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.
| Property | Default | Description |
|---|---|---|
--hy-splitter-handle-ornament-tick | var(--hy-ornament-tick) | Visible bar thickness |
--hy-splitter-handle-ornament-handle | var(--hy-ornament-handle) | Invisible drag area (48px on touch) |
--hy-splitter-handle-border-default-rest | var(--hy-border-default-rest) | Bar color at rest |
--hy-splitter-handle-border-default-pressed | var(--hy-border-default-pressed) | Bar color on hover |
--hy-splitter-handle-background-brand-indicator-rest | var(--hy-background-brand-indicator-rest) | Bar color while dragging (CSS :active, transient) |
--hy-splitter-handle-radius-container-2xs | var(--hy-radius-container-2xs) | Bar border radius |
--hy-splitter-handle-motion-transition-hover-duration | var(--hy-motion-transition-hover-duration) | Transition duration for hover and focus state feedback |
--hy-splitter-handle-motion-transition-hover-easing | var(--hy-motion-transition-hover-easing) | Transition easing for hover and focus state feedback |
--hy-splitter-handle-ornament-knob | var(--hy-ornament-knob) | Size of the collapsed tab |
--hy-splitter-handle-icon-size-xs | var(--hy-icon-size-xs) | Chevron size in the collapsed tab |
--hy-splitter-handle-background-surface-base | var(--hy-background-surface-base) | Collapsed tab fill |
--hy-splitter-handle-foreground-icon-subtle-rest | var(--hy-foreground-icon-subtle-rest) | Collapsed tab chevron color (the subtle icon ink, C9) |
--hy-splitter-handle-stroke-sm | var(--hy-stroke-sm) | Collapsed tab outline width; its color follows the bar's |
--hy-splitter-handle-radius-container-sm | var(--hy-radius-container-sm) | Collapsed tab radius on its free corners |