picasso.js

v1.0.0

A charting library streamlined for building visualizations for the Qlik Sense Analytics platform.

picasso.js entry point

Parameterspicassojs

cfg

No description

Returnspicassojs

No description

Propertiespicassojs

version
string

picasso.js version

import picasso from 'picasso.js';

const configuredPicasso = picasso({ renderer: { prio: ['canvas'] } }) // All components will render using the canvas renderer

Parameterschart

definition

No description

Returnschart

Chart instance

picasso.chart({
    element: document.querySelector('#container'), // This is the element to render the chart in
    data: [
      {
        type: 'matrix',
        data: [
          ['Month', 'Sales', 'Margin'],
          ['Jan', 1106, 7],
          ['Feb', 5444, 53],
          ['Mar', 147, 64],
          ['Apr', 7499, 47],
          ['May', 430, 62],
          ['June', 9735, 13],
          ['July', 5832, 13],
          ['Aug', 7435, 15],
          ['Sep', 3467, 35],
          ['Oct', 3554, 78],
          ['Nov', 5633, 23],
          ['Dec', 6354, 63],
        ],
      },
    ],
    settings: {
      scales: {
        x: { data: { field: 'Margin' } },
        y: { data: { field: 'Sales' } },
      },
      components: [
        {
          // specify how to render the chart
          type: 'axis',
          scale: 'y',
          layout: {
            dock: 'left',
          },
        },
        {
          type: 'axis',
          scale: 'x',
          layout: {
            dock: 'bottom',
          },
        },
        {
          type: 'point',
          data: {
            extract: {
              field: 'Month',
              props: {
                x: { field: 'Margin' },
                y: { field: 'Sales' },
              },
            },
          },
          settings: {
            x: { scale: 'x' },
            y: { scale: 'y' },
            size: function () {
              return Math.random();
            },
          },
        },
      ],
    },
  });

Register a value with the given key. If value is omitted, returns the value of key.

Parameterscomponent

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returnscomponent

any

Registered value

Register a value with the given key. If value is omitted, returns the value of key.

Parametersdata

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returnsdata

any

Registered value

Register a value with the given key. If value is omitted, returns the value of key.

Parametersformatter

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returnsformatter

any

Registered value

Register a value with the given key. If value is omitted, returns the value of key.

Parametersinteraction

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returnsinteraction

any

Registered value

Register a value with the given key. If value is omitted, returns the value of key.

Parametersrenderer

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returnsrenderer

any

Registered value

const svgFactory = picassojs.renderer('svg');
const svgRenderer = svgFactory();

Register a value with the given key. If value is omitted, returns the value of key.

Parametersscale

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returnsscale

any

Registered value

Plugin registry

Parametersuse

plugin

Callback function to register a plugin

options
optional
object

No description

Brush()

interface

A brush context

Triggered when this brush is deactivated

Triggered when this brush is activated

Triggered when this brush is updated

Parametersupdate

added
Array<object>

The added items

removed
Array<object>

The removed items

Add and remove values in a single operation almost the same as calling addValues and removeValues but only triggers one 'update' event

If the state of the brush changes, an 'update' event is emitted.

ParametersaddAndRemoveValues

addItems
Array<object>

Items to add

removeItems
Array<object>

Items to remove

Adds an alias to the given key

ParametersaddKeyAlias

key
string

Value to be replaced

alias
string

Value to replace key with

brush.addKeyAlias('BadFieldName', 'Region');
brush.addValue('BadFieldName', 'Sweden'); // 'BadFieldName' will be stored as 'Region'
brush.containsValue('Region', 'Sweden'); // true
brush.containsValue('BadFieldName', 'Sweden'); // true

Adds a numeric range to this brush context

ParametersaddRange

key
string

An identifier that represents the data source of the range

range

The range to add to this brush

brush.addRange('Sales', { min: 20, max: 50 });

ParametersaddRanges

items

Items containing the ranges to remove

Adds a primitive value to this brush context

If this brush context is not started, a 'start' event is emitted. If the state of the brush changes, ie. if the added value does not already exist, an 'update' event is emitted.

ParametersaddValue

key
string

An identifier that represents the data source of the value

value
string | number

The value to add

brush.addValue('countries', 'Sweden');
brush.addValue('/qHyperCube/qDimensionInfo/0', 3);

ParametersaddValues

items
Array<object>

Items to add

Returns all brushes within this context

Returnsbrushes

object

No description

Brushclear()

function

Clears this brush context

Configure the brush instance.

Parametersconfigure

config

No description

brushInstance.configure({
  ranges: [
    { key: 'some key', includeMax: false },
    { includeMax: true, includeMin: true },
  ]
})

Checks if a range segment is contained within this brush context

Returns true if the range segment exists for the provided key, returns false otherwise.

ParameterscontainsRange

key
string

An identifier that represents the data source of the value

range

The range to check for

ReturnscontainsRange

boolean

No description

brush.addRange('Sales', { min: 10, max: 50 });
brush.containsRange('Sales', { min: 15, max: 20 }); // true - the range segment is fully contained within [10, 50]
brush.containsRange('Sales', { min: 5, max: 20 }); // false - part of the range segment is outside [10, 50]
brush.containsRange('Sales', { min: 30, max: 80 }); // false - part of the range segment is outside [10, 50]

