diff --git a/Documentation/Toolbar/toc.yml b/Documentation/Toolbar/toc.yml
index 818a94e..1ffc4fe 100644
--- a/Documentation/Toolbar/toc.yml
+++ b/Documentation/Toolbar/toc.yml
@@ -24,3 +24,5 @@
href: groups.md
- name: Slots
href: slots.md
+ - name: Toolbar Layout
+ href: toolbar-layout.md
diff --git a/Documentation/Toolbar/toolbar-layout.md b/Documentation/Toolbar/toolbar-layout.md
new file mode 100644
index 0000000..161f02f
--- /dev/null
+++ b/Documentation/Toolbar/toolbar-layout.md
@@ -0,0 +1,121 @@
+# Toolbar Layout
+
+`ToolbarLayout` is a named, transparent region inside a `Toolbar` that enables decoupled, dynamically swappable toolbar content. Unlike `ToolbarGroup`, it carries no visual container of its own — the injected content brings its own `ToolbarGroup` pills, `ToolbarSection` context switchers, and `ToolbarSeparator` dividers.
+
+The key capability: any component in the React tree can inject a complete toolbar layout — multiple groups, sections, and separators — into a named region without prop drilling. The injection is coordinated by the `ToolbarSlotProvider`.
+
+## When to use `ToolbarLayout` vs `ToolbarGroup`
+
+| | `ToolbarGroup` | `ToolbarLayout` |
+|---|---|---|
+| Visual container | Yes — renders as a pill | No — transparent pass-through |
+| Slot content | Appended to its own children | Replaces fallback children |
+| Intended content | Individual buttons | Complete toolbar structures (groups, sections, separators) |
+| Use case | Cluster related buttons | Entire swappable toolbar regions |
+
+## Quick Start
+
+Wrap the toolbar and the contributing components in a `ToolbarSlotProvider`. Give `ToolbarLayout` a `name` prop that external components match in their `ToolbarSlot`:
+
+```tsx
+import { ToolbarSlotProvider, ToolbarSlot } from '@cratis/components';
+
+export const AppShell = () => (
+
+
+
+
+ {/* Fallback — shown when no slot content is registered */}
+
+
+
+
+
+
+
+
+);
+
+// Anywhere in the tree — injects a complete multi-group layout:
+const CanvasFeature = () => {
+ const content = useMemo(() => (
+ <>
+
+
+
+
+
+
+
+
+
+ ), []);
+
+ return {content};
+};
+```
+
+## Fallback Children
+
+The `children` prop provides default content rendered when no slot content has been registered. As soon as any `ToolbarSlot` with a matching `slotName` mounts, the slot content replaces the fallback completely.
+
+If the layout region has no meaningful default, omit `children` entirely — `ToolbarLayout` renders nothing when both its slot and its children are empty:
+
+```tsx
+{/* No fallback — layout is invisible until a feature registers */}
+
+```
+
+## Multiple Contributors
+
+Multiple components can each register a `ToolbarSlot` with the same `slotName`. The `order` prop on each slot controls the render order (lower values appear first):
+
+```tsx
+// Feature A — appears first
+
+
+
+
+
+
+// Feature B — appears second
+
+ <>
+
+
+
+
+
+
+```
+
+## Context-Sensitive Layouts
+
+A common pattern is to render a different slot content based on the active application mode. Mount and unmount (or swap the children of) a single `ToolbarSlot` as the mode changes:
+
+```tsx
+const modeContent = {
+ draw: ,
+ text: ,
+ shape: ,
+};
+
+// The ToolbarLayout region updates automatically as activeMode changes:
+
+ {modeContent[activeMode]}
+
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` | required | Identifies the layout region. Match this in `ToolbarSlot` `slotName`. |
+| `children` | `ReactNode` | — | Fallback content shown when no slot content is registered. |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction — should match the parent `Toolbar`. |
+
+## Related
+
+- [Slots](slots.md) — the slot system that powers `ToolbarLayout`
+- [Groups](groups.md) — `ToolbarGroup` for visually contained button clusters
+- [Context Switching](context-switching.md) — `ToolbarSection` for animated context changes within a slot
diff --git a/Source/Toolbar/Toolbar.stories.tsx b/Source/Toolbar/Toolbar.stories.tsx
index 1a077a2..0409ec8 100644
--- a/Source/Toolbar/Toolbar.stories.tsx
+++ b/Source/Toolbar/Toolbar.stories.tsx
@@ -12,6 +12,7 @@ import { ToolbarGroup } from './ToolbarGroup';
import { ToolbarSection } from './ToolbarSection';
import { ToolbarSeparator } from './ToolbarSeparator';
import { ToolbarSlot, ToolbarSlotProvider } from './ToolbarSlot';
+import { ToolbarLayout } from './ToolbarLayout';
const meta: Meta = {
title: 'Components/Toolbar',
@@ -717,3 +718,287 @@ export const WithMultipleSlotContributors: Story = {
);
},
};
+
+ // ─── ToolbarLayout stories ────────────────────────────────────────────────────
+
+ /**
+ * Demonstrates {@link ToolbarLayout} rendering its fallback children when no slot
+ * content has been registered. The layout acts as a transparent container so the
+ * injected {@link ToolbarGroup} pills appear exactly as they would if placed
+ * directly inside the {@link Toolbar}.
+ */
+ export const LayoutWithDefaultContent: Story = {
+ render: () => (
+
+
+
+
+
+
+
+
+
+
+ ),
+ };
+
+ /**
+ * Shows a feature injecting a complete toolbar layout — multiple groups and a
+ * separator — into a named {@link ToolbarLayout} region from anywhere in the tree.
+ * Toggle the "Feature mounted" switch to see the layout region swap between the
+ * default content and the injected content.
+ */
+ export const LayoutWithInjectedContent: Story = {
+ render: () => {
+ const LayoutWithInjectedContentDemo = () => {
+ const [featureMounted, setFeatureMounted] = useState(true);
+
+ const featureContent = useMemo(
+ () => (
+ <>
+
+
+
+
+
+
+
+
+
+ ),
+ []
+ );
+
+ return (
+
+