ToolPanelConfig

Since v0.1.1

Tool panel configuration

Properties

Property	Type	Description
position?	left | right	Panel position: ‘left'
width?	number	Default panel width in pixels (default: 280)
defaultOpen?	string	⚠️ Accordion section to auto-expand the first time the tool panel opens. v0.1.1+
initialState?	open | closed	Initial open state of the tool panel sidebar on grid load. v2.9.0+
locked?	boolean	When true, lock the tool panel sidebar in its open state. v2.9.0+
persistState?	boolean	Whether to persist open/closed state (requires Column State Events)
closeOnClickOutside?	boolean	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?	overlay | push | dropdown	Layout mode for the tool panel. v2.8.0+

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'

---