Checks if a value is contained within a range in this brush context

Returns true if the values exists for the provided key, returns false otherwise.

ParameterscontainsRangeValue

key
string

An identifier that represents the data source of the value

value
number

The value to check for

ReturnscontainsRangeValue

boolean

No description

brush.addRange('Sales', { min: 10, max: 50 });
brush.containsRangeValue('Sales', 30); // true
brush.containsRangeValue('Sales', 5); // false

Checks if a certain value exists in this brush context

Returns true if the values exists for the provided key, returns false otherwise.

ParameterscontainsValue

key
string

An identifier that represents the data source of the value

value
string | number

The value to check for

ReturnscontainsValue

boolean

No description

brush.addValue('countries', 'Sweden');
brush.containsValue('countries', 'Sweden'); // true
brush.toggleValue('countries', 'Sweden'); // remove 'Sweden'
brush.containsValue('countries', 'Sweden'); // false
emitsend

Ends this brush context

Ends this brush context and emits an 'end' event if it is not already ended.

Parametersend

args
any

arguments to be passed to 'end' listeners

Adds an event interceptor

Parametersintercept

name
string

Name of the event to intercept

ic
function

Handler to call before event is triggered

brush.intercept('add-values', items => {
 console.log('about to add the following items', items);
 return items;
});

Checks if this brush is activated

Returns true if started, false otherwise

ReturnsisActive

boolean

No description

Removes all interceptors

ParametersremoveAllInterceptors

name
optional
string

Name of the event to remove interceptors for. If not provided, removes all interceptors.

Removes an interceptor

ParametersremoveInterceptor

name
string

Name of the event to intercept

ic
function

Handler to remove

Removes an alias

This will only remove the key to alias mapping for new manipulations of the brush, no changes will be made to the current state of this brush.

ParametersremoveKeyAlias

key
string

Value to remove as alias

brush.removeKeyAlias('BadFieldName');

Removes a numeric range from this brush context

ParametersremoveRange

key
string

An identifier that represents the data source of the range

range

The range to remove from this brush

ParametersremoveRanges

items
Array<object>

Items containing the ranges to remove

Removes a primitive values from this brush context

If the state of the brush changes, ie. if the removed value does exist, an 'update' event is emitted.

ParametersremoveValue

key
string

An identifier that represents the data source of the value

value
string | number

The value to remove

brush.removeValue('countries', 'Sweden');

ParametersremoveValues

items
Array<object>

Items to remove

Sets a numeric range to this brush context

Overwrites any active ranges identified by key

ParameterssetRange

key
string

An identifier that represents the data source of the range

range

The range to set on this brush

ParameterssetRanges

items
Array<object>

Items containing the ranges to set

ParameterssetValues

items
Array<object>

Items to set

emitsstart

Starts this brush context

Starts this brush context and emits a 'start' event if it is not already started.

Parametersstart

args
any

arguments to be passed to 'start' listeners

Toggles a numeric range in this brush context

Removes the range if it's already contained within the given identifier, otherwise the given range is added to the brush.

ParameterstoggleRange

key
string

An identifier that represents the data source of the range

range

The range to toggle in this brush

ParameterstoggleRanges

items
Array<object>

Items containing the ranges to toggle

Toggles a primitive value in this brush context

If the given value exists in this brush context, it will be removed. If it does not exist it will be added.

ParameterstoggleValue

key
string

An identifier that represents the data source of the value

value
string | number

The value to toggle

brush.toggleValue('countries', 'Sweden');

ParameterstoggleValues

items
Array<object>

Items to toggle

PropertiesBrushConfig

ranges
optional

Range configurations

PropertiesRanges

includeMax
optional, default=true
boolean

Whether or not the maximum value of a range should be included when determining if a value is brushed.

includeMin
optional, default=true
boolean

Whether or not the minimum value of a range should be included when determining if a value is brushed.

key
optional
string

An identifier that represents the data source of the value

PropertiesBrushConsumeSettings

context
optional
string

Name of the brush context to observe

data
optional
Array<string>

The mapped data properties to observe

mode
optional
string

Data properties operator: and, or, xor.

style
optional

The style to apply to the shapes of the component

{
   context: 'selection',
   data: ['x'],
   filter: (shape) => shape.type === 'circle',
   style: {
     active: {
       fill: 'red',
       stroke: '#333',
       strokeWidth: (shape) => shape.strokeWidth * 2,
     },
     inactive: {},
   },
}

Filtering function

PropertiesBrushTargetConfig

key
string

Component key

contexts
optional
Array<string>

Name of the brushing contexts to affect

data
optional
Array<string>

The mapped data properties to add to the brush

action
optional, default='set'
string

Type of action to respond with

PropertiesBrushTriggerSettings

on
optional
string

Type of interaction to trigger brush on

action
optional
string

Type of interaction to respond with

contexts
optional
Array<string>

Name of the brushing contexts to affect

data
optional
Array<string>

The mapped data properties to add to the brush

propagation
optional
string

