Skip to main content

Adding panels

Panels are the content units of a Dockview layout. addPanel creates one from a registered component and controls where it opens, its title, tab renderer, initial parameters, size and floating state.

Panels can be added through the Dockview API.

addPanel
Add a panel and return the created object.
addPanel(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 Registering panels 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 Dockview 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 specify 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 Dockview container in the specified direction.

Direction
A direction in which a panel can be moved or placed relative to another panel.
type Direction = 'within' | 'below' | 'above' | 'right' | 'left'

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',
    },
});

api.addPanel({
    id: 'panel_4',
    component: 'default',
    position: {
        referencePanel: panel2,
        index: 2, // optionally specify which index to add the panel at
    },
});

Relative to another group​

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

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

api.addPanel({
    id: 'panel_3',
    component: 'default',
    position: {
        referenceGroup: panel2.group,
        index: 2, // optionally specify which index to add the panel at
    },
});

Relative to the container​

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

Floating​

You should specify 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 maximum 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 Dockview.

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

Initial size​

You can define an initialWidth and initialHeight. Dockview will make 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,
});

See also​