Patterns

Purpose

Using patterns can be useful to group similar items, for example imagine you want to build a pie chart displaying various foods, you can use a color scale to assign a unique color to each one, then you can group vegetables/fruits/meats/… using a similar pattern for each group (while keeping color variation).

Using patterns in nivo

Defining patterns in nivo is a 2 steps process, first you'll have to declare available definitions (the same goes for gradients) using dedicated helpers or providing plain objects.
Then you must define the rules to apply those definitions using the fill property.

Separating pattern definitions from application allows us to reuse those in various places, like fills and borders, and while maintaining a direct mapping for a bar chart with 5 items can be simple enough, when you're dealing with a complex heatmap with tens of nodes it can quickly become cumbersome. Doing so also provides the ability to use a pattern depending on chart element value. Last but not least, patterns colors can be inherited from current node ones.

Example

import { patternDotsDef, patternSquaresDef } from '@nivo/core'
import { Stream } from '@nivo/stream'

const MyChart = () => (
    <Stream
        data={/*…*/}
        keys={['react', 'vue', 'elm']}
        // 1. defining patterns
        defs={[
            // using helpers (cannot be used with http rendering API)
            // will use color from current element
            patternDotsDef('dots', { color: 'inherit' }),
            // will use background color from current element
            patternSquaresDef('squares', { background: 'inherit' }),
            // using plain object
            { id: 'custom', type: 'patternSquares', size: 24 },
        ]}
        // 2. defining rules to apply those patterns
        fill={[
            // match using query object
            // (can be used with http rendering API
            { match: { id: 'react' }, id: 'dots' },
            // match using function
            // (cannot be used with http rendering API
            { match: d => d.id === 'vue', id: 'squares' },
            // match all, will only affect 'elm' because once
            // a rule match, others are skipped
            // (can be used with http rendering API
            { match: '*', id: 'custom' },
        ]}
    />
)

Available patterns

// helper
import { patternDotsDef } from '@nivo/core'
patternDotsDef('dots-pattern', {
  "size": 4,
  "padding": 4,
  "stagger": false,
  "background": "#ffffff",
  "color": "#000000"
})
// plain object
{
    "id": "dots-pattern",
    "type": "patternDots",
    "size": 4,
    "padding": 4,
    "stagger": false,
    "background": "#ffffff",
    "color": "#000000"
}

// helper
import { patternLinesDef } from '@nivo/core'
patternLinesDef('lines-pattern', {
  "spacing": 5,
  "rotation": 0,
  "lineWidth": 2,
  "background": "#000000",
  "color": "#ffffff"
})
// plain object
{
    "id": "lines-pattern",
    "type": "patternLines",
    "spacing": 5,
    "rotation": 0,
    "lineWidth": 2,
    "background": "#000000",
    "color": "#ffffff"
}

// helper
import { patternSquaresDef } from '@nivo/core'
patternSquaresDef('squares-pattern', {
  "size": 4,
  "padding": 4,
  "stagger": false,
  "background": "#ffffff",
  "color": "#000000"
})
// plain object
{
    "id": "squares-pattern",
    "type": "patternSquares",
    "size": 4,
    "padding": 4,
    "stagger": false,
    "background": "#ffffff",
    "color": "#000000"
}

Known limitations

Please be aware that pattern usage has some limitations, it's not supported for canvas chart implementations for now, and tooltips involving colored chips will use plain element color.