Control the event propagation when multiple shapes are tapped. Disabled by default

globalPropagation
optional
string

Control the event propagation between components. Disabled by default

touchRadius
optional
number

Extend contact area for touch events. Disabled by default

mouseRadius
optional
number

Extend contact area for regular mouse events. Disabled by default

{
   on: 'tap',
   action: 'toggle',
   contexts: ['selection', 'tooltip'],
   data: ['x'],
   propagation: 'stop', // 'stop' => prevent trigger from propagating further than the first shape
   globalPropagation: 'stop', // 'stop' => prevent trigger of same type to be triggered on other components
   touchRadius: 24,
   mouseRadius: 10
 }

Create a new canvas renderer

ParameterscanvasRendererFactory

sceneFn
optional
function

Scene factory

ReturnscanvasRendererFactory

A canvas renderer instance

Chart()

interface

Chart instance

PropertiesChart

interactions

Get all interaction instances

Get or create brush context for this chart

Parametersbrush

name
string

Name of the brush context. If no match is found, a new brush context is created and returned.

Returnsbrush

A brush context

Brush data by providing a collection of data bound shapes.

ParametersbrushFromShapes

shapes

An array of data bound shapes.

config

Options

const shapes = chartInstance.shapesAt(...);
const config = {
 components:[
   {
     key: 'key1',
     contexts: ['myContext'],
     data: [''],
     action: 'add'
   }
 ]
};
chartInstance.brushFromShapes(shapes, config);

Get a component context

Parameterscomponent

key
string

Component key

Returnscomponent

Component instance

Get components overlapping a point.

ParameterscomponentsFromPoint

p

Point with x- and y-coordinate. The coordinate is relative to the browser viewport.

ReturnscomponentsFromPoint

Array of component contexts

Get

Parametersdataset

key
string

Get the dataset identified by key

Returnsdataset

No description

Destroy the chart instance.

Get all nodes matching the provided selector

ParametersfindShapes

selector
string

CSS selector [type, attribute, universal, class]

ReturnsfindShapes

Array of objects containing matching nodes

chart.findShapes('Circle') // [<CircleNode>, <CircleNode>]
chart.findShapes('Circle[fill="red"][stroke!="black"]') // [CircleNode, CircleNode]
chart.findShapes('Container Rect') // [Rect, Rect]

Get or create a formatter for this chart

Parametersformatter

v
string | object

Formatter reference or formatter options

Returnsformatter

No description

instance.formatter('nameOfMyFormatter'); // Fetch an existing formatter by name
instance.formatter({ formatter: 'nameOfMyFormatter' }); // Fetch an existing formatter by name
instance.formatter({ type: 'q' }); // Fetch an existing formatter by type
instance.formatter({
 formatter: 'd3',
 type: 'number',
 format: '1.0.%'
}); // Create a new formatter

Get all registered formatters

Returnsformatters

No description

Get all shapes associated with the provided context

ParametersgetAffectedShapes

context
string

The brush context

mode
string

Property comparison mode.

props
Array<string>

Which specific data properties to compare

key
string

Which component to get shapes from. Default gives shapes from all components.

ReturnsgetAffectedShapes

Array<object>

Array of objects containing shape and parent element

Get or create a scale for this chart

Parametersscale

v
string | object

Scale reference or scale options

Returnsscale

Scale instance

instance.scale('nameOfMyScale'); // Fetch an existing scale by name
instance.scale({ scale: 'nameOfMyScale' }); // Fetch an existing scale by name
instance.scale({ source: '0/1', type: 'linear' }); // Create a new scale

Get all registered scales

Returnsscales

No description

Get all nodes colliding with a geometrical shape (circle, line, rectangle, point, polygon, geopolygon).

The input shape is identified based on the geometrical attributes in the following order: circle => line => rectangle => point => polygon => geopolygon. Note that not all nodes on a scene have collision detection enabled.

ParametersshapesAt

shape

A geometrical shape. Coordinates are relative to the top-left corner of the chart instance container.

opts

Options

ReturnsshapesAt

Array of objects containing colliding nodes

chart.shapesAt(
 {
   x: 0,
   y: 0,
   width: 100,
   height: 100
 },
 {
   components: [
     { key: 'key1', propagation: 'stop' },
     { key: 'key2' }
   ],
   propagation: 'stop'
 }
);

ParameterstoggleBrushing

val
optional
boolean

Toggle brushing on or off. If value is omitted, a toggle action is applied to the current state.

Update the chart with new settings and / or data

Parametersupdate

def
optional

New chart definition

PropertiesChartDefinition

data

Chart data

element
HTMLElement

Element to attach chart to

settings

Chart settings

Called before the chart has been destroyed

Called before the chart has been mounted

Called before the chart has been rendered

Called before the chart has been updated

Called when the chart has been created

Called after the chart has been destroyed

Called after the chart has been mounted

Parametersmounted

element
HTMLElement

The element the chart been mounted to

Called after the chart has been updated

PropertiesChartSettings

components
optional

Components

scales
optional

Dictionary with scale definitions

formatters
optional

Dictionary with formatter definitions

strategy

Dock layout settings

