# ToolPanelConfig

> _Since v0.1.1_

Tool panel configuration

## Properties

| Property | Type | Description |
| -------- | ---- | ----------- |
| `position?` | <code>left &#124; right</code> | Panel position: 'left' | 'right' (default: 'right') |
| `width?` | <code>number</code> | Default panel width in pixels (default: 280) |
| `defaultOpen?` | <code>string</code> | ⚠️ Accordion section to auto-expand the first time the tool panel opens. <span class="since-badge" title="Introduced in v0.1.1">v0.1.1+</span> |
| `initialState?` | <code>open &#124; closed</code> | Initial open state of the tool panel sidebar on grid load. <span class="since-badge" title="Introduced in v2.9.0">v2.9.0+</span> |
| `locked?` | <code>boolean</code> | When `true`, lock the tool panel sidebar in its open state. <span class="since-badge" title="Introduced in v2.9.0">v2.9.0+</span> |
| `persistState?` | <code>boolean</code> | Whether to persist open/closed state (requires Column State Events) |
| `closeOnClickOutside?` | <code>boolean</code> | Close the tool panel when clicking outside of it. When `true`, clicking anywhere outside the tool panel (but inside the grid) will close the panel automatically. |
| `mode?` | <code>overlay &#124; push &#124; dropdown</code> | Layout mode for the tool panel. <span class="since-badge" title="Introduced in v2.8.0">v2.8.0+</span> |

### Property Details

#### initialState

Initial open state of the tool panel sidebar on grid load.

- `'closed'` (default) — sidebar starts collapsed; user opens it via the
  built-in toggle button or `grid.getPluginByName('shell')?.openToolPanel()`.
- `'open'` — sidebar starts open; the section named by defaultOpen
  (or the first registered panel) is expanded.

Takes precedence over the legacy v2 behavior of defaultOpen: if
`initialState` is set explicitly, it wins.

**Default:** `'closed'`

---

#### locked

When `true`, lock the tool panel sidebar in its open state.

Effects:
- Implies `initialState: 'open'` — the sidebar is forced open on load.
- `grid.getPluginByName('shell')?.closeToolPanel()` / `toggleToolPanel()` become no-ops while
  locked (the panel cannot be closed by user or programmatic actions).
- Suppresses the built-in toolbar toggle button (same effect as
  `shell.header.toolPanelToggle: false`) since toggling is disabled.
- Accordion sections inside the panel can still be expanded/collapsed.

**Default:** `false`

---

#### closeOnClickOutside

Close the tool panel when clicking outside of it.
When `true`, clicking anywhere outside the tool panel (but inside the grid)
will close the panel automatically.

Ignored in `mode: 'push'` (the panel does not overlap grid content,
so there is no meaningful "outside" to dismiss against).

**Default:** `false`

---

#### mode

Layout mode for the tool panel.

- `'overlay'` (default) — panel is positioned over the grid content;
  opening/closing the panel does not change the grid's available width.
  Best for narrow viewports.
- `'push'` — panel participates in the shell's flex layout as a sibling
  of the grid content; opening the panel shrinks the grid's available
  width and triggers a normal column-virtualization re-layout via
  ResizeObserver. Best for desktop layouts where users want to keep
  all cells visible while the panel is open.
- `'dropdown'` — the whole tool-panel sidebar (the full accordion) is
  shown as an anchored popover floating above the grid, dismissed on
  Escape or click-outside. The popover anchors to (in priority order)
  the `anchor` passed to ShellController.openToolPanel, the
  built-in toolbar toggle button, or the top corner of the grid. Best
  for compact toolbars and custom column-header "columns" buttons.

**Default:** `'overlay'`

---