1# Palette Service
2
3The `palette` service offers a collection of palettes which implement a uniform interface for assigning colors to charts. The service provides methods for switching palettes
4easily. It's used by the x-pack plugins `canvas` and `lens`.
5
6Each palette is allowed to store some state as well which has to be handled by the consumer.
7
8Palettes are integrated with the expression as well using the `system_palette` and `palette` functions.
9
10## Using the palette service
11
12To consume the palette service, use `charts.palettes.getPalettes` to lazily load the async bundle implementing existing palettes. This is recommended to be called in the renderer, not as part of the `setup` or `start` phases of a plugin.
13
14All palette definitions can be loaded using `paletteService.getAll()`. If the id of the palette is known, it can be fetched using `paleteService.get(id)`.
15
16One a palette is loaded, there are two ways to request colors - either by fetching a list of colors (`getColors`) or by specifying the chart object to be colored (`getColor`). If possible, using `getColor` is recommended because it allows the palette implementation to apply custom logic to coloring (e.g. lightening up colors or syncing colors) which has to be implemented by the consumer if `getColors` is used).
17
18### SeriesLayer
19
20If `getColor` is used, an array of `SeriesLayer` objects has to be passed in. These correspond with the current series in the chart a color has to be determined for. An array is necessary as some charts are constructed hierarchically (e.g. pie charts or treemaps). The array of objects represents the current series with all ancestors up to the corresponding root series. For each layer in the series hierarchy, the number of "sibling" series and the position of the current series has to be specified along with the name of the series.
21
22## Custom palette
23
24All palettes are stateless and define their own colors except for the `custom` palette which takes a state of the form
25```ts
26{ colors: string[]; gradient: boolean }
27```
28
29This state has to be passed into the `getColors` and `getColor` function to retrieve specific colors.
30
31## Registering new palettes
32
33Currently palettes can't be extended dynamically.
34