interactions
optional

Interaction handlers

collections
optional

Collections

Circle

object

PropertiesCircle

cx
number

Center x-coordinate

cy
number

Center y-coordinate

r
number

Circle radius

PropertiesCollectionSettings

key
string

Unique key for the collection

data

Used to extract data from a DataSource

{
    key: 'my-collection',
    data: {
      extract: [{
        source: 'Products',
        field: 'Product',
        value: d => d.name,
        label: d => `<${d.name}>`
        props: {
          year: { field: 'Year' }
          num: { field: 'Sales' }
        }
      }],
      filter: d => d.label !== 'Sneakers', // extract everything except Sneakers
      sort: (a, b) => a.label > b.label ? -1 : 1, // sort descending
    }
}

Component

object

Component instance

PropertiesComponent

type
string

Type of component

key
string

Key of the component

PropertiesComponentAxis

scale
string

reference to band or linear scale

settings

discrete or continuous axis settings

{
 type: 'axis',
 scale: '<name-of-scale>'
}

Continuous axis settings

PropertiesContinuousSettings

align
optional, default='auto'
string

Set the anchoring point of the axis. Available options are auto/left/right/bottom/top. In auto the axis determines the best option. The options are restricted based on the axis orientation, a vertical axis may only anchor on left or right

labels

No description

line

No description

minorTicks

No description

paddingEnd
optional, default=10
number

Padding in direction perpendicular to the axis

paddingStart
optional
number

Padding in direction perpendicular to the axis

ticks

No description

{
 type: 'axis',
 scale: '<name-of-linear-scale>',
 settings: {
   minorTicks: {
     show: false,
   },
 },
}

Discrete axis settings

PropertiesDiscreteSettings

align
optional, default='auto'
string

Set the anchoring point of the axis. Available options are auto/left/right/bottom/top. In auto the axis determines the best option. The options are restricted based on the axis orientation, a vertical axis may only anchor on left or right

labels

No description

line

No description

paddingEnd
optional, default=10
number

Padding in direction perpendicular to the axis

paddingStart
optional
number

Padding in direction perpendicular to the axis

ticks

No description

{
 type: 'axis',
 scale: '<name-of-band-scale>',
 settings: {
   labels: {
     mode: 'tilted',
     tiltAngle: 40,
   },
 },
}

PropertiesComponentBox

data

No description

settings

No description

{
  type: "box",
  data: {
   mapTo: {
     min: { source: "/qHyperCube/qMeasureInfo/0" },
     start: { source: "/qHyperCube/qMeasureInfo/1" },
     med: { source: "/qHyperCube/qMeasureInfo/2" },
     end: { source: "/qHyperCube/qMeasureInfo/3" },
     max: { source: "/qHyperCube/qMeasureInfo/4" },
   },
   groupBy: {
     source: "/qHyperCube/qDimensionInfo/0"
   }
 },
 settings: {
   major: {
     scale: { source: "/qHyperCube/qDimensionInfo/0" }
   },
   minor: {
     scale: { source: ["/qHyperCube/qMeasureInfo/0",
              "/qHyperCube/qMeasureInfo/1",
              "/qHyperCube/qMeasureInfo/2",
              "/qHyperCube/qMeasureInfo/3",
              "/qHyperCube/qMeasureInfo/4"] }
   }
 }
}

PropertiesMajorReference

start
string

Reference to the data property of the start value along the major axis

end
string

Reference to the data property of the end value along the major axis

A component that can brush a rectangular area

PropertiesComponentBrushArea

settings

No description

{
 type: 'brush-area',
 brush: {
   components: [{ key: '<target-component>', contexts: ['highlight'] }]
 }
}

PropertiesComponentBrushAreaDir

settings

No description

PropertiesComponentBrushLasso

settings

Component settings

{
 type: 'brush-lasso',
 settings: {
   brush: {
     components: [{ key: '<target-component>', contexts: ['<brush-context>'] }]
   }
 },
}

PropertiesComponentBrushRange

settings

No description

experimental

PropertiesComponentContainer

type
experimental
optional, default='container'
string

No description

{
 type: 'container',
 preferredSize: ({ inner, outer, dock, children }) => {
   const sizes = children.map(c => c.preferredSize({ inner, outer }));
   return Math.max(...sizes);
 },
 strategy: (rect, components) => {
   const height = rect.height / components.length;
   components.forEach((c, i) => {
     c.resize({ ...rect, height, y: rect.y + i * height })
   });
   return { visible: components, hidden: [], order: components };
 },
 components: [
    ...
 ],
}

PropertiesComponentGridLine

settings

Component settings

{
 type: 'grid-line',
 settings: {
   x: {
     scale: '<name-of-scale>',
   },
   y: {
     scale: '<name-of-scale>',
   },
 },
}

PropertiesComponentLabels

settings

Component settings

{
  type: 'labels',
  settings: {
    sources: [
      {
        component: 'bars',
        selector: 'rect', // select all 'rect' shapes from the 'bars' component
        strategy: {
          type: 'bar', // the strategy type
          settings: {
            labels: [
              {
                label({ data }) {
                  return data ? data.end.label : '';
                },
                placements: [
                  // label placements in prio order. Label will be placed in the first place it fits into
                  { position: 'inside', fill: '#fff' },
                  { position: 'outside', fill: '#666' },
                ],
              },
            ],
          },
        },
      },
    ],
  },
}

