Splitview

Introduction

A Splitview is a collection of resizable horizontally or vertically stacked panels.

Simple Splitview example

import {
    ISplitviewPanelProps,
    Orientation,
    SplitviewReact,
    SplitviewReadyEvent,
} from 'dockview';

const components = {
    default: (props: ISplitviewPanelProps<{ title: string }>) => {
        return <div style={{ padding: '20px' }}>{props.params.title}</div>;
    },
};

export const SimpleSplitview = () => {
    const onReady = (event: SplitviewReadyEvent) => {
        event.api.addPanel({
            id: 'panel_1',
            component: 'default',
            params: {
                title: 'Panel 1',
            },
        });

        event.api.addPanel({
            id: 'panel_2',
            component: 'default',
            params: {
                title: 'Panel 2',
            },
        });

        event.api.addPanel({
            id: 'panel_3',
            component: 'default',
            params: {
                title: 'Panel 3',
            },
        });
    };

    return (
        <SplitviewReact
            components={components}
            onReady={onReady}
            orientation={Orientation.HORIZONTAL}
            className="dockview-theme-abyss"
        />
    );
};

SplitviewReact Component

You can create a Splitview through the use of the ReactSplitview component.

import { ReactSplitview } from 'dockview';

Using the onReady prop you can access to the component api and add panels either through deserialization or the individual addition of panels.

Property	Type	Optional	Default	Description
onReady	(event: SplitviewReadyEvent) => void	No		Function
components	Record<string, ISplitviewPanelProps>	No		Panel renderers
orientation	Orientation	Yes	Orientation.HORIZONTAL	Orientation of the Splitview
proportionalLayout	boolean	Yes	true	See Proportional layout
hideBorders	boolean	Yes	false	Hide the borders between panels
className	string	Yes	''	Attaches a classname
disableAutoResizing	boolean	Yes	false	See Auto Resizing

Splitview API

The Splitview API is exposed both at the onReady event and on each panel through props.containerApi. Through this API you can control general features of the component and access all added panels.

Splitview API via Panel component

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

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

Splitview API via the onReady callback

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

Property	Type	Description
height	number	Component pixel height
width	number	Component pixel width
minimumSize	number	The sum of the minimumSize property for each panel
maximumSize	number	The sum of the maximumSize property for each panel
length	number	Number of panels
panels	ISplitviewPanel[]	All panels
onDidLayoutChange	Event<void>	Fires on layout change
onDidLayoutFromJSON	Event<void>	Fires of layout change caused by a fromJSON deserialization call
onDidAddView	Event<IView>	Fires when a view is added
onDidRemoveView	Event<IView>	Fires when a view is removed
addPanel	addPanel(options: AddSplitviewComponentOptions): ISplitviewPanel
removePanel	(panel: ISplitviewPanel, sizing?: Sizing): void
getPanel	(id:string): ISplitviewPanel \| undefined
movePanel	(from: number, to: number): void
updateOptions	(options: SplitviewComponentUpdateOptions): void
focus	(): void	Focus the active panel, if exists
layout	(width: number, height:number): void	See Auto Resizing
fromJSON	(data: SerializedSplitview): void	Serialization
toJSON	(): SerializedSplitview	Serialization
clear	(): void	Clears the current layout

Splitview Panel API

The Splitview panel API is exposed on each panel containing actions and variables specific to that panel.

Splitview panel API via Panel component

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

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

Property	Type	Description
id	string	Panel id
isFocused	boolean	Is panel focsed
isActive	boolean	Is panel active
isVisible	boolean	Is panel visible
width	number	Panel width
height	number	Panel height
onDidDimensionsChange	Event<PanelDimensionChangeEvent>	Fires when panel dimensions change
onDidFocusChange	Event<FocusEvent>	Fire when panel is focused and blurred
onDidVisibilityChange	Event<VisibilityEvent>	Fires when the panels visiblity property is changed (see Panel Visibility)
onDidActiveChange	Event<ActiveEvent>	Fires when the panels active property is changed (see Active Panel)
onDidConstraintsChange	onDidConstraintsChange: Event<PanelConstraintChangeEvent>	Fires when the panels size contrainsts change (see Panel Constraints)
setVisible	(isVisible: boolean): void
setActive	(): void
setConstraints	(value: PanelConstraintChangeEvent2): void;
setSize	(event: PanelSizeEvent): void

Advanced Features

Listed below are some functionalities avalaible through both the panel and component APIs. The live demo shows examples of these in real-time.

Visibility

A panels visibility can be controlled and monitored through the following code. A panel with visibility set to false will remain as a part of the components list of panels but will not be rendered.

const disposable = props.api.onDidVisibilityChange(({ isVisible }) => {
    //
});

api.setVisible(true);

Active

Only one panel in the splitview can be the active panel at any one time. Setting a panel as active will set all the others as inactive. A focused panel is always the active panel but an active panel is not always focused.

const disposable = props.api.onDidActiveChange(({ isActive }) => {
    //
});

api.setActive();

Contraints

When adding a panel you can specify pixel size contraints

event.api.addPanel({
    id: 'panel_3',
    component: 'default',
    minimumSize: 100,
    maximumSize: 1000,
});

These contraints can be updated throughout the lifecycle of the splitview using the panel API

props.api.onDidConstraintsChange(({ maximumSize, minimumSize }) => {
    //
});

api.setConstraints({
    maximumSize: 200,
    minimumSize: 400,
});