JSPM

dockview

1.2.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 16432
  • Score
    100M100P100Q132874F
  • License MIT

Zero dependency layout manager supporting tabs, grids and splitviews with ReactJS support

Package Exports

  • dockview
  • dockview/dist/cjs/index.js
  • dockview/dist/esm/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (dockview) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

dockview

Zero dependency layout manager supporting tabs, grids and splitviews with ReactJS support

npm version CI Build Coverage Quality Gate Status Bundle Phobia

A zero dependency layout manager based on the layering of splitview with support for ReactJS components, written in TypeScript.

Want to inspect the latest deployment? Go to https://unpkg.com/browse/dockview@latest/

Features

  • Simple splitviews, nested splitviews (i.e. gridviews) supporting full layout managment with dockable and tabular views
  • Extensive API support at the component level and view level
  • Themable and customizable
  • Serialization / deserialization support
  • Tabular docking and Drag and Drop support
  • Documentation and examples

Table of contents

This project was inspired by many popular IDE editors. Some parts of the core resizable panelling are inspired by code found in the VSCode codebase, splitview and gridview.

Quick start

Dockview has a peer dependency on react >= 16.8.0 and react-dom >= 16.8.0. You can install dockview from npm.

npm install --save dockview

Within your project you must import or reference the stylesheet at dockview/dist/styles/dockview.css. For example:

@import '~dockview/dist/styles/dockview.css';

You should also attach a dockview theme to an element containing your components. For example:

<body classname="dockview-theme-dark"></body>

Demonstrated below is a high level example of a DockviewReact component. You can follow a similar pattern for GridviewReact, SplitviewReact and PaneviewReact components too, see examples for more.

import {
    DockviewReact,
    DockviewReadyEvent,
    PanelCollection,
    IDockviewPanelProps,
    IDockviewPanelHeaderProps,
} from 'dockview';

const components: PanelCollection<IDockviewPanelProps> = {
    default: (props: IDockviewPanelProps<{ someProps: string }>) => {
        return <div>{props.params.someProps}</div>;
    },
};

const headers: PanelCollection<IDockviewPanelHeaderProps> = {
    customTab: (props: IDockviewPanelHeaderProps) => {
        return (
            <div>
                <span>{props.api.title}</span>
                <span onClick={() => props.api.close()}>{'[x]'}</span>
            </div>
        );
    },
};

const Component = () => {
    const onReady = (event: DockviewReadyEvent) => {
        event.api.addPanel({
            id: 'panel1',
            component: 'default',
            params: {
                someProps: 'Hello',
            },
        });
        event.api.addPanel({
            id: 'panel2',
            component: 'default',
            params: {
                someProps: 'World',
            },
            position: { referencePanel: 'panel1', direction: 'below' },
        });
    };

    return (
        <DockviewReact
            components={components}
            tabComponents={headers}
            onReady={onReady}
        />
    );
};

Specifically for DockviewReact there exists higher-order components to encapsulate both the tab and contents into one logical component for the user making state sharing between the two simple, which is an optional feature.

const components: PanelCollection<IDockviewPanelProps> = {
    default: (props: IDockviewPanelProps<{ someProps: string }>) => {
        return <div>{props.params.someProps}</div>;
    },
    fancy: (props: IDockviewPanelProps) => {
        const close = () => props.api.close();
        return (
            <DockviewComponents.Panel>
                <DockviewComponents.Tab>
                    <div>
                        <span>{props.api.title}</span>
                        <span onClick={close}>{'Close'}</span>
                    </div>
                </DockviewComponents.Tab>
                <DockviewComponents.Content>
                    <div>{'Hello world'}</div>
                </DockviewComponents.Content>
            </DockviewComponents.Panel>
        );
    },
};

Sandbox examples

Serializated layouts

All view components support the methods toJSON(), fromJSON(...) and onDidLayoutChange().

See example here.

Drag and drop

Both DockviewReact and PaneviewReact support drag and drop functionality out of the box.

  • DockviewReact allows tabs to be repositioned using drag and drop.
  • PaneviewReact allows the repositioning of views using drag and drop on the header section.

You can use the utility methods getPaneData and getPanelData to manually extract the data transfer metadata associated with an active drag and drop event for either of the above components.

import {
    getPaneData,
    getPanelData,
    PanelTransfer,
    PaneTransfer,
} from 'dockview';

const panelData: PanelTransfer | undefined = getPanelData();

if (panelData) {
    // DockviewReact: data transfer metadata associated with the active drag and drop event
    const { viewId, groupId, panelId } = panelData; // deconstructed object
}

const paneData: PaneTransfer | undefined = getPaneData();

if (paneData) {
    // PaneviewReact: data transfer metadata associated with the active drag and drop event
    const { viewId, paneId } = paneData; // deconstructed object
}

You can also intercept custom drag and drop events allowing dockview components to interact with and react to external drag events. PaneviewReact supports the method onDidDrop and DockviewReact supports the methods onDidDrop and showDndOverlay.

Theming

The theme can be customized using the below set of CSS properties. You can find the built in themes here which could be used as an example to extend upon or build your own theme.

CSS Property Description
General
--dv-active-sash-color The background color a dividing sash during an interaction
--dv-separator-border The color of the seperator between panels
Paneview
--dv-paneview-header-border-color -
--dv-paneview-active-outline-color The primary accent color, used for example to highlight the active panel in Paneviews
Dockview -> Dragging
--dv-drag-over-background-color The overlay color applied to a group when a moving tab is dragged over
Dockview -> Tabs container
--dv-tabs-and-actions-container-font-size -
--dv-tabs-and-actions-container-height Default tab height
--dv-tabs-and-actions-container-background-color -
--dv-tabs-container-scrollbar-color -
--dv-group-view-background-color -
Dockview -> Tabs (see dockviewComponent.scss)
--dv-activegroup-visiblepanel-tab-background-color The background color of the tab for the visible panel in the active group
--dv-activegroup-hiddenpanel-tab-background-color The background color of the tab for the hidden panel/s in the active group
--dv-inactivegroup-visiblepanel-tab-background-color The background color of the tab for the visible panel in groups other than the active group
--dv-inactivegroup-hiddenpanel-tab-background-color The background color of the tab for the hidden panel/s in groups other than the active group
--dv-activegroup-visiblepanel-tab-color The color of the tab for the visible panel in the active group
--dv-activegroup-hiddenpanel-tab-color The color of the tab for the hidden panel/s in the active group
--dv-inactivegroup-visiblepanel-tab-color The color of the tab for the visible panel in groups other than the active group
--dv-inactivegroup-hiddenpanel-tab-color The color of the tab for the hidden panel/s in groups other than the active group
--dv-tab-divider-color -
--dv-tab-close-icon Default tab close icon

Performance

Consider using React.lazy(...) to defer the importing of your panels until they are required. This has the potential to reduce the initial import cost when your application starts.

FAQ

Q: Can I use this library without React?

A: In theory, yes. The library is written in plain-old JS and the parts written in ReactJS are merely wrappers around the plain-old JS components. Currently everything is published as one package though so maybe that's something to change in the future.

Q: Can I use this library with AngularJS/Vue.js or any other arbitrarily named JavaScript library/framework?

A: Yes but with some extra work. Dockview is written in plain-old JS so you can either interact directly with the plain-old JS components or create a wrapper using your prefered library/framework. The React wrapper may give some ideas on how this wrapper implementation could be done for other libraries/frameworks. Maybe that's something to change in the future.