PropertiesBarsLabelStrategy

type
default='bar'
string

Name of strategy

settings

Bars strategy settings

PropertiesRowsLabelStrategy

type
default='rows'
string

Name of strategy

settings

Rows strategy settings

PropertiesSlicesLabelStrategy

type
default='slice'
string

Name of strategy

settings

Slices strategy settings

PropertiesSource

component
string

Key of target component

selector
string

Shape selector

strategy

Strategy settings

PropertiesComponentLegendCat

scale
string

Reference to categorical color scale

settings

Component settings

{
  type: 'legend-cat',
  scale: '<categorical-color-scale>',
}

PropertiesComponentLegendSeq

settings

Component settings

{
  type: 'legend-seq',
  settings: {
    fill: '<sequential-color-scale>',
    major: '<linear-scale>',
  }
}

PropertiesComponentLine

settings

Component settings

{
  type: "line",
  data: {
    extract: {
      field: "Year",
      props: {
        sales: { field: "Sales" },
      },
    },
  },
  settings: {
    coordinates: {
      major: { scale: "t" },
      minor: { scale: "y", ref: "sales" },
    },
  },
}

Callback function for layer sort

ParametersLayerSort

a

No description

b

No description

PropertiesComponentPie

settings

Component settings

{
  type: 'pie',
  data: {
    extract: {
      field: 'Region',
      props: {
        num: { field: 'Population' }
      }
    }
  },
  settings: {
    startAngle: Math.PI / 2,
    endAngle: -Math.PI / 2,
    slice: {
      arc: { ref: 'num' },
      fill: 'green',
      stroke: 'red',
      strokeWidth: 2,
      strokeLinejoin: 'round',
      innerRadius: 0.6,
      outerRadius 0.8,
      opacity: 0.8,
      offset: 0.2
    }
  }
}

PropertiesComponentPoint

settings

Component settings

{
  type: 'point',
  data: {
    extract: {
      field: 'Month',
      props: {
        x: { field: 'Margin' },
        y: { field: 'Year' }
      }
    }
  },
  settings: {
    x: { scale: 'm' },
    y: { scale: 'y' },
  }
}

PropertiesComponentRefLine

settings

Component settings

{
 type: 'ref-line',
 lines: {
   y: [{
     scale: 'y',
     value: 5000,
     label: {
       text: 'value label'
     }
   }]
 }
}

PropertiesGenericObject

fill
optional, default='#fff'
string

Fill color

stroke
optional, default='transparent'
string

Stroke

strokeWidth
optional
number

Stroke width

opacity
optional, default=1
number

Opacity

PropertiesGenericText

text
optional, default=''
string

Text (if applicable)

fontSize
optional, default='12px'
string

Font size (if applicable)

fontFamily
optional, default='Arial'
string

Font family

fill
optional, default='#fff'
string

Fill color

stroke
optional, default='transparent'
string

Stroke

strokeWidth
optional
number

Stroke width

strokeDasharray
optional
string

Stroke dash array

opacity
optional, default=1
number

Opacity

PropertiesLine

value
number | function

The value of the reference line. If a scale is specified, it is applied.

scale
optional
string

Scale to use (if undefined will use normalized value 0-1)

line
optional, default=ComponentRefLine~GenericObject

The style of the line

label
optional, default=ComponentRefLine~LineLabel

The label style of the line

PropertiesLineLabel

padding
default=5
number

Padding inside the label

text
optional, default=''
string

Text

fontSize
optional, default='12px'
string

Font size

fontFamily
optional, default='Arial'
string

Font family

stroke
optional, default='transparent'
string

Stroke

strokeWidth
optional
number

Stroke width

opacity
optional, default=1
number

Opacity

align
optional
number | string

Alignment property left to right (0 = left, 1 = right). Also supports string ('left', 'center', 'middle', 'right')

vAlign
optional
number | string

Alignment property top to bottom (0 = top, 1 = bottom). Also supports string ('top', 'center', 'middle', 'bottom')

maxWidth
optional, default=1
number

The maximum relative width to the width of the rendering area (see maxWidthPx as well)

maxWidthPx
optional, default=9999
number

The maximum width in pixels. Labels will be rendered with the maximum size of the smallest value of maxWidth and maxWidthPx size, so you may specify maxWidth 0.8 but maxWidthPx 100 and will never be over 100px and never over 80% of the renderable area

background
optional, default=ComponentRefLine~LineLabelBackground

The background style (rect behind text)

showValue
optional, default=true
boolean

Show value label

PropertiesLineLabelBackground

fill
optional, default='#fff'
string

Fill color

stroke
optional, default='transparent'
string

Stroke

strokeWidth
optional
number

Stroke width

opacity
optional, default=0.5
number

Opacity

Generic settings available to all components

PropertiesComponentSettings

type
string

Component type (ex: axis, point, ...)

brush
optional

Brush settings

layout
optional

