Discrete color palettes for cartography and data visualization
npm install dicopalDiscrete color palettes (hundreds of them!) for JavaScript.
> Dicopal offers color palettes from:
> - Colorbrewer2
> - Fabio Crameri's Scientific Colour Maps
> - CARTOColors
> - cmocean
> - Light & Bartlein
> - Matplotlib
> - MyCarta
> - Tableau
> - The Wes Anderson Palettes blog
> - Joshua Stevens' palettes
> - Masataka Okabe and Kei Ito's Color Universal Design (CUD) categorical palette
> - D3 "Observable10" categorical palette
⏩ Browse all the available palettes
⏩ Example about the creation of asymmetric diverging palettes
Add the package to your project:
``bash`
npm install dicopal
Add the script to your HTML:
`html`
`javascript`
const pal = getPalette('Pastel', 4); // Returns the "Pastel" palette with 4 colors
// {
// "number": 4,
// "type": "qualitative",
// "name": "Pastel",
// "id": "Pastel_4",
// "colors": ["#66C5CC","#F6CF71","#F89C74","#DCB0F2"],
// "provider": "cartocolors",
// "url": "https://github.com/CartoDB/CartoColor/wiki/CARTOColor-Scheme-Names"
// }
`javascript`
const cols = getColors('Pastel', 4); // Returns the "Pastel" palette with 4 colors
// ["#66C5CC","#F6CF71","#F89C74","#DCB0F2"]
Colors can also be reversed:
`javascript`
const cols = getColors('Pastel', 4, true);
// ['#DCB0F2', '#F89C74', '#F6CF71', '#66C5CC']
`javascript`
// Returns 135 instances of palette with 3 colors
const palettes = getPalettes({ number: 3 });
`javascript`
// Returns 160 instances of qualitative palettes
const palettes = getPalettes({ type: 'qualitative' });
`javascript`
// Returns 265 instances of colorbrewer palettes
const palettes = getPalettes({ provider: 'colorbrewer' });
`javascript`
// Returns the 6 instances of the "Accent" palette
const palettes = getPalettes({ name: 'Accent' });
`javascript`
// Returns the 12 instances of the palettes that are qualitative and have 10 colors
const palettes = getPalettes({ type: 'qualitative', number: 10 });
When no argument is provided, the getPalettes function returns all the palettes:
`javascript`
// Returns the 1600 instances of palettes
const allPalettes = getPalettes();
You can then filter the palettes yourself by any combination of criteria:
`javascript`
// Only sequential and diverging palettes from all providers except colorbrewer
// with between 3 and 12 colors
const palettes = allPalettes
.filter((p) => (
['sequential', 'diverging'].includes(p.type)
&& p.provider !== 'colorbrewer'
&& p.number >= 3
&& p.number <= 12)
);
`javascript`
const providers = getPaletteProviders(); // Returns the 10 providers
`javascript`
const providers = getPaletteTypes(); // Returns the 3 types
`javascript`
// Returns the 179 names ('ArmyRose', 'BrBg', 'Accent', etc.)
const providers = getPaletteNames();
`javascript`
// Returns the 35 names ('BrBg', 'PRGn', etc.)
const providers = getPaletteNames('colorbrewer');
`javascript`
// Returns an array of numbers, like [3, 4, 5, 6, 7, 8]
const numClasses = getPaletteNumbers('Pastel2');
The getAsymmetricDivergingPalette function enables the creation of asymmetric diverging palettes
(e.g. 3 colors for the left side and 4 colors for the right side),
either balanced (i.e. the perceptual distance between the colors is the same on both sides) or not.
It takes the following arguments:
- divergingSchemeName (string): the name of the diverging scheme to use (e.g. 'RdYlBu')leftNumber
- (number): the number of colors to use on the left siderightNumber
- (number): the number of colors to use on the right sidecentralClass
- (boolean - optional): whether to include a central class (default: true)balanced
- (boolean - optional): whether to balance the colors on both sides (default: false)reverse
- (boolean - optional): whether to reverse the palette (default: false)
#### Balanced
`javascript`
const pal = getAsymmetricDivergingColors('RdYlBu', 7, 2, true, true);
#### Unbalanced
`javascript`
const pal = getAsymmetricDivergingColors('RdYlBu', 7, 2, true, false);
Sometimes, a palette exists only in a limited number of colors (e.g. 3-to-9 colors) but you need
a palette with a different number of colors (e.g. 12 colors).
The getSequentialColors function enables the creation of interpolated sequential palettes with a custom number of colors.
It takes the following arguments:
- sequentialSchemeName (string): the name of the sequential scheme to use (e.g. 'Blues')classNumber
- (number): the number of colors to usereverse
- (boolean - optional): whether to reverse the palette (default: false)
`javascript`
const pal = getSequentialColors('Blues', 12);
You can add your own palettes to Dicopal at runtime:
`javascript
// Add a qualitative palette
addPalette({
type: 'qualitative', // Mandatory, amongst ('diverging', 'qualitative', 'sequential')
name: 'MyPalette', // Mandatory, string
colors: ['#FF0000', '#00FF00', '#0000FF'], // Mandatory, array of HEX colors as string
provider: 'MyOrganisation', // Mandatory, string
url: 'https://example.com' // Optional, string
});
// Add a sequential palette
addPalette({
type: 'sequential',
name: 'MySequentialPalette',
colors: ['#FF0000', '#FF3300', '#FF6600', '#FF9900', '#FFCC00', '#FFFF00', '#FFFF33'],
provider: 'MyOrganisation',
url: 'https://example.com'
});
// Note that for the 'getAsymmetricDivergingColors' function to work correctly
// on the added palette, you must add at least two variations of the palette,
// one with a central class (and at least a total of 5 colors) and one without
// (and at least a total of 4 colors).
addPalette({
name: 'NewDivergingPalette',
type: 'diverging',
colors: ['#D7191C', '#FDAE61', '#d7d7d7', '#ABDDA4', '#35AF24'],
provider: 'MyOrg',
url: 'https://example.com',
});
addPalette({
name: 'NewDivergingPalette',
type: 'diverging',
colors: ['#D7191C', '#efc091', '#b8e1b2', '#35AF24'],
provider: 'MyOrg',
url: 'https://example.com',
});
`
You can then use the getPalette, getColors, getPalettes, getPaletteProviders, getPaletteTypes, getPaletteNames, getPaletteNumbers, getAsymmetricDivergingColors and getSequentialColors functions as usual.
For a given provider:
`javascript`
getRawData('colorbrewer');
For all the provider (default):
`javascript`
getRawData();
Contributions of all kinds are welcome, through issues and pull requests.
If you use the library and feel that the API could be improved / simplified / enriched / etc.,
don't hesitate to come and discuss it in the issues!
Palette information is stored in the src/palette.json` file.
It is generated in Python from various sources,
notably the palettable
Python library (authored by Matt Davis)
and the dicopal RDF vocabulary which
both provide a list of palettes with their colors and metadata as well
as from Joshua Stevens' palettes.
Apache-2.0. See LICENSE for details.