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.

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

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...
};

height	Height of the component. number
length	The current number of panels. number
maximumSize	The maximum size the component can reach where size is measured in the direction of orientation provided. number
minimumSize	The minimum size the component can reach where size is measured in the direction of orientation provided. number
onDidAddView	Invoked when a view is added. Event<IView>
onDidLayoutChange	Invoked whenever any aspect of the layout changes. If listening to this event it may be worth debouncing ouputs. Event<void>
onDidLayoutFromJSON	Invoked after a layout is loaded through the fromJSON method. Event<void>
onDidRemoveView	Invoked when a view is removed. Event<IView>
orientation	The current orientation of the component. Orientation
panels	The list of current panels. ISplitviewPanel[]
width	Width of the component. number
addPanel	Add a new panel and return the created instance. <T extends object = Parameters>(options: AddSplitviewComponentOptions<T>): ISplitviewPanel
clear	Remove all panels and clear the component. (): void
focus	Focus the component. (): void
fromJSON	Deserialize a layout to built a splitivew. (data: SerializedSplitview): void
getPanel	Get the reference to a panel given it's string id. (id: string): ISplitviewPanel | undefined
layout	Layout the panel with a width and height. (width: number, height: number): void
movePanel	Move a panel given it's current and desired index. (from: number, to: number): void
removePanel	Removes an existing panel and optionally provide a Sizing method for the subsequent resize. (panel: ISplitviewPanel, sizing?: Sizing): void
toJSON	Serialize a layout (): SerializedSplitview
updateOptions	Update configuratable options. (options: SplitviewComponentUpdateOptions): void

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>;
};

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<PanelConstraintChangeEvent>
onDidDimensionsChange	Event<PanelDimensionChangeEvent>
onDidFocusChange	Event<FocusEvent>
onDidVisibilityChange	Event<VisibilityEvent>
width	The panel width in pixels number
setActive	(): void
setConstraints	(value: PanelConstraintChangeEvent2): void
setSize	(event: PanelSizeEvent): void
setVisible	(isVisible: boolean): void
updateParameters	(parameters: Parameters): 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,
});