Skip to main content

Rendering Panels

Rendering type is an important consideration when creating your application and whether your panels should be destroyed when hidden.

If you are looking for information on how to render iframes in Dockview please go the the iframes section.

When a panel is selected all other panels in that group are not visible. The API does expose methods to determine whether your panel is visible or not and the panel instance only ever destroyed when removed however the question still remains, what to do with the partial DOM tree that makes up your panel and there are two options the dock can take:

  1. (onlyWhenVisible) Remove the element from the DOM tree to make space for the new panel.

This will cause the element to loss any DOM-specific state such as scrollbar position and if you measure the size of any elements during this time you will mostly like see both a width and height of 0px, this is also true for any active ResizeObservers.

api.addPanel({
    id: 'my_unique_panel_id',
    component: 'my_component',
    renderer: 'always'
});
  1. (always) Keep the DOM tree alive but hide it in order to allow the select panels content to show.

This approach will maintain any DOM-sepcific state you had and is essential if you require the native scrollbar position to be preserved.

api.addPanel({
    id: 'my_unique_panel_id',
    component: 'my_component',
    renderer: 'onlyWhenVisible'
});

Both are valid use-cases therefore the dock allows you to choose your rendering mode, the default however is the first option since this is the most memory efficient solution.

You can change the defaultRenderer in the Dock Options.

The panel instance is only ever destroyed when it is removed from the dock allowing you to still run code associated with the panel when it is not visible. The renderer only affects what happens to the DOM element.

Choose a Render Mode​

api.addPanel({
    id: 'my_unique_panel_id',
    component: 'my_component',
    renderer: 'always'
});

api.addPanel({
    id: 'my_unique_panel_id',
    component: 'my_component',
    renderer: 'onlyWhenVisible'
});

Live Example​

When a panel uses always render mode, the panel component instance is kept alive even when the panel is not visible. This means reactive state, subscriptions, and lifecycle hooks continue to run in the background.

You can listen to onDidVisibilityChange to gate expensive work, or conditionally render inner content only when the panel is visible.

Toggling the checkbox in the live example shows the panel component being destroyed when hidden and re-created when it becomes visible again.