Create a new JavaScript Heap reference for this model instance.

Add a new, independent panel to this viewer's layout, rendering the supplied [ViewerConfigUpdate] into it. The panel uses the default [perspective_client::Client] (the first passed to [Self::load]) to resolve its table. Returns the generated panel id.

Element-level config fields (settings, theme) in the argument are ignored — those are shared across the element, not per-panel.

Copy this viewer's View or Table data as CSV to the system clipboard.

Arguments

• method - The ExportMethod (serialized as a String) to use to render the data to the Clipboard.

JavaScript Examples

myDownloadButton.addEventListener("click", async () => {
    await viewer.copy();
})
Copy

Delete the internal [View] and all associated state, rendering this <perspective-viewer> unusable and freeing all associated resources. Does not delete the supplied [Table] (as this is constructed by the callee).

Calling any method on a <perspective-viewer> after [Self::delete] will throw.

JavaScript Examples

await viewer.delete();
Copy

Download this viewer's internal [View] data via a browser download event.

Arguments

• method - The ExportMethod to use to render the data to download.

JavaScript Examples

myDownloadButton.addEventListener("click", async () => {
    await viewer.download();
})
Copy

Restart this <perspective-viewer> to its initial state, before load().

Use Self::restart if you plan to call Self::load on this viewer again, or alternatively Self::delete if this viewer is no longer needed.

Exports this viewer's internal [View] as a JavaSript data, the exact type of which depends on the method but defaults to String in CSV format.

This method is only really useful for the "plugin" method, which will use the configured plugin's export (e.g. PNG for @perspective-dev/viewer-charts). Otherwise, prefer to call the equivalent method on the underlying [View] directly.

Arguments

• method - The ExportMethod to use to render the data to download.

JavaScript Examples

const data = await viewer.export("plugin");
Copy

Flush any pending modifications to this <perspective-viewer>. Since <perspective-viewer>'s API is almost entirely async, it may take some milliseconds before any user-initiated changes to the [View] affects the rendered element. If you want to make sure all pending actions have been rendered, call and await [Self::flush].

[Self::flush] will resolve immediately if there is no [Table] set.

JavaScript Examples

In this example, [Self::restore] is called without await, but the eventual render which results from this call can still be awaited by immediately awaiting [Self::flush] instead.

viewer.restore(config);
await viewer.flush();
Copy

The id of the active panel — the one the settings panel and status-bar toolbar target.

Get an Array of all of the plugin custom elements registered for this element. This may not include plugins which called [registerPlugin] after the host has rendered for the first time.

Get the underlying [Client] for this viewer (as passed to, or associated with the [Table] passed to, [PerspectiveViewerElement::load]).

Arguments

• wait_for_client - whether to wait for [PerspectiveViewerElement::load] to be called, or fail immediately if [PerspectiveViewerElement::load] has not yet been called.

JavaScript Examples

const client = await viewer.getClient();
Copy

Per-panel companion to [Self::getClient] — the named/active panel's own client (vs the element-level default client).

Get this viewer's edit port for the currently loaded [Table] (see [Table::update] for details on ports).

Per-panel companion to [Self::getEditPort] — the named/active panel's own edit port. Plugins must use this (with their slot as name) so cell edits target their own panel's [Table], not the active panel's.

Get the ids of all panels in this viewer's layout, in insertion order.

Gets a plugin Custom Element with the name field, or get the active plugin if no name is provided.

Arguments

• name - The name property of a perspective plugin Custom Element, or None for the active plugin's Custom Element.

Get render statistics. Some fields of the returned stats object are relative to the last time [PerspectiveViewerElement::getRenderStats] was called, ergo calling this method resets these fields.

JavaScript Examples

const {virtual_fps, actual_fps} = await viewer.getRenderStats();
Copy

Per-panel companion to [Self::getRenderStats].

Return a [perspective_js::JsViewWindow] for the currently selected region.

Per-panel companion to [Self::getSelection].

Get the underlying [Table] for this viewer (as passed to [PerspectiveViewerElement::load] or as the table field to [PerspectiveViewerElement::restore]).

Arguments

• wait_for_table - whether to wait for [PerspectiveViewerElement::load] to be called, or fail immediately if [PerspectiveViewerElement::load] has not yet been called.

JavaScript Examples

const table = await viewer.getTable();
Copy

Per-panel companion to [Self::getTable].

Get the underlying [View] for this viewer.

Use this method to get promgrammatic access to the [View] as currently configured by the user, for e.g. serializing as an Apache Arrow before passing to another library.

The [View] returned by this method is owned by the [PerspectiveViewerElement] and may be invalidated by [View::delete] at any time. Plugins which rely on this [View] for their [HTMLPerspectiveViewerPluginElement::draw] implementations should treat this condition as a cancellation by silently aborting on "View already deleted" errors from method calls.

JavaScript Examples

const view = await viewer.getView();
Copy

Get a copy of the [ViewConfig] for the current [View]. This is non-blocking as it does not need to access the plugin (unlike [PerspectiveViewerElement::save]), and also makes no API calls to the server (unlike [PerspectiveViewerElement::getView] followed by [View::get_config])

Returns the [ViewConfig] the currently-bound View was constructed from, so the value is consistent with what the active plugin is rendering even if a queued [Self::restore]/update_and_render has already mutated the live config in anticipation of the next draw. Falls back to the live session config when no View has yet been created (e.g., after load but before the first render).

Per-panel companion to [Self::getViewConfig].

Per-panel companion to [Self::getView].

Loads a [Client], or optionally [Table], or optionally a Javascript Promise which returns a [Client] or [Table], in this viewer.

Loading a [Client] does not render, but subsequent calls to [PerspectiveViewerElement::restore] will use this [Client] to look up the proviced table name field for the provided [ViewerConfigUpdate].

Loading a [Table] is equivalent to subsequently calling [Self::restore] with the table field set to [Table::get_name], and will render the UI in its default state when [Self::load] resolves. If you plan to call [Self::restore] anyway, prefer passing a [Client] argument to [Self::load] as it will conserve one render.

When [PerspectiveViewerElement::load] resolves, the first frame of the UI + visualization is guaranteed to have been drawn. Awaiting the result of this method in a try/catch block will capture any errors thrown during the loading process, or from the [Client] Promise itself.

[PerspectiveViewerElement::load] may also be called with a [Table], which is equivalent to:

await viewer.load(await table.get_client());
await viewer.restore({name: await table.get_name()})
Copy

If you plan to call [PerspectiveViewerElement::restore] immediately after [PerspectiveViewerElement::load] yourself, as is commonly done when loading and configuring a new <perspective-viewer>, you should use a [Client] as an argument and set the table field in the restore call as

A [Table] can be created using the @perspective-dev/client library from NPM (see [perspective_js] documentation for details).

JavaScript Examples

import perspective from "@perspective-dev/client";

const worker = await perspective.worker();
viewer.load(worker);
Copy

... or

const table = await worker.table(data, {name: "superstore"});
viewer.load(table);
Copy

Complete example:

const viewer = document.createElement("perspective-viewer");
const worker = await perspective.worker();

await worker.table("x\n1", {name: "table_one"});
await viewer.load(worker);
await viewer.restore({table: "table_one", columns: ["x"]});
Copy

... or, if you don't want to pass your own arguments to restore:

const viewer = document.createElement("perspective-viewer");
const worker = await perspective.worker();

const table = await worker.table("x\n1", {name: "table_one"});
await viewer.load(table);
Copy

Force open the settings for a particular column. Pass null to close the column settings panel. See [Self::toggleColumnSettings] for more.

Remove the panel with id name from the layout, disposing its engines (its View is deleted and its Table reference released). The last remaining panel cannot be removed (no-op). See also [Self::addPanel].

Reset the viewer's ViewerConfig to the default.

Arguments

• reset_all - If set, will clear expressions and column settings as well.

JavaScript Examples

await viewer.reset();
Copy

If this element is in an errored state, this method will clear it and re-render. Calling this method is equivalent to clicking the error reset button in the UI.

Set the available theme names available in the status bar UI.

Calling [Self::resetThemes] may cause the current theme to switch, if e.g. the new theme set does not contain the current theme.

JavaScript Examples

Restrict <perspective-viewer> theme options to only default light and dark themes, regardless of what is auto-detected from the page's CSS:

viewer.resetThemes(["Pro Light", "Pro Dark"])
Copy

Recalculate the viewer's dimensions and redraw.

Use this method to tell <perspective-viewer> its dimensions have changed when auto-size mode has been disabled via [Self::setAutoSize]. [Self::resize] resolves when the resize-initiated redraw of this element has completed.

Arguments

• options - An optional object with the following fields:
  • dimensions - An optional object {width, height} providing explicit size hints (in pixels) for the plugin container. When provided, the plugin element will be temporarily sized to these dimensions during resize, then reset.

JavaScript Examples

await viewer.resize()
await viewer.resize({dimensions: {width: 800, height: 600}})
Copy

Restores this element from a full/partial [perspective_js::JsViewConfig] (this element's user-configurable state, including the Table name).

One of the best ways to use [Self::restore] is by first configuring a <perspective-viewer> as you wish, then using either the Debug panel or "Copy" -> "config.json" from the toolbar menu to snapshot the [Self::restore] argument as JSON.

Arguments

• update - The config to restore to, as returned by [Self::save] in either "json", "string" or "arraybuffer" format.

JavaScript Examples

Loads a default plugin for the table named "superstore":

await viewer.restore({table: "superstore"});
Copy

Apply a group_by to the same viewer element, without modifying/resetting other fields - you can omit the table field, this has already been set once and is not modified:

await viewer.restore({group_by: ["State"]});
Copy

Per-panel companion to [Self::restore]: restore a single panel from a ViewerConfig, targeting the named panel, or the active panel when name is omitted. When the target is not the active panel, the shared (active-targeting) settings UI is left untouched.

Restyle all plugins from current document.

JavaScript Examples

viewer.style = "--psp--color: red";
await viewer.restyleElement();
Copy

Save this element's user-configurable state to a serialized state object, one which can be restored via the [Self::restore] method.

JavaScript Examples

Get the current group_by setting:

const {group_by} = await viewer.restore();
Copy

Reset workflow attached to an external button myResetButton:

const token = await viewer.save();
myResetButton.addEventListener("clien", async () => {
    await viewer.restore(token);
});
Copy

Per-panel companion to [Self::save]: serialize a single panel's user-configurable state (today's ViewerConfig shape) for the named panel, or the active panel when name is omitted.

Make the panel with id name the active panel, re-targeting the settings panel and status-bar toolbar (and the root's session/renderer subscriptions) to its engines.

Sets the auto-pause behavior of this component.

When true, this <perspective-viewer> will register an IntersectionObserver on itself and subsequently skip rendering whenever its viewport visibility changes. Auto-pause is enabled by default.

Arguments

• autopause Whether to enable auto-pause behavior or not.

JavaScript Examples

Disable auto-size behavior:

viewer.setAutoPause(false);
Copy

Sets the auto-size behavior of this component.

When true, this <perspective-viewer> will register a ResizeObserver on itself and call [Self::resize] whenever its own dimensions change. However, when embedded in a larger application context, you may want to call [Self::resize] manually to avoid over-rendering; in this case auto-sizing can be disabled via this method. Auto-size behavior is enabled by default.

Arguments

• autosize - Whether to enable auto-size behavior or not.

JavaScript Examples

Disable auto-size behavior:

viewer.setAutoSize(false);
Copy

Set the selection [perspective_js::JsViewWindow] for this element.

Per-panel companion to [Self::setSelection]. Selection is per-Renderer state, so recording it on the source panel (rather than whichever panel is active) is what attributes master/detail and toolbar selection actions to the panel the user actually selected in.

Determines the render throttling behavior. Can be an integer, for millisecond window to throttle render event; or, if None, adaptive throttling will be calculated from the measured render time of the last 5 frames.

Arguments

• throttle - The throttle rate in milliseconds (f64), or None for adaptive throttling.

JavaScript Examples

Only draws at most 1 frame/sec:

viewer.setThrottle(1000);
Copy

Asynchronously opens the column settings for a specific column. When finished, the <perspective-viewer> element will emit a "perspective-toggle-column-settings" CustomEvent. The event's details property has two fields: {open: bool, column_name?: string}. The CustomEvent is also fired whenever the user toggles the sidebar manually.

Per-panel companion to [Self::toggleColumnSettings]. The column settings sidebar is bound to the active panel, so opening a non-active panel's column first activates that panel (exactly like clicking its tab), then opens the column — resolved against that panel's schema. Toggle semantics (close when already open) apply only when the panel was already active; activating a different panel always opens, even if a same-named column of the previously-active panel was showing.

Toggle (or force) the config panel open/closed.

Arguments

• force - Force the state of the panel open or closed, or None to toggle.

JavaScript Examples

await viewer.toggleConfig();
Copy