Theming

Theming is supported in perspective-viewer and its accompanying plugins. A number of themes come bundled with perspective-viewer; you can import any of these themes directly into your app, and the perspective-viewers will be themed accordingly:

// Themes based on Thought Merchants's Prospective design
import "@perspective-dev/viewer/dist/css/pro.css";
import "@perspective-dev/viewer/dist/css/pro-dark.css";

// Other themes
import "@perspective-dev/viewer/dist/css/solarized.css";
import "@perspective-dev/viewer/dist/css/solarized-dark.css";
import "@perspective-dev/viewer/dist/css/monokai.css";
import "@perspective-dev/viewer/dist/css/vaporwave.css";

Alternatively, you may use themes.css, which bundles all default themes

import "@perspective-dev/viewer/dist/css/themes.css";

If you choose not to bundle the themes yourself, they are available through CDN. These can be directly linked in your HTML file:

<link
    rel="stylesheet"
    crossorigin="anonymous"
    href="https://cdn.jsdelivr.net/npm/@perspective-dev/viewer/dist/css/pro.css"
/>

Note the crossorigin="anonymous" attribute. When including a theme from a cross-origin context, this attribute may be required to allow <perspective-viewer> to detect the theme. If this fails, additional themes are added to the document after <perspective-viewer> init, or for any other reason theme auto-detection fails, you may manually inform <perspective-viewer> of the available theme names with the .resetThemes() method.

// re-auto-detect themes
viewer.resetThemes();

// Set available themes explicitly (they still must be imported as CSS!)
viewer.resetThemes(["Pro Light", "Pro Dark"]);

<perspective-viewer> will default to the first loaded theme when initialized. You may override this via .restore(), or provide an initial theme by setting the theme attribute:

<perspective-viewer theme="Pro Light"></perspective-viewer>

or

const viewer = document.querySelector("perspective-viewer");
await viewer.restore({ theme: "Pro Dark" });

Custom Themes

The best way to write a new theme is to fork and modify an existing theme, which are just collections of regular CSS variables (no preprocessor is required, though Perspective’s own themes use one). <perspective-viewer> is not “themed” by default and will lack icons and label text in addition to colors and fonts, so starting from an empty theme forces you to define every theme-able variable to get a functional UI.

Icons and Translation

UI icons are defined by CSS variables provided by @perspective-dev/viewer/dist/css/icons.css. These variables must be defined for the UI icons to work - there are no default icons without a theme.

UI text is also defined in CSS variables provided by @perspective-dev/viewer/dist/css/intl.css, and has identical import requirements. Some example definitions (automatically-translated sans-editing) can be found @perspective-dev/viewer/dist/css/intl/ folder.

Importing the pre-built themes.css stylesheet as well as a custom theme will define Icons and Translation globally as a side-effect. You can still customize icons in this mode with rules (of the appropriate specificity), but if you do not still remember to define these variables yourself, your theme will not work without the base themes.css package available.