Skip to main content

Theming

Additional Developer Resources
Public beta for Mapbox Search JS
Mapbox Search JS is in public beta. During the public beta phase, frameworks may be subject to potential changes as they stabilize.

This page includes reference documentation for types relates to the Control Theme API, used to configure custom styling, icons, and images for Mapbox Search JS Web elements.

Options and Type Definitions

Theme

The Control Theme API is a way to apply your own design system to Mapbox Search JS Web elements.

Control themes use a combination of CSS variables, custom scoped CSS, and SVG icons.

Type

Object

Properties

cssText(string): Optional CSS text to be inserted into Scoped CSS elements. As such, any CSS will not interact with the rest of the page.

TODO: Class names are element-specific and have yet to be standardized. Breaking changes are likely and will be flagged in CHANGELOG.md.

    icons(ThemeIcons): SVG icon overrides to be applied to the control.
      images(ThemeImages): Raster image URLs to be applied to the control.
        variables(ThemeVariables): CSS variables to be applied to the control.

          Example

          const theme = {
            variables: {
              fontFamily: 'Avenir, sans-serif',
              unit: '14px',
              padding: '0.5em',
              borderRadius: '0',
              boxShadow: '0 0 0 1px silver',
            }
          };

          autofill({ theme });
          Was this section on Theme helpful?

          ThemeVariables

          ThemeVariables are a collection of CSS variables that style Control Theme API elements.

          Type

          Object

          Properties

          border(string)
            border(string): Border color of elements such as modals and listboxes.

            Analogous to CSS border.

              borderRadius(string): Border radius of elements such as modals and listboxes.

              Analogous to CSS border-radius.

                boxShadow(string): Box shadow of elements such as modals and listboxes.

                Analogous to CSS box-shadow.

                  colorBackdrop(string): Backdrop color of body content behind modals.

                  Analogous to CSS color. Default: black with alpha value

                    colorBackground(string): Background color for elements such as modals and listboxes.

                    Analogous to CSS color. Default: white

                      colorBackgroundActive(string): Background color for items on press.

                      Analogous to CSS color. Default: dark gray

                        colorBackgroundHover(string): Background color for items on hover.

                        Analogous to CSS color. Default: light gray

                          colorPrimary(string): Color of the primary accent color.

                          Analogous to CSS color. Default: variant of blue

                            colorSecondary(string): Color of the secondary accent color.

                            Analogous to CSS color. Default: blue-gray

                              colorText(string)
                                colorText(string): Color of the primary text.

                                Analogous to CSS color. Default: dark gray

                                  curve(string): The timing function to use for listbox animations.

                                  Analogous to CSS <easing-function>. Default: ease-out

                                    duration(string)
                                      duration(string): The duration to use for listbox animations.

                                      Analogous to CSS <time>. Default: 150ms

                                        fontFamily(string): Font family.

                                        Analogous to CSS font-family. Default: Sans-serif system font stack

                                          fontWeight(string): Font weight for body text.

                                          Analogous to CSS font-weight. Default: normal

                                            fontWeightBold(string): Font weight for headings and item titles.

                                            Analogous to CSS font-weight. Default: bold

                                              fontWeightSemibold(string): Font weight for subheadings.

                                              Analogous to CSS font-weight. Default: 600

                                                lineHeight(string)
                                                  lineHeight(string): Line height.

                                                  Analogous to CSS line-height. Default: 1.2

                                                    minWidth(string): Minimum width of elements such as modals and listboxes.

                                                    Analogous to CSS <length>.

                                                      padding(string): Padding of items in an element.

                                                      Analogous to CSS <length>.

                                                        paddingFooterLabel(string): Padding of powered by mapbox label in footer of search listbox.

                                                        Analogous to CSS <length>.

                                                          paddingModal(string): Padding for contents of modal elements.

                                                          Analogous to CSS <length>.

                                                            spacing(string): Spacing between items in an element.

                                                            Analogous to CSS <length>.

                                                              unit((string | Expression))
                                                                unit((string | Expression)): Unit is the base font size and can be referenced in other variables as multiples of 1em .

                                                                Analogous to font-size.

                                                                  unitHeader((string | Expression)): Unit header is a derivative of unit and is used for modal headers.

                                                                  Analogous to font-size.

                                                                    Was this section on ThemeVariables helpful?

                                                                    ThemeIcons

                                                                    ThemeIcons are SVG icons that are used in Control Theme API elements.

                                                                    Roughly, icon names and their defaults are the same as Mapbox's Assembly.

                                                                    Values must be valid SVG plain-text. Unless otherwise noted, icons should be 18px in size and have appropriate dimensions set.

                                                                    Icons can also be filled with 'currentColor'.

                                                                    Type

                                                                    Object

                                                                    Properties

                                                                    addressMarker(string): Icon for address results in search list box.
                                                                      close(string): Close icon.
                                                                        marker(string): Icon for map markers. Can be any size.
                                                                          question(string): Question mark icon.
                                                                            search(string): Icon for Search Box input.
                                                                              street(string): Icon for streets results in search list box.

                                                                                Example

                                                                                const icons = {
                                                                                  close: `
                                                                                <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
                                                                                <svg viewBox="0 0 18 18" xmlns="http://www.w3.org/2000/svg">
                                                                                  <path fill-rule="evenodd" clip-rule="evenodd" d="M3.79289 3.79289C4.18342 3.40237 4.81658 3.40237 5.20711 3.79289L9 7.58579L12.7929 3.79289C13.1834 3.40237 13.8166 3.40237 14.2071 3.79289C14.5976 4.18342 14.5976 4.81658 14.2071 5.20711L10.4142 9L14.2071 12.7929C14.5976 13.1834 14.5976 13.8166 14.2071 14.2071C13.8166 14.5976 13.1834 14.5976 12.7929 14.2071L9 10.4142L5.20711 14.2071C4.81658 14.5976 4.18342 14.5976 3.79289 14.2071C3.40237 13.8166 3.40237 13.1834 3.79289 12.7929L7.58579 9L3.79289 5.20711C3.40237 4.81658 3.40237 4.18342 3.79289 3.79289Z" fill="currentColor"/>
                                                                                </svg>
                                                                                `
                                                                                }
                                                                                Was this section on ThemeIcons helpful?

                                                                                ThemeImages

                                                                                ThemeImages are raster images that are used in Control Theme API elements.

                                                                                There are currently only two images, "toggle default" and "toggle satellite," which specify images for a Map/Satellite toggle button.

                                                                                Values must be valid URLs accessible by the expected browser environment. Data URLs and Blob URLs are also supported.

                                                                                Type

                                                                                Object

                                                                                Properties

                                                                                styleToggleDefault(string): Image for the "Map" of the Map/Satellite toggle button.
                                                                                  styleToggleSatellite(string): Image for the "Satellite" of the Map/Satellite toggle button.
                                                                                    Was this section on ThemeImages helpful?

                                                                                    Expression

                                                                                    Currently, the only expression supported is ['mobile', mobile_value, tablet_and_desktop_value].

                                                                                    Type

                                                                                    ["mobile", string, string]
                                                                                    Was this section on Expression helpful?
                                                                                    Additional Developer Resources
                                                                                    Was this page helpful?