Skip to main content
Version: Development 🚧

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.

Complex Example​