Options & Callbacks

All three entry points (olliVis, olliDiagram, olli) accept the same optional third argument.

import type { OlliOptions } from 'olli';

OlliOptions

interface OlliOptions {
  initialPreset?: string;
  initialCustomization?: Record<string, Customization>;
  initialSelection?: Selection;
  callbacks?: {
    onFocus?: (navId: NavNodeId) => void;
    onSelection?: (selection: Selection) => void;
  };
}

initialPreset

Name of a preset to apply on mount. For olliVis, the built-in presets are 'detailed', 'standard', and 'minimal'.

olliVis(spec, container, { initialPreset: 'standard' });

initialCustomization

Per-role recipe overrides applied on mount. Each key is a role name; each value is a Customization:

olliVis(spec, container, {
  initialCustomization: {
    datum: {
      role: 'datum',
      recipe: [
        { token: 'name', brevity: 'short' },
        { token: 'index', brevity: 'short' },
      ],
    },
  },
});

A Customization has two fields:

• role — which type of node this applies to
• recipe — an ordered list of { token: string, brevity: 'short' | 'long' } entries

Note: if the user has previously saved their own preferences via the description settings dialog, those localStorage settings take priority over initialPreset and initialCustomization on subsequent loads.

initialSelection

A Selection to seed on mount. This sets the initial selection state of the tree.

olliVis(spec, container, {
  initialSelection: { and: [{ field: 'region', equal: 'North' }] },
});

callbacks

Subscribe to changes at mount time. These are equivalent to calling handle.onFocusChange and handle.onSelectionChange after mount.

olliVis(spec, container, {
  callbacks: {
    onFocus: (navId) => console.log('focus:', navId),
    onSelection: (sel) => console.log('selection:', sel),
  },
});

Verbosity presets

A preset is a bundle of per-role recipes. Applying a preset swaps every role's description recipe at once. olliVis ships three:

Preset	Description
detailed	Long descriptions everywhere. Announces field lists, aggregate statistics, and more on data items.
standard	Short descriptions with a balanced set of tokens. A reasonable default.
minimal	Short descriptions with fewer tokens.

The three presets correspond to the verbosity levels from the CHI '24 customization paper.

Switch presets at mount time with initialPreset, or at runtime with handle.applyPreset('standard'). For finer control, use handle.setCustomization(role, recipe).

Next

• OlliHandle — the full handle API.
• Entry Points — which function to call.