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.
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.
| Name | Description |
|---|---|
| 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. |
const theme = {
variables: {
fontFamily: 'Avenir, sans-serif',
unit: '14px',
padding: '0.5em',
borderRadius: '0',
boxShadow: '0 0 0 1px silver',
}
};
autofill({ theme });ThemeVariables are a collection of CSS variables that style Control Theme API
elements.
| Name | Description |
|---|---|
| border string | |
| border string | Border color of elements such as modals and listboxes.
Analogous to CSS |
| borderRadius string | Border radius of elements such as modals and listboxes.
Analogous to CSS |
| boxShadow string | Box shadow of elements such as modals and listboxes.
Analogous to CSS |
| colorBackdrop string | Backdrop color of body content behind modals.
Analogous to CSS |
| colorBackground string | Background color for elements such as modals and listboxes.
Analogous to CSS |
| colorBackgroundActive string | Background color for items on press.
Analogous to CSS |
| colorBackgroundHover string | Background color for items on hover.
Analogous to CSS |
| colorPrimary string | Color of the primary accent color.
Analogous to CSS |
| colorSecondary string | Color of the secondary accent color.
Analogous to CSS |
| colorText string | |
| colorText string | Color of the primary text.
Analogous to CSS |
| curve string | The timing function to use for listbox animations.
Analogous to CSS |
| duration string | |
| duration string | The duration to use for listbox animations.
Analogous to CSS |
| fontFamily string | Font family.
Analogous to CSS |
| fontWeight string | Font weight for body text.
Analogous to CSS |
| fontWeightBold string | Font weight for headings and item titles.
Analogous to CSS |
| fontWeightSemibold string | Font weight for subheadings.
Analogous to CSS |
| lineHeight string | |
| lineHeight string | Line height.
Analogous to CSS |
| minWidth string | Minimum width of elements such as modals and listboxes.
Analogous to CSS |
| padding string | Padding of items in an element.
Analogous to CSS |
| paddingFooterLabel string | Padding of powered by mapbox label in footer of search listbox.
Analogous to CSS |
| paddingModal string | Padding for contents of modal elements.
Analogous to CSS |
| spacing string | Spacing between items in an element.
Analogous to CSS |
| 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 |
| unitHeader (string | Expression) | Unit header is a derivative of
unit
and is used for modal headers.
Analogous to |
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'.
| Name | Description |
|---|---|
| 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. |
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>
`
}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.
| Name | Description |
|---|---|
| styleToggleDefault string | Image for the "Map" of the Map/Satellite toggle button. |
| styleToggleSatellite string | Image for the "Satellite" of the Map/Satellite toggle button. |