@mapbox/style-components v0.32.3

style-components

Maintained by @mapbox/map-design-team.

What are style components?

A style component is an abstraction built on top of the Mapbox GL style spec, designed to make map styles re-usable and composable.

A style component conforms to the style component specification, which is a superset of the Mapbox GL style spec. Style component documents compile to Mapbox GL stylesheets.

A few features of style components:

• All style components compile to valid Mapbox GL stylesheets.
• Style components may have other style components nested inside of them.
• Style components use a design pattern for non-destructive map styling inspired by React whereby a parent component may pass props, which are variable values of a certain type, to a child component.
• Style components support embeddable vector images, and those vector images can be customized via props just like other values in the stylesheet.
• The style component compiler outputs stylesheets that can be decompiled into style components by including metadata on the stylesheets about which layers correspond to which components.
• The style component compiler may be run in the browser, allowing components to be used in user interfaces where the map style changes dynamically based on user input.

Installation and basic usage

npm install @mapbox/style-components

const compiler = require('@mapbox/style-components').compiler;
const style = compiler({
  // value for rootStyleComponent must conform to the style component spec
  rootStyleComponent: {
    id: 'my-config',
    components: {},
    propConfig: {},
    version: 8
  }
});

// Return a Mapbox GL style spec-compliant stylesheet
return style;

Read below for more detailed usage guidelines.

Usage

The style-components library exports two functions for working with stylesheets, two functions for working with svg data, and a validation function:

Output a stylesheet from a component

compiler transforms a style component into a Mapbox GL JS stylesheet. See the compiler documentation for usage guidelines and examples.

compiler uses generateSvgFromIcon to output svgs if svg data is present in the icons property in the style component.

Output a component from a stylesheet

decompiler transforms a Mapbox GL JS stylesheet into a style component. The stylesheet must have metadata associating style layers to components. See the decompiler documentation for usage guidelines and examples.

Output icon JSON from SVG

generateIconFromSvg transforms SVG XML into JSON that conforms to the Icon type in the component spec.

Output SVG from icon JSON

generateSvgFromIcon transforms icon JSON into SVG XML.

Validate component JSON

validate confirms that a provided JSON file satisfies the style component specification. See the validator documentation for more information.

Supported platforms

This library is compiled for use in browsers and Node.js.

Development

Release

First create a CHANGELOG entry for your release by following the instructions here. Commit the entry followed by these commands:

$ npm version {major|minor|patch}
$ git push
$ git push --tags
$ mbx npm publish