Skip to content

Latest commit

 

History

History
149 lines (109 loc) · 6.1 KB

overview.md

File metadata and controls

149 lines (109 loc) · 6.1 KB
Raw

@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'}})

To style hyphenated CSS properties (e.g. background-color, border-color, etc.), use the camelCase equivalent.

new FullscreenWidget({ style: {'backgroundColor': '#fff'}})

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:
  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;
}