@deck.gl/widgets

Widgets are UI components around the WebGL2/WebGPU canvas to offer controls and information for a better user experience.

This module contains the following widgets:

• FullscreenWidget
• ZoomWidget
• CompassWidget

Installation

Install from NPM

npm install deck.gl
# or
npm install @deck.gl/core @deck.gl/widgets

import {FullscreenWidget} from '@deck.gl/widgets';
import '@deck.gl/widgets/stylesheet.css';

new FullscreenWidget({});

Include the Standalone Bundle

<script src="https://unpkg.com/deck.gl@^9.0.0/dist.min.js"></script>
<link src="https://unpkg.com/deck.gl@^9.0.0/widgets/stylesheet.css" rel='stylesheet' />
<!-- or -->
<script src="https://unpkg.com/@deck.gl/core@^9.0.0/dist.min.js"></script>
<script src="https://unpkg.com/@deck.gl/widgets@^9.0.0/dist.min.js"></script>
<link src="https://unpkg.com/deck.gl@^9.0.0/widgets/stylesheet.css" rel='stylesheet' />

new deck.FullscreenWidget({});

CSS Theming

Customizing the appearance of widgets can be achieved using CSS variables. This section provides guidance on how to theme widgets at different levels of specificity.

Global Theming

Apply to all widgets with the .deck-widget selector.

.deck-widget {
    --button-size: 48px;
}

Note: While variables can be globally applied using the :root selector, ensuring their availability throughout the entire document, this method is not recommended. Applying variables globally can lead to naming conflicts, especially in larger projects or when integrating with other libraries.

Type-specific Theming

Theme a specific type of widget using the .deck-widget-[type] selector.

.deck-widget-fullscreen {
    --button-size: 48px;
}

Instance-specific Theming

Apply styles to a single instance of a widget using inline styles.

new FullscreenWidget({ style: {'--button-size': '48px'}})

Custom Class Theming

Define a custom class with your desired styles and apply it to a widget.

.my-class {
    --button-size: 48px;
}

new FullscreenWidget({ className: 'my-class'})

Customizable CSS Variables

We've provided a set of CSS variables to make styling UI Widgets more convenient. These variables allow for customization of widget sizes, colors, and other properties. Below is a comprehensive list of these variables, their expected types, and default values:

Size

Name	Type	Default
--button-size	Dimension	28px
--button-border-radius	Dimension	8px
--widget-margin	Dimension	12px

Color

Name	Type	Default
--button-background	Color	#fff
--button-stroke	Color	rgba(255, 255, 255, 0.3)
--button-inner-stroke	Border	unset
--button-shadow	Box Shadow	0px 0px 8px 0px rgba(0, 0, 0, 0.25)
--button-backdrop-filter	Backdrop Filter	unset
--button-icon-idle	Color	rgba(97, 97, 102, 1)
--button-icon-hover	Color	rgba(24, 24, 26, 1)
--icon-compass-north-color	Color	#F05C44
--icon-compass-south-color	Color	#C2C2CC

Icon

Name	Type	Default
--icon-fullscreen-enter	SVG Data Url	Material Symbol Fullscreen
--icon-fullscreen-enter	SVG Data Url	Material Symbol Fullscreen Exit
--icon-zoom-in	SVG Data Url	Material Symbol Add
--icon-zoom-out	SVG Data Url	Material Symbol Remove

Replacing Icons

Users can to customize icons to better align with their design preferences or branding. This section provides a step-by-step guide on how to replace and customize these icons.

1. Prepare Your Icons:

• Ensure your icons are available as SVG Data Url. These will be used for a CSS mask-image.

2. Icon Replacement:

• Use CSS variables, such as --icon-fullscreen-enter, to replace the default icons with your customized ones.

3. Color Customization:

• The original color embedded in your SVG will be disregarded. However, it's crucial that the SVG isn't transparent.
• Customize the color of your icon using the appropriate CSS variable, such as --button-icon-idle.

Example:

.deck-widget {
    --icon-fullscreen-enter: url('path_to_your_svg_icon.svg');
    --button-icon-idle: blue;
}