Morph · Application UI
MorphDock
A config-driven morphing navigation dock. The item row morphs compact ↔ full, and the whole pill blooms in place into a consumer-provided panel via useChromeMorph, items, badges, core/pinned flags, a trailing cluster, and a contextual action. Pure --dock tokens, reduced-motion + Esc + click-away.
@byronwade/foundation@byronwade/utils@byronwade/use-chrome-morph@phosphor-icons/react
Feature showcase
Installation
Features
Config-driven navigation
Items, pinned items, tools, breadcrumbs, badges, and actions are all driven from typed config.
Morphing panel surface
Uses useChromeMorph to bloom the dock into a consumer-provided panel with controlled state support.
Advanced chrome states
Supports status overlays, save actions, draggable panels, resizable panels, placements, and tones.
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| items | MorphDockItem[] | - | Nav items: id, label, icon, optional onSelect/href, active, core, pinned, badge, group (a seam is drawn between adjacent items of differing groups). |
| expandable | boolean | true | Allow compact ↔ full toggling via a chevron button. |
| cluster | React.ReactNode | - | Custom trailing slot (count + badge, env tag, search button…). |
| action | { label; icon; onSelect? } | - | Contextual action pill, blooms the panel when children are present, else runs onSelect. |
| tools | MorphDockAction[] | - | Trailing two-tone tool zone (bg-dock-tool), a combined nav + toolbar pill. Actions: id, label, icon, onSelect?/href?, primary (brand fill), group (seam between groups). |
| breadcrumb | { label: string; href?: string }[] | - | Leading crumb trail; the last crumb is the current page (aria-current). |
| status | MorphDockStatus | null | - | A save/validation outcome the panel blooms into (success/error/info). Success/info auto-dismiss; errors persist. |
| onStatusDismiss | () => void | - | Called when the status is dismissed, auto for success/info, or via its close button. |
| statusDismissMs | number | 4000 | Auto-dismiss delay (ms) for success/info status. Errors never auto-dismiss. |
| tone | "dock" | "surface" | "dock" | Dark dock pill (default) or light surface. |
| navLabel | string | "Primary" | Accessible name for the nav landmark. |
| open | boolean | - | Controlled morph open state. |
| onOpenChange | (open: boolean) => void | - | Open-state change callback. |
| children | React.ReactNode | - | The panel the dock morphs into. |
| panelTitle | React.ReactNode | - | Title shown in the panel header (alongside the drag handle / close / save chrome). |
| onSave | () => void | - | Renders a Save button in the panel header when provided. |
| panelWidth | number | 360 | Open-panel width in px. |
| panelHeight | number | - | Open-panel height in px. Omit to size to content (bloom-down). |
| growHeight | boolean | true | Bloom width + height (default) or width-only. |
| placement | "top" | "bottom" | "left" | "right" | "bottom" | Which way the panel blooms from the bar. |
| origin | "start" | "center" | "end" | "start" | Where along the dock the panel grows from, a centered dock blooms symmetrically with "center". |
| draggable | boolean | false | Detach the open panel and drag it free by its handle (flies home on close). |
| resizable | boolean | false | Show a corner grip to resize the open panel; the morph box follows live. |
| bare | boolean | false | Drop the resting pill background/shadow, items float free until a panel blooms (the panel keeps its surface). |
Exports
| Export | Kind | Description |
|---|---|---|
| MorphDock | component | Morphing navigation dock and panel component. |
| MorphDockItem | type | Configuration object for a primary dock item. |
| MorphDockAction | type | Configuration object for action/tool items. |
| MorphDockProps | type | Public props for the MorphDock component. |
Slots
| Slot | Element | Description |
|---|---|---|
| morph-dock-breadcrumb | - | Breadcrumb trail rendered before the dock nav. |
| morph-dock-tools | - | Trailing tool zone inside the dock pill. |
| morph-dock-seam | - | Visual separator between item or tool groups. |
CSS Variables
| Variable | Default | Description |
|---|---|---|
| --dock | - | Dock surface token used by the resting pill. |
| --dock-tool | - | Tool-zone surface token. |
| --dock-active | - | Active dock item token. |
Dependencies
| Package | Kind | Description |
|---|---|---|
| @byronwade/foundation | registry | Installed through the byronwade/ui registry. |
| @byronwade/utils | registry | Installed through the byronwade/ui registry. |
| @byronwade/use-chrome-morph | registry | Installed through the byronwade/ui registry. |
| @phosphor-icons/react | npm | Installed from npm. |
Source and related
| File | Path |
|---|---|
| Component | registry/ui/morph-dock.tsx |
| Default example | content/examples/morph-dock/default.tsx |
| Draggable example | content/examples/morph-dock/draggable.tsx |
| Resizable example | content/examples/morph-dock/resizable.tsx |