Skip to main content

Adding Panels

This section describes how to add a new panel and the options you can provide.

Panels can be added through the dock api.

addPanel
Add a panel and return the created object.
addPanel<T extends object = Parameters>(options: AddPanelOptions<T>): IDockviewPanel

Opening a Basic Panel​

To open a panel requires a unique id and the name of the component to render.

const panel: IDockviewPanel = api.addPanel({
    id: 'my_unique_panel_id',
    component: 'my_component',
    // optionally set `inactive: true` to prevent the added panel becoming active automatically
    inactive: true
});

See Overview to register components.

Providing a Panel Title​

Registering and updating the title using these built-in variables only works for the default tab renderer. If you use a custom tab render you can optionally access these variables to render the title, or you can take your own approach to rendering a tab title.

Use title to provide a custom title for the panel. If no title is provided then the dock will render id in the tab.

api.addPanel({
    id: 'panel_1',
    component: 'my_component',
    title: 'my_custom_title',
});
api.setTitle('my_new_custom_title');

Provide a custom Tab renderer​

You can override the default tab renderer through the Options.

To render a custom tab component you should specify the tabComponent.

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

See Tabs to learn how to register tab components.

Provide custom Parameters​

Using the params option you can specific a simple object that is accessible in both the panel and tab renderer. To update these parameters after the panel has been created see Update Panel.

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

Rendering​

See Panel Rendering.

Positioning the Panel​

You can position a panel relative to an existing panel, group using direction. If you do not provide a reference panel or group then the panel will be positioned to the edge of the dock in the specified direction.

Relative to another Panel​

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

api.addPanel({
    id: 'panel_3',
    component: 'default',
    position: {
      referencePanel: panel2,
      direction: 'above'
    }
});

Relative to another Group​

const panel2: IDockviewPanel = api.addPanel({
    id: 'panel_2',
    component: 'default',
    position: {
      referenceGroup: 'panel_1',
      direction: 'left'
    }
});

const panel = api.addPanel({
    id: 'panel_2',
    component: 'default',
    position: {
      referenceGroup: panel2.group,
      direction: 'left'
    }
});

Relative to the container​

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

Floating​

You should specific the floating option which can be either true or an object describing the position of the floating group.

The position property of the floating object accepts combinations of top, left, bottom and right.

api.addPanel({
    id: 'panel_1',
    component: 'default',
    floating: true
});

api.addPanel({
  id: 'panel_2',
  component: 'default',
  floating: {
      position: { left: 10, top: 10 },
      width: 300,
      height: 300
  }
});

Minimum and Maximum​

You can define both minimum and maxmium widths and heights, these are persisted with layouts.

Since panels exist within groups there are occasions where these boundaries will be ignored to prevent overflow and clipping issues within the dock.

api.addPanel({
    id: 'panel_1',
    component: 'default',
    minimumWidth: 100,
    maximumWidth: 100,
    minimumHeight: 200,
    maximumHeight: 2000
});

Initial Size​

You can define an initialWidth and initialHeight. The dock will may a best attempt to obey these inputs but it may not always be possible due to the constraints of the grid.

api.addPanel({
    id: 'panel_1',
    component: 'default',
    initialWidth: 100,
    initialHeight: 100
});