Styling Widgets

Themes

The deck.gl widget system provides support for themes. The primary goal of widget themes is to allow applications to select and switch between dark and light modes, so that widgets match the overall look of the application.

Themes are global for a deck instance, i.e they apply to all widgets in all views. Even though widgets can be placed in different views, it is not possible to specify different themes for different views.

Default themes are provided for dark and light mode, however themes can be customized to offer applications some additional control of styling, see below.

Built-In Themes

Preview	Theme
	import {DarkTheme} from '@deck.gl/widgets';
	import {LightTheme} from '@deck.gl/widgets';
	import {DarkGlassTheme} from '@deck.gl/widgets';
	import {LightGlassTheme} from '@deck.gl/widgets';

Setting the Theme

For applications that already implement theme switching in the non-deck parts of their UI, it is expected that deck.gl themes will be updated programmatically when the ambient UI theme is switched.

import {DarkTheme, LightTheme} from '@deck.gl/widgets';

new Deck({
  style: mode === 'dark' ? DarkTheme : LightTheme
})

For minimal applications that don't implement a UI outside of deck.gl, a ThemeWidget is provided that let users switch between dark and light mode themes.

import {ThemeWidget} from '@deck.gl/widgets';

new Deck({
  widgets=[new ThemeWidget()]
});

Customizing Themes

New themes can be defined programmatically or via CSS.

deck.gl uses CSS variables to define themes. This section provides guidance on how to theme and style widgets at different levels of specificity.

This lets application customize the appearance of widgets beyond the default light and dark mode themes.

Customizing themes in TypeScript

import type {Theme} from '@deck.gl/widgets';
import {DarkTheme} from '@deck.gl/widgets';

const CustomTheme = {
  ...DarkTheme,
  ...
} satisfies Theme;

Customizing themes in CSS

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.

Widget-type specific styling

The CSS variables for a specific type of widget using the .deck-widget-[type] selector.

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

Instance-specific Styling

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 list of these variables, their expected types, and default values.

Additionally, refer to each widget's API reference for variables specific to that widget.

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

Refer to each widget's API reference for icon variable names.

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.

widget-icon-overrides.css

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

Icon Recommendations

If possible, make the new icon re-colorable, resizable, and replaceable with CSS.

• Give the SVG a black fill for color masking
• Convert your SVG to CSS with a convertor like this.
• Remove height and width attributes (widget sets to 100%)
• Add css to the stylesheet like this
• Use a unique CSS class name and variable for the icon.

For consistency with the other icons in the core set, you can use Google Symbols.