Layout settings

show
optional, default=true
boolean

If the component should be rendered

scale
optional
string

Named scale. Will be provided to the component if it asks for it.

formatter
optional
string

Named formatter. Fallback to create formatter from scale. Will be provided to the component if it asks for it.

components
experimental
optional

Optional list of child components

strategy

Layout strategy used for child components.

data

Extracted data that should be available to the component

Function returning the preferred size

Called when the component has been created

Called before the component has been mounted

Called after the component has been mounted

Called before the component has been updated

Called after the component has been updated

Called before the component has been rendered

Called before the component has been destroyed

Called after the component has been destroyed

PropertiesComponentText

text
string | function

Text to display

settings

No description

{
 type: 'text',
 text: 'my title',
 dock: 'left',
 settings: {
   anchor: 'left',
 }
}

PropertiesComponentTooltip

settings

No description

type
default='tooltip'
string

No description

picasso.chart({
  settings: {
    interactions: [{
      type: 'native',
      events: {
        mousemove(e) {
          const tooltip = this.chart.component('<tooltip-key>');
          tooltip.emit('show', e);
        },
        mouseleave(e) {
          const tooltip = this.chart.component('<tooltip-key>');
          tooltip.emit('hide');
        }
      }
    }],
    components: [
      {
        key: '<tooltip-key>',
        type: 'tooltip'
      }
    ]
  },
  ...
});

ParameterscustomLayoutFunction

rect

No description

components

No description

Used to extract data from a DataSource

PropertiesDataExtraction

extract

Data extraction definition. Define how and what kind of data should be extracted from a DataSource.

stack
optional

If provided, defines how the data should be stacked

{
  extract: [{
    source: 'Products',
    field: 'Product',
    value: d => d.name,
    label: d => `<${d.name}>`
    props: {
      year: { field: 'Year' }
      num: { field: 'Sales' }
    }
  }],
  filter: d => d.label !== 'Sneakers', // extract everything except Sneakers
  sort: (a, b) => a.label > b.label ? -1 : 1, // sort descending
}

Callback function to filter the extracted data items

Parametersfilter

datum

The extracted datum

Returnsfilter

boolean

Return true if the datum should be included in the final data set

Callback function to sort the extracted data items

Parameterssort

a

The extracted datum

b

The extracted datum

Returnssort

number

If less than 0, sort a before b. If greater than 0, sort b before a

Data extraction definition. Define how and what kind of data should be extracted from a DataSource.

PropertiesExtract

source
string

Which data source to extract from

field
string

The field to extract data from

value
optional
ValueFn | string | number | boolean

The field value accessor

label
optional
LabelFn | string | number | boolean

The field label accessor

reduce
optional
ReduceFn | string

Reducer function

reduceLabel
optional
ReduceLabelFn | string

Label reducer function

props
optional

Additional properties to add to the extracted item

{
    source: 'Products',
    field: 'Product',
    value: (val) => val,
    label: (val) => `<${val}>`
    props: {
      year: { field: 'Year' }
      num: { field: 'Sales' }
    }
  }

TrackBy callback function

ParameterstrackBy

cell
any

The field cell

ReturnstrackBy

any

No description

Filter callback function

Parametersfilter

cell
any

The field cell

Returnsfilter

boolean

No description

Filter callback function

ParametersFilterFn

cell
any

The field cell

ReturnsFilterFn

boolean

No description

Label callback function

ParametersLabelFn

cell
any

The field cell

ReturnsLabelFn

string

No description

PropertiesProps

field
string

The field to extract data from

value
optional
ValueFn | string | number | boolean

The field value accessor

label
optional
LabelFn | string | number | boolean

The field label accessor

{
 field: 'Sales',
 value: (val) => Math.round(val),
 label: (val) => `<${val}>`
}

Reduce callback function

ParametersReduceFn

values
Array<any>

The collected values to reduce

ReturnsReduceFn

any

No description

ReduceLabel callback function

ParametersReduceLabelFn

labels
Array<any>

The collected labels to reduce

value
any

Reduced value

ReturnsReduceLabelFn

string

No description

TrackBy callback function

ParametersTrackByFn

cell
any

The field cell

ReturnsTrackByFn

any

No description

Value callback function

ParametersValueFn

cell
any

The field cell

ReturnsValueFn

any

No description

Callback function to filter the extracted data items

ParametersFilterCallback

datum

The extracted datum

ReturnsFilterCallback

boolean

Return true if the datum should be included in the final data set

Callback function to sort the extracted data items

ParametersSortCallback

a

The extracted datum

b

The extracted datum

ReturnsSortCallback

number

If less than 0, sort a before b. If greater than 0, sort b before a

Callback function. Should return the key to stack by

ParametersStackKeyCallback

datum

The extracted datum

ReturnsStackKeyCallback

any

The data value to stack by

Callback function. Should return the data value to stack with

ParametersStackValueCallback

datum

The extracted datum

ReturnsStackValueCallback

any

The data value to stack with

PropertiesDataFieldExtraction

source
string

Which data source to extract from

field
string

The field to extract data from

value
optional
ValueFn | string | number | boolean

The field value accessor

label
optional
LabelFn | string | number | boolean

The field label accessor

{
 source: 'Products',
 field: 'Sales',
 value: (val) => Math.round(val),
 label: (val) => `<${val}>`
}

Dataset()

interface

Extract data items from this dataset

Parametersextract

config

No description

Returnsextract

No description

Find a field within this dataset

Parametersfield

query
string

The field to find

Returnsfield

No description

Get all fields within this dataset

Returnsfields

No description

Returnshierarchy

null

No description

Datasetkey()

function

Get the key identifying this dataset

Returnskey

string

No description

Datasetraw()

function

Get the raw data

Returnsraw

any

No description

PropertiesDataSource

key
string

Unique identifier for this data source

type
string

The dataset type

data
any

Data

Callback function

ParametersdatumAccessor

d

datum

(d) => Math.min(0, d.value);

Custom type that is either a boolean, DatumConfig or a datumAccessor

PropertiesDatumConfig

scale
optional
string

Name of a scale

ref
optional
string

A reference to a DatumExtract property

// Implicitly resolve the datum by passing a referenced data through the scale
{
 scale: '<name-of-scale>',
 ref: '<data-property>'
}

// or explicitly resolve the datum using callback function
{
 fn: (d) => Math.min(0, d.datum.x.value);
}

Callback function

Parametersfn

d

datum

(d) => Math.min(0, d.value);

PropertiesDatumExtract

value
any

The extracted value

label
string

The extracted value as a string

source

The data source of the extracted data

Custom type that is either a number, DatumConfig or a datumAccessor

Custom type that is either a string, DatumConfig or a datumAccessor

Dock layout settings

PropertiesDockLayoutSettings

logicalSize
optional

Logical size

center
optional

Define how much space the center dock area requires

layoutModes
optional

Dictionary with named sizes

size
optional

Size is equal to that of the container (element) of the chart by default. It's possible to overwrite it by explicitly setting width or height

PropertiesLayoutMode

width
number

No description

height
number

No description

Field

object

Returns a formatter adapted to the content of this field.

Fieldid()

function

Returns this field's id

Returnsid

string

No description

Fielditems()

function

Returns the values of this field.

Returnsitems

No description

Fieldkey()

function

Returns this field's key

Returnskey

string

No description

Fieldmax()

function

Returns the max value of this field.

Returnsmax

number

No description

Fieldmin()

function

Returns the min value of this field.

Returnsmin

number

No description

Fieldraw()

function

Returns the input data

Returnsraw

any

No description

Fieldtags()

function

Returns the tags.

Returnstags

Array<string>

No description

Fieldtitle()

function

Returns this field's title.

Returnstitle

string

No description

Fieldtype()

function

Returns this field's type: 'dimension' or 'measure'.

Returnstype

string

No description

formatter()

function

Returnsformatter

any

Returns a formatted value

PropertiesFormatterDefinition

formatter
optional
string

Name of the formatter

type
optional
string

Type of formatter

format
optional
string

Format string

data

The data to create formatter from

PropertiesGeopolygon

polygons

Array of polygons

Interaction instance

PropertiesInteraction

key
string

Interaction identifier

Enable interaction

Disable interaction

Destroy interaction

PropertiesInteractionSettings

type
string

Type of interaction handler

key
optional
string

Unique key identifying the handler

enable
function | boolean

Enable or disable the interaction handler. If a callback function is provided, it must return either true or false

{
 type: 'native',
 key: 'nativeHandler',
 enable: () => true,
 events: { // "events" is a property specific to the native handler
   mousemove: (e) => console.log('mousemove', e),
 }
}

Line

object

PropertiesLine

x1
number

Start x-coordinate

y1
number

Start y-coordinate

x2
number

End x-coordinate

y2
number

End y-coordinate

Path

object

PropertiesPath

d
string

Path definition

Callback function to register a plugin

Parametersplugin

registries

No description

options
object

No description

Point

object

PropertiesPoint

x
number

X-coordinate

y
number

Y-coordinate

Polygon

object

PropertiesPolygon

points

Array of connected points

Polyline

object

PropertiesPolyline

points

Array of connected points

Rect

object

PropertiesRect

x
number

X-coordinate

y
number

Y-coordinate

width
number

Width

height
number

Height

Register a value with the given key. If value is omitted, returns the value of key.

Parameterscomponent

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returnscomponent

any

Registered value

Register a value with the given key. If value is omitted, returns the value of key.

Parametersdata

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returnsdata

any

Registered value

Register a value with the given key. If value is omitted, returns the value of key.

Parametersformatter

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returnsformatter

any

Registered value

Register a value with the given key. If value is omitted, returns the value of key.

Parametersinteraction

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returnsinteraction

any

Registered value

Register a value with the given key. If value is omitted, returns the value of key.

Parametersrenderer

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returnsrenderer

any

Registered value

Register a value with the given key. If value is omitted, returns the value of key.

Parametersscale

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returnsscale

any

Registered value

Register a value with the given key. If value is omitted, returns the value of key.

Parametersregistry

key
string

Name of the type to register

value
optional
any

Value to store in the registry.

Returnsregistry

any

Registered value

Renderer()

interface

ParametersappendTo

element
HTMLElement

Element to attach renderer to

ReturnsappendTo

HTMLElement

Root element of the renderer

Clear all child elements from the renderer root element

Returnsclear

The renderer instance

Remove the renderer root element from its parent element

Get the element this renderer is attached to

Returnselement

HTMLElement

No description

Get all nodes matching the provided selector

ParametersfindShapes

selector
string

CSS selector [type, attribute, universal, class]

ReturnsfindShapes

Array of objects containing matching nodes

Get nodes renderer at area

ParametersitemsAt

geometry

Get nodes that intersects with geometry

ReturnsitemsAt

No description

ParametersmeasureText

opts

No description

ReturnsmeasureText

object

Width and height of text

measureText({
 text: 'my text',
 fontSize: '12px',
 fontFamily: 'Arial'
}); // returns { width: 20, height: 12 }

Parametersrender

nodes
Array<object>

Nodes to render

Returnsrender

boolean

True if the nodes were rendered, otherwise false

Get the root element of the renderer

Returnsroot

HTMLElement

No description

Set or Get the size definition of the renderer container.

Parameterssize

opts

Size definition

Returnssize

The current size definition

PropertiesSizeDefinition

x
optional
number

x-coordinate

y
optional
number

y-coordinate

width
optional
number

Width

height
optional
number

Height

scaleRatio
optional

No description

margin
optional

No description

Scale

interface

Scale instance

PropertiesScale

type
string

Type of scale

ScaleBand

object

PropertiesScaleBand

type
optional, default='band'
string

No description

padding
optional
number

Sets both inner and outer padding to the same value

paddingInner
optional
number

Inner padding

paddingOuter
optional
number

Outer padding

align
optional, default=0.5
number

Control how the outer padding should be distributed, where 0.5 would distribute the padding equally on both sides

invert
optional
boolean

Invert the output range

maxPxStep
optional
number

Explicitly limit the bandwidth to a pixel value

range
optional, default=[0, 1]
array | function

Set range explicitly (ignored when maxPxStep takes effect)

Callback label function, applied on each datum

Callback value function, applied on each datum

PropertiesScaleCategoricalColor

type
optional, default='categorical-color'
string

No description

range
optional
Array<string>

CSS color values of the output range

unknown
optional
string

Value to return when input value is unknown

explicit
optional

Explicitly bind values to an output

Definition for creating a scale. Additional properties, specific for a type of scale, can be added as key/value pairs

PropertiesScaleDefinition

type
optional
string

Type of scale

data

Data configuration

PropertiesScaleLinear

type
optional, default='linear'
string

No description

expand
optional
number

Expand the output range

invert
optional
boolean

Invert the output range

include
optional
Array<number>

Include specified numbers in the output range

ticks
optional

No description

minorTicks
optional

No description

min
optional
number

Set an explicit minimum value

max
optional
number

Set an explicit maximum value

PropertiesScaleSequentialColor

type
optional, default='sequential-color'
string

No description

range
optional
Array<string>

CSS color values of the output range

invert
optional
boolean

Invert range

min
optional
number

Set an explicit minimum value

max
optional
number

Set an explicit maximum value

PropertiesScaleThresholdColor

type
optional, default='threshold-color'
string

No description

domain
optional
Array<number>

Values defining the thresholds

range
optional
Array<string>

CSS color values of the output range

invert
optional
boolean

Invert range

min
optional
number

Set an explicit minimum value

max
optional
number

Set an explicit maximum value

nice
optional
boolean

If set to true, will generate 'nice' domain values. Ignored if domain is set.

Read-only object representing a node on the scene.

PropertiesSceneNode

attrs
object

Node attributes

bounds

Bounding rectangle of the node. After any transform has been applied, if any, but excluding scaling transform related to devicePixelRatio. Origin is in the top-left corner of the scene element.

children
Array<SceneNode>

Get child nodes

collider

Collider of the node. Transform on the node has been applied to the collider shape, if any, but excluding scaling transform related to devicePixelRatio. Origin is in the top-left corner of the scene element.

If node has no collider, null is returned.

data
any

Get the associated data

desc
object

Node description

element
HTMLElement

Element the scene is attached to

key
string

Key of the component this shape belongs to

localBounds

Bounding rectangle of the node within its local coordinate system. Origin is in the top-left corner of the scene element.

parent

Get parent node

tag
string

Node tag

type
string

Node type

Bounding rectangle of the node, relative a target.

If target is an HTMLElement, the bounds are relative to the HTMLElement. Any other target type will return the bounds relative to the viewport of the browser.

ParametersboundsRelativeTo

target
HTMLElement | any

No description

includeTransform
default=true
boolean

Whether to include any applied transforms on the node

ReturnsboundsRelativeTo

No description

node.boundsRelativeTo($('div'));
node.boundsRelativeTo('viewport');

Create a new svg renderer

ParameterssvgRendererFactory

treeFactory
optional
function

Node tree factory

ns
optional
string

Namespace definition

sceneFn
optional
function

Scene factory

ReturnssvgRendererFactory

A svg renderer instance

Was this page helpful?