Gridview

Gridview is a collection of nested splitviews and is the foundation for the Dockview component. Gridview serves a purpose when you want only the nested splitviews with no tabs and no headers.

Introduction

GridviewReact Component

import { ReactGridview } from 'dockview';

className	string
components	PanelCollection<IGridviewPanelProps<any>>
disableAutoResizing	boolean
hideBorders	boolean
onReady	(event: GridviewReadyEvent): void
orientation	Orientation
proportionalLayout	boolean

Gridview API

const MyComponent = (props: IGridviewPanelProps<{ title: string }>) => {
    // props.containerApi...

    return <div>{`My first panel has the title: ${props.params.title}`}</div>;
};

const onReady = (event: GridviewReadyEvent) => {
    // event.api...
};

height	Height of the component. number
maximumHeight	Maximum height of the component. number
maximumWidth	Maximum width of the component. number
minimumHeight	Minimum height of the component. number
minimumWidth	Minimum width of the component. number
onDidActivePanelChange	Invoked when the active panel changes. May be undefined if no panel is active. Event<IGridviewPanel<GridviewPanelApi> | undefined>
onDidAddPanel	Invoked when a panel is added. May be called multiple times when moving panels. Event<IGridviewPanel<GridviewPanelApi>>
onDidLayoutChange	Invoked when any layout change occures, an aggregation of many events. Event<void>
onDidLayoutFromJSON	Invoked after a layout is deserialzied using the fromJSON method. Event<void>
onDidRemovePanel	Invoked when a panel is removed. May be called multiple times when moving panels. Event<IGridviewPanel<GridviewPanelApi>>
orientation	Current orientation. Can be changed after initialization. Orientation
panels	All panel objects. IGridviewPanel<GridviewPanelApi>[]
width	Width of the component. number
addPanel	Add a panel and return the created object. <T extends object = Parameters>(options: AddComponentOptions<T>): IGridviewPanel<GridviewPanelApi>
clear	Reset the component back to an empty and default state. (): void
focus	Focus the component. Will try to focus an active panel if one exists. (): void
fromJSON	Create a component from a serialized object. (data: SerializedGridviewComponent): void
getPanel	Get a panel object given a string id. May return undefined. (id: string): IGridviewPanel<GridviewPanelApi> | undefined
layout	Force resize the component to an exact width and height. Read about auto-resizing before using. (width: number, height: number, force: boolean = false): void
movePanel	Move a panel in a particular direction relative to another panel. (panel: IGridviewPanel<GridviewPanelApi>, options: { direction: Direction, reference: string, size: number }): void
removePanel	Remove a panel given the panel object. (panel: IGridviewPanel<GridviewPanelApi>, sizing?: Sizing): void
toJSON	Create a serialized object of the current component. (): SerializedGridviewComponent

Gridview Panel API

const MyComponent = (props: IGridviewPanelProps<{ title: string }>) => {
    // props.api...

    return <div>{`My first panel has the title: ${props.params.title}`}</div>;
};

height	The panel height in pixels number
id	The id of the panel that would have been assigned when the panel was created string
isActive	Whether the panel is the actively selected panel boolean
isFocused	Whether the panel holds the current focus boolean
isVisible	Whether the panel is visible boolean
onDidActiveChange	Event<ActiveEvent>
onDidConstraintsChange	Event<GridConstraintChangeEvent>
onDidDimensionsChange	Event<PanelDimensionChangeEvent>
onDidFocusChange	Event<FocusEvent>
onDidVisibilityChange	Event<VisibilityEvent>
width	The panel width in pixels number
setActive	(): void
setConstraints	(value: GridConstraintChangeEvent2): void
setSize	(event: SizeEvent): void
setVisible	(isVisible: boolean): void
updateParameters	(parameters: Parameters): void

Resizing

Panel Resizing

You can set the size of a panel using props.api.setSize(...).

// it's mandatory to provide either a height or a width, providing both is optional
props.api.setSize({
    height: 100,
    width: 200,
});

You can update any constraints on the panel. All parameters are optional.

props.api.setConstraints({
    minimumHeight: 100,
    maximumHeight: 1000
    minimumWidth: 100,
    maximumWidth: 1000
});

You can hide a panel by setting it's visibility to false. Hidden panels retain their size at the point of being hidden, if made visible again they will try to resize to the remembered size.

props.api.setVisible(false);

Panels

Add Panel

Using the gridview API you can access the addPanel method which returns an instance of the created panel. The minimum method signature is:

const panel = api.addPanel({
    id: 'my_unique_panel_id',
    component: 'my_component',
});

where id is the unique id of the panel and component is the implenentation which will be used to render the panel. You will have registered this using the components prop of the GridviewReactComponent component.

You can pass bounding constraints to limit the size of the panel.

const panel = api.addPanel({
    id: 'my_unique_panel_id',
    component: 'my_component',
    minimumHeight: 100,
    maximumHeight: 1000,
    minimumWidth: 100,
    maximumWidth: 1000,
});

You can pass a snap parameter which will hide the panel when an attempt is made to move it beyond a minimum width or height if one exists.

const panel = api.addPanel({
    id: 'my_unique_panel_id',
    component: 'my_component',
    minimumHeight: 100,
    snap: true,
});

You can pass a priority parameter which will keep the panel a certain priority when being resized. This is useful when you know you want this panel to always take the first available or last available space. The default is LayoutPriority.Normal which defers space allocations to the libraries discression.

const panel = api.addPanel({
    id: 'my_unique_panel_id',
    component: 'my_component',
    minimumHeight: 100,
    priority: LayoutPriority.High,
});

You can pass properties to the panel using the params key. You can update these properties through the panels api object and its updateParameters method.

const panel = api.addPanel({
    id: 'my_unique_panel_id',
    component: 'my_component',
    params: {
        myCustomKey: 'my_custom_value',
    },
});

panel.api.updateParameters({
    myCustomKey: 'my_custom_value',
    myOtherCustomKey: 'my_other_custom_key',
});

Note updateParameters does not accept partial parameter updates, you should call it with the entire set of parameters you want the panel to receive.

Finally addPanel accepts a position object which tells dockview where to place the panel.

• This object accepts a referencePanel which can be the associated id as a string or the panel object reference.
• This object accepts a direction property which dictates where, relative to the provided reference the new panel will be placed.

If a referencePanel is not passed then the direction will be treated as absolute.

If no direction is provided the library will place the new panel in a pre-determined position.

const panel = api.addPanel({
    id: 'panel_1',
    component: 'default',
});

const panel2 = api.addPanel({
    id: 'panel_2',
    component: 'default',
    position: {
        referencePanel: panel1,
        direction: 'right',
    },
});

Note updateParameters does not accept partial parameter updates, you should call it with the entire set of parameters you want the panel to receive.

Theme

As well as importing the dockview stylesheet you must provide a class-based theme somewhere in your application. For example.

// Providing a theme directly through the DockviewReact component props
<GridviewReact className="dockview-theme-dark" />

// Providing a theme somewhere in the DOM tree
<div className="dockview-theme-dark">
  <div>
    {/**...  */}
    <GridviewReact  />
  </div>
</div>

You can find more details on theming here.

Events

GridviewReact exposes a number of events that the developer can listen to and below is a simple example with a log panel showing those events that occur.

fromJSON

Complex Example