navio

Navio API

Every option and method this build exposes, generated from src/params.js. The same table drives the settings panel and navio.describe(), so all three agree by construction.

import navio from "navio";           // UMD global: `navio`

const nv = navio(d3.select(el), { height: 400 });
nv.id("id");                          // a real key, not the row index
nv.data(rows);
nv.addAllAttribs();                   // one column per field

d3 and popper.js are external - Navio reads them off the host page rather than bundling them. d3 v7 or later.

Options

Pass any of these in the options object, or set them on the instance. A few are read only once (see the notes); nv.setOptions({...}) applies a batch in an order that works.

Layout

Option Type Default What it does
height number 600 The widget’s extent along the RECORD axis - screen height when horizontal, width when vertical. More room means fewer rows share a pixel line.
orientation horizontal | vertical "horizontal" Which way the two axes run. “horizontal” puts attributes across and records down; “vertical” transposes both. All geometry goes through toXY, so everything follows.
attribWidth number 15 How wide each column is drawn. Narrow columns fit more attributes on screen; wide ones make individual values easier to compare.
levelsSeparation number 40 Horizontal gap between drill-down levels. The filter chips are drawn in this gap, so a wider gap gives them more room.
margin number 10 Blank space around the drawing, inside the widget.
x0 number 0 Offset of the whole drawing from the container’s left edge.
y0 number 100 Room for the rotated column headers, before the records start. Measured from the labels by default; moving this slider takes that over and keeps whatever you set.
autoHeaderSpace boolean true Size y0 from the labels actually drawn, on every update. Off means y0 is yours. Note the band is ADDED to height rather than taken out of it, so the data area is height either way.
headerMaxSpace number 140 The most the header band will reserve. Past this the labels still draw in full, but the extra hangs above the widget instead of growing it - and what it hangs over, it takes clicks from. Ignored in vertical orientation, which never spills.
theme auto | light | dark "auto" Which way the widget’s CHROME is coloured - labels, counts, borders, the panel, the tooltip. “auto” reads the background behind the widget and picks ink to suit, re-reading on every redraw. The DATA colours never follow it: inverting a categorical scale would change what a colour means. The widget stays transparent in every theme, so it sits on the page’s own background.

Headers

Option Type Default What it does
showAttribTitles boolean true Draw the column header labels. Off costs no header band at all.
attribRotation number -45 Angle of the column headers, in degrees. 0 is horizontal and -90 is vertical; steeper angles fit longer names above narrow columns. Ignored in vertical orientation, where labels are upright.
attribFontSize number 13 Size of the column header labels. Capped by the column width, so widening a column can be what actually makes a header legible.
attribFontSizeSelected number 32 Size a header grows to while the pointer is over it, so a rotated label can be read without changing the layout.
showSelectedAttrib boolean true Draw the derived column marking which rows are selected.
showSequenceIDAttrib boolean true Draw the derived “sequential Index” column. Worth knowing that its label is the widest one on a default widget, so it sets the header band on its own however short your own attribute names are.

Filtering

Option Type Default What it does
nestedFilters boolean true Each filter opens a new level showing the rows that survived it. Off keeps a single level and re-filters it in place - a second, much less travelled code path; see docs/ai/FILTERING-MODEL.md.
clickTolerance number 4 How far the pointer may drift during a click and still count as a click rather than a range selection. Raise it if selecting a single value is difficult.
filterFontSize number 8 Size of the filter chips under the levels.
fmtCounts function d3.format(",.0d") Formats the per-level record counts. Any (number) -> string will do.

Rows

Option Type Default What it does  
divisionsThreshold number 4 How many pixels a row must occupy before dividing lines are drawn between rows. Below this the lines would be thicker than the rows.  
divisionsColor colour null null Colour of the lines drawn between rows when they are tall enough. null follows the theme; a colour you set is used in both.
levelConnectionsColor colour "rgba(205, 220, 163, 0.5)" Colour of the ribbons linking a level to the rows it came from.  
linkColor colour "#ccc" Colour of the curves drawn for links passed via nv.links().  
nullColor colour "#ffedfd" Colour for a missing value, in every scale type. The same in both themes on purpose: a gap is not a value, and it should look like the same gap on a dark page as on a light one.  

Tooltip

Option Type Default What it does  
tooltipBgColor colour null null Background of the hover tooltip. null follows the theme; a colour you set is used in both.
tooltipFontSize number 12 Font size inside the hover tooltip. Read once, when the tooltip is built.  
tooltipMargin number 50 How far the tooltip sits from the pointer.  
tooltipArrowSize number 10 Size of the tooltip’s arrow, in pixels.  

Attributes

Option Type Default What it does
id string "__seqId" Which field identifies a row. Defaults to the row’s position, which is enough until rows are re-sorted or linked - set it to a real key for links, and for a selection that survives sorting.
maxNumDistinctForCategorical number 30 addAllAttribs calls an attribute categorical below this many distinct values.
maxNumDistinctForOrdered number 90 addAllAttribs calls an attribute ordered below this many distinct values, and text above it. Set to Infinity to never choose text.
howManyItemsShouldSearchForNotNull number 100 How many rows to look through for a non-null value when guessing an attribute’s type.
addAllAttribsRecursionLevel number Infinity How deep addAllAttribs descends into nested objects.
addAllAttribsIncludeObjects boolean false Let addAllAttribs make a column out of an object-valued field.
addAllAttribsIncludeArrays boolean false Let addAllAttribs make a column out of an array-valued field.
digitsForText number 2 How many leading characters a text attribute is bucketed by.
digitsForObjects number Infinity As digitsForText, for stringified objects and arrays.
stringify function JSON.stringify Turns object values into strings for bucketing. Pass d => d to make this cheap when you know the values are already strings.

Colours

Option Type Default What it does  
defaultColorInterpolator function d3.interpolateBlues Interpolator for sequential (numeric) attributes.  
defaultColorInterpolatorDate function d3.interpolatePurples Interpolator for date attributes.  
defaultColorInterpolatorDiverging function d3.interpolateBrBG Interpolator for diverging attributes - chosen automatically only when the data actually crosses zero.  
defaultColorInterpolatorOrdered function d3.interpolateOranges Interpolator for ordered attributes.  
defaultColorInterpolatorText function d3.interpolateGreys Interpolator for text attributes.  
defaultColorInterpolatorObject function d3.interpolateGreens Interpolator for object and array attributes.  
defaultColorRangeBoolean array ["#a1d76a","#e9a3c9","white"] Colours for true, false and null, in that order.  
defaultColorRangeSelected array ["white","#b5cf6b"] Colours for unselected and selected rows in the derived selected column.  
defaultColorCategorical array function navio.palettes.nameable Palette for categorical attributes: an array of colours, or a function (n) => colours called with the number of categories. navio.palettes holds the built-ins - nameable (the default, 50 colours that stay distinguishable under colour blindness and can all be named), distinct, mokole, category10 (the pre-0.3.0 look), tableau10, turbo, rainbow, sinebow. Too few colours for the data warns rather than silently repeating.

Settings panel

Option Type Default What it does
settings boolean true Whether the settings panel and its gear button exist at all. Read once, inside data().
settingsPlacement below | beside | over "below" Where the panel opens relative to the widget. A modal placement was built and removed: it centres in the VIEWPORT, so with two Navios the panel appeared nowhere near the one it belonged to.
settingsMaxAttribRows number 10 Past this many columns the attribute list scrolls inside its own box rather than pushing the rest of the panel below the fold.
attribPicker function null Replace the panel’s attribute list. (names, {value, onChange, move, instanceId, types, getType, setType, canSetType}) -> HTMLElement.
settingsKey string undefined Where panel settings are remembered in localStorage. null turns persistence off. Undefined means the key is derived from the page and the CONTAINER’S id - and with no id there is no key, so nothing is stored: a per-page construction counter was tried and swapped two widgets’ settings whenever they were built in a different order.

Debug

Option Type Default What it does
DEBUG boolean false Trace internals to the console. Inherited from navio.DEBUG at construction, so set THAT before constructing to catch the first data() call.

Methods

Method What it is for
data(rows) -> nv \| rows Set the rows to display, or read them back. Navio never writes to your rows.
addAllAttribs(names?) -> nv Add a column per field, guessing each type. Usually the only setup call needed after data().
id(field) -> nv \| field Name the field that identifies a row. Needed for links and for stable selection across re-sorts.
addSequentialAttrib(attrib, scale?) -> nv Add one column with an explicit type. Also: Categorical, Ordered, Date, Diverging, Text, Boolean, Object.
getFilters() -> filters[][] The filter chain, one array per level. This is what to bind Navio-to-Navio on.
setFilters(filters[][]) -> nv Rebuild the filter chain, reproducing a saved drill-down.
getSelected() -> rows The rows currently selected. This - not the filter chain - is what NavioWidget.value carries.
isSelected(rowOrIndex) -> boolean Is this row selected? Use this rather than looking for a property on the row; Navio keeps selection in a side table.
setSelectedRows(rows) -> nv Select exactly these rows.
getRowsAtLevel(level = 0) -> rows The rows that survived down to a given level of the chain.
sortBy(attrib, desc = false, level?) -> nv Sort a level. Deliberately does not change which rows are selected - see docs/ai/FILTERING-MODEL.md.
setAttribVisible(attrib, visible = true) -> nv Show or hide one column, by name or by attribute value.
getHiddenAttribs() -> names Which columns are hidden. setHiddenAttribs(names) replaces the set.
setAttribType(attrib, type) -> nv Re-type a column after the fact - when the guess was wrong, or a numeric code is really a category.
getSettings() -> object The panel’s state as plain JSON. setSettings(cfg) applies it, and deliberately leaves filters and selection alone.
getOptions() -> object Every option and its current value, in the shape the constructor accepts.
setOptions(options) -> nv Apply several options at once, in an order that works - some are read only once.
onChange(fn) -> nv Call fn whenever the selection changes.
links(links) -> nv \| links Draw curves between rows. Endpoints are resolved on every redraw, because d3-force rewrites them in place.
update(opts?) -> nv Redraw. hardUpdate() also rebuilds the scales.
destroy() -> nv Remove everything Navio added, including its listeners on body and the class it put on your container.

Things that are not obvious

This site is open source. Improve this page.