Skip to main content

@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:

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/dist/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/widgets@^9.0.0/dist/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

NameTypeDefault
--button-sizeDimension28px
--button-border-radiusDimension8px
--widget-marginDimension12px

Color

NameTypeDefault
--button-backgroundColor#fff
--button-strokeColorrgba(255, 255, 255, 0.3)
--button-inner-strokeBorderunset
--button-shadowBox Shadow0px 0px 8px 0px rgba(0, 0, 0, 0.25)
--button-backdrop-filterBackdrop Filterunset
--button-icon-idleColorrgba(97, 97, 102, 1)
--button-icon-hoverColorrgba(24, 24, 26, 1)
--icon-compass-north-colorColor#F05C44
--icon-compass-south-colorColor#C2C2CC

Icon

NameTypeDefault
--icon-fullscreen-enterSVG Data UrlMaterial Symbol Fullscreen
--icon-fullscreen-enterSVG Data UrlMaterial Symbol Fullscreen Exit
--icon-zoom-inSVG Data UrlMaterial Symbol Add
--icon-zoom-outSVG Data UrlMaterial 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:
  1. Icon Replacement:
  • Use CSS variables, such as --icon-fullscreen-enter, to replace the default icons with your customized ones.
  1. 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;
}