Luzmo Analytics Components Kit

A collection of web components for building analytics interfaces with Luzmo. Built with Lit and designed to work seamlessly with Luzmo's visualization platform.

ACK produces and edits chart configuration (type, slots, options, filters). It does not render charts itself. You hand the configuration to Luzmo Embed (@luzmo/embed), which renders the visualization.

Full documentation: for detailed guides, component APIs, theming, and examples, see the Analytics Components Kit docs.

How it works

1. Configure: users interact with ACK components to pick data fields, assign them to chart slots, set options, and define filters. Each change fires an event your app captures.
2. Store: your app keeps the resulting slotsContents, options, and filters as its own state. ACK follows a one-way data flow: your app is the single source of truth.
3. Render: pass { type, slots, options, filters } into a Luzmo Embed component (luzmo-embed-viz-item for a single chart, or let luzmo-item-grid render a multi-chart layout).

Installation

npm install @luzmo/analytics-components-kit lit@^3.3.2 @luzmo/lucero@^2.0.0 @luzmo/icons@^1.0.1-alpha.46

ACK uses Lucero 2 for its design-system primitives. Package managers that do not install peer dependencies automatically must install the compatible peer versions explicitly.

To render the configured charts, also install Luzmo Embed (optional):

npm install @luzmo/embed

Optional framework wrappers for embedding: @luzmo/react-embed, @luzmo/ngx-embed, @luzmo/vue-embed.

Important: This package is linked to @luzmo/[email protected]. Ensure you are using this version when working with slotsContents, slotConfiguration, options, and grid configurations.

Authentication

Every component that fetches data needs an embed authorization token. This is a short-lived, scoped token, not your org API credentials. It follows a two-tier model:

1. Server-side: your backend uses your org API key/token (environment variables, never shipped to the client) to call the Luzmo SDK and generate an embed authorization object.
2. Client-side: your frontend fetches that object from your backend and reads the authKey / authToken fields (or id / token if you return the raw Luzmo authorization object). These are passed to every component.

Set auth-key and auth-token consistently on every component that accesses data:

<luzmo-data-field-panel
  auth-key="your-auth-key"
  auth-token="your-auth-token"
></luzmo-data-field-panel>

<luzmo-item-slot-drop-panel
  auth-key="your-auth-key"
  auth-token="your-auth-token"
  item-type="bar-chart"
>
</luzmo-item-slot-drop-panel>

For the full walkthrough (generating embed tokens, token management, and multi-tenancy), see the authentication patterns guide.

Available Components

Import individual components so bundlers can tree-shake unused code. eg.

import '@luzmo/analytics-components-kit/data-field-panel';
import '@luzmo/analytics-components-kit/item-slot-drop-panel';
import '@luzmo/analytics-components-kit/item-option-panel';

Data Fields

Present the columns and formulas from a dataset so users can pick the data they want to visualize. Also includes components to display and edit Luzmo formula/column expressions (function syntax, e.g. SUM({datasetId:columnId})). Formula components accept datasets directly via datasetsDataFields or fetch them from the Luzmo API via dataset-ids (+ auth).

| Component | Import | Description | Reference | | ---------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | | Data Field | @luzmo/analytics-components-kit/data-field | Single draggable representation of a dataset column or formula | Docs | | Data Field Panel | @luzmo/analytics-components-kit/data-field-panel | Panel listing all fields for one or more datasets, with search and dataset switching | Docs | | Formula | @luzmo/analytics-components-kit/formula | Read-only formula display: rich inline column/aggregation pills (display="rich") or plain text with inline type icons (display="text") | Docs | | Formula Editor | @luzmo/analytics-components-kit/formula-editor | Visual editor: CodeMirror input with inline column pills and nested aggregations, plus function/aggregation/dataset panels | Docs |

The editor emits debounced luzmo-expression-changed and, when auth-key/auth-token are set, DataBroker-backed luzmo-validity-changed (detail includes validating while the call is in flight). Event detail types (ExpressionChangedEventDetail, ValidityChangedEventDetail, DatasetsErrorEventDetail) and the related formula types are available from @luzmo/analytics-components-kit/types. Per-component developer-doc pages for Formula / Formula Editor are not published yet, so those rows link to the ACK overview until the docs go live.

Data Slots

Let users assign data fields to chart slots (e.g. x-axis, measure, legend). Drag-and-drop for desktop, dropdown pickers for compact/mobile layouts.

| Component | Import | Description | Reference | | ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | Item Slot Drop | @luzmo/analytics-components-kit/item-slot-drop | Drop target for a single slot | Docs | | Item Slot Drop Panel | @luzmo/analytics-components-kit/item-slot-drop-panel | All slot drop targets for a chart type (drag & drop); auto constraints | Docs | | Item Slot Picker | @luzmo/analytics-components-kit/item-slot-picker | Dropdown picker for a single slot | Docs | | Item Slot Picker Panel | @luzmo/analytics-components-kit/item-slot-picker-panel | Dropdown pickers for all slots (no drag & drop); optional dataset picker | Docs |

Prefer the panel components (data-field-panel, item-slot-drop-panel, item-slot-picker-panel) over the individual primitives: panels auto-load slot configs and apply inter-slot constraints for you (e.g. "no multiple measures when the legend is filled"). Use the primitives only when you need custom layout/styling and can handle constraints yourself.

Slot panels also surface inline calculations supplied through slotsContents. An aggregating ad-hoc measure uses formula; a non-aggregating derived dimension uses expression. Slots show compact Formula or Expression labels with matching icons; the cog menu shows the full read-only calculation under the same heading, with vertical scrolling after four rows. Override its size-dependent maximum width with --luzmo-display-settings-calculation-max-width. Clear the picker with its X action, or clear a drop target with its trash action, to return to column selection.

Item Options

Let users adjust how a chart looks and behaves (colors, labels, chart mode, legend position, ...).

| Component | Import | Description | Reference | | ----------------- | --------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Item Option | @luzmo/analytics-components-kit/item-option | Single option control (expose only what you need) | Docs | | Item Option Panel | @luzmo/analytics-components-kit/item-option-panel | Full grouped options editor for a chart type | Docs |

Individual option control editors are also exported for fully custom option UIs: item-option-action-button-group, item-option-color-palette-picker, item-option-color-picker, item-option-color-range, item-option-multi-language-field, item-option-number-field, item-option-picker, item-option-position-picker, item-option-positions-number-field, item-option-radio-button-group, item-option-slider, item-option-switch, and item-option-text-field.

Filters

| Component | Import | Description | Reference | | --------- | ----------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------- | | Filters | @luzmo/analytics-components-kit/filters | Filter editor with nested AND/OR groups | Docs |

<luzmo-filters> outputs the standard Luzmo filter format (ItemFilterGroup[] from @luzmo/dashboard-contents-types), compatible with luzmo-embed-viz-item's filters property and luzmo-item-grid items' filters. Group condition values are lowercase and / or. The published FilterGroup editor type uses the same casing, so typed consumers must migrate uppercase literals to and / or. At runtime uppercase AND / OR input is still accepted and normalized to lowercase on output.

Chart rendering

| Component | Import | Description | Reference | | --------- | ------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | Item Grid | @luzmo/analytics-components-kit/item-grid | Interactive grid to arrange, resize, and manage multiple charts (renders internally) | Docs |

To render a single chart, use luzmo-embed-viz-item from @luzmo/embed (not part of this kit); see Rendering.

Usage: Drag & Drop Data Flow

1. Add <luzmo-data-field-panel> for data fields and <luzmo-item-slot-drop-panel> for slots (or <luzmo-item-slot-picker-panel> for mobile).
2. Feed the panel its data via dataset-ids (auto-fetch, with api-url + auth) or datasetsDataFields (your own data).
3. Set item-type (e.g. bar-chart) on the slot panel and listen to luzmo-slots-contents-changed to capture the slots state.
4. Treat slotsContents as your app state (re-apply it after each change for one-way data flow) and use { type, slots, options, filters } to render the configured chart.

import '@luzmo/analytics-components-kit/data-field-panel';
import '@luzmo/analytics-components-kit/item-slot-drop-panel';

const fieldsPanel = document.querySelector('luzmo-data-field-panel')!;
const dropPanel = document.querySelector('luzmo-item-slot-drop-panel')!;

for (const panel of [fieldsPanel, dropPanel]) {
  panel.apiUrl = 'https://api.luzmo.com'; // EU (default); US: https://api.us.luzmo.com; or your VPC host
  panel.authKey = 'your-auth-key';
  panel.authToken = 'your-auth-token';
}

fieldsPanel.datasetIds = ['your-dataset-id'];

// Tell the slot panel which chart type to build slots for (bar-chart, line-chart, ...)
dropPanel.itemType = 'bar-chart';

dropPanel.addEventListener('luzmo-slots-contents-changed', (event) => {
  const { slotsContents } = (event as CustomEvent<{ slotsContents: unknown[] }>).detail;
  dropPanel.slotsContents = slotsContents; // re-apply state (one-way data flow)

  // `slotsContents` is the `slots` half of the chart state; combine it with the
  // chart `type`, `options`, and `filters` you track to render (see Rendering).
});

item-slot-drop-panel and item-slot-picker-panel emit the same luzmo-slots-contents-changed event, so you can share one handler and swap them with CSS media queries for responsive layouts.

See the Data Field Panel reference for the full list of properties, events, and examples.

Rendering

ACK produces the configuration; luzmo-embed-viz-item (from @luzmo/embed) renders it. Store the state your ACK components emit and map it onto the viz item:

| Viz item input | Controlled by | ACK component(s) | | -------------- | ------------------- | -------------------------------------------------------------------------------------- | | type | which chart to draw | slot/option components via item-type | | slots | data the chart uses | item-slot-drop, item-slot-drop-panel, item-slot-picker, item-slot-picker-panel | | options | look and behavior | item-option, item-option-panel | | filters | rows included | filters |

import '@luzmo/embed';

const vizItem = document.querySelector('luzmo-embed-viz-item')!;
vizItem.appServer = 'https://app.luzmo.com'; // EU (default); US: https://app.us.luzmo.com; or your VPC host
vizItem.apiHost = 'https://api.luzmo.com'; // EU (default); US: https://api.us.luzmo.com; or your VPC host
vizItem.authKey = 'your-auth-key';
vizItem.authToken = 'your-auth-token';

// Map your ACK-produced state onto the viz item (your app is the single source of truth)
vizItem.type = itemType; // chart type
vizItem.slots = slotsContents; // from luzmo-slots-contents-changed
vizItem.options = options; // from luzmo-options-changed
vizItem.filters = filters; // from luzmo-filters-changed

See the Flex reference and the "Using luzmo-embed-viz-item with the kit" guide in the ACK docs for every viz item property, event, and method.

Item Grid

Use <luzmo-item-grid> to render and edit a dashboard grid of charts (it embeds charts internally). Each item needs an id. Choose one of two modes:

• Uncontrolled: seed the grid once with the initial-items attribute; the grid manages layout state internally.
• Controlled: drive the grid with the items property and keep your app state in sync from the events.

const grid = document.querySelector('luzmo-item-grid')!;
grid.appServer = 'https://app.luzmo.com'; // EU (default); US: https://app.us.luzmo.com; or your VPC host
grid.apiHost = 'https://api.luzmo.com'; // EU (default); US: https://api.us.luzmo.com; or your VPC host
grid.authKey = 'your-auth-key';
grid.authToken = 'your-auth-token';

grid.items = [
  {
    id: 'chart-1',
    type: 'bar-chart',
    position: { col: 0, row: 0, sizeX: 24, sizeY: 20 },
    options: { mode: 'grouped' },
    slots: [
      // Each slot references a chart-type slot by `name` (bar-chart: y-axis, measure, legend).
      // Slot content describes the column/formula, not just its ids.
      {
        name: 'y-axis',
        content: [
          {
            datasetId: 'b35d4aaf-5f36-47a0-94e6-91a989d1635f',
            columnId: 'cb43b7f7-ede1-410f-88c1-5a93e1f9b92c',
            label: { en: 'Campaign' },
            type: 'hierarchy'
          }
        ]
      },
      {
        name: 'measure',
        content: [
          {
            datasetId: 'b35d4aaf-5f36-47a0-94e6-91a989d1635f',
            columnId: '8953c794-830c-46e5-bdb7-eee9b15dd8f5',
            label: { en: 'Opened emails' },
            type: 'hierarchy',
            aggregationFunc: 'count',
            format: ',.0f'
          }
        ]
      }
    ]
  }
];

// Controlled mode: re-apply the corrected items after each layout change
grid.addEventListener('luzmo-item-grid-layout-changed', (e) => {
  grid.items = (e as CustomEvent).detail.updatedItems;
});

Slot content is a full field descriptor (datasetId/columnId or formulaId, plus label, type, and modifiers like aggregationFunc, level, or format), not just an id pair. The easiest way to produce valid slot content is to let the drag & drop panels emit it; see Usage: Drag & Drop Data Flow.

Key events: luzmo-item-grid-ready, luzmo-item-grid-layout-changed, luzmo-item-grid-item-action (cancelable), and luzmo-item-grid-item-states-changed. Imperative helpers (addGridItem, removeGridItem, cloneGridItem, updateGridItem*) return the updated GridItemData[].

See the Item Grid reference for controlled vs uncontrolled details, all properties, events, methods, and examples.

Utilities

Import helpers from @luzmo/analytics-components-kit/utils when you need ACK-compatible data or chart-state transformations without mounting a component.

import { loadDataFieldsForDatasets, switchItem, formatter, getValueForFormatter } from '@luzmo/analytics-components-kit/utils';
import { itemTypes } from '@luzmo/analytics-components-kit/item-list';

// Load datasets with their columns/formulas, converted to component-ready data fields
const datasets = await loadDataFieldsForDatasets(['dataset-id-1'], {
  // apiUrl: EU (default) https://api.luzmo.com; US: https://api.us.luzmo.com; or your VPC host
  dataBrokerConfig: { apiUrl: 'https://api.luzmo.com', authKey: 'your-auth-key', authToken: 'your-auth-token' }
});

// Switch chart type while preserving compatible slot data
const newItem = await switchItem({ oldItemType: 'bar-chart', newItemType: 'line-chart', slots, options });

// Build a chart picker from the available chart types
const chartOptions = itemTypes.map((item) => ({ label: item.label, value: item.type }));

See the Utilities reference for signatures, return types, behavior notes, and more examples.

Types

Import TypeScript types from the dedicated entrypoint:

import type {
  DatasetDataField,
  SlotContentsChangedEventDetail,
  SlotConstraintTriggeredEventDetail,
  ItemFilterGroup,
  FilterGroup
} from '@luzmo/analytics-components-kit/types';

Runtime values are exported from the main package (or @luzmo/analytics-components-kit/utils), e.g. import { PeriodOverPeriodCondition } from '@luzmo/analytics-components-kit';.

Language & Localization

Components render labels, placeholders, and data in the language you specify via two properties:

• language: UI language (button labels, slot names, menu items). Supported: en, nl, fr, de, es.
• content-language: locale-aware formatting and data labels (number formats, date patterns, column names). Defaults to language.

<luzmo-data-field-panel
  language="nl"
  content-language="nl"
></luzmo-data-field-panel>

See the patterns guide for multi-language data labels.

Item Definitions

Each chart type has a slots config, options config, and context config. Access them through dedicated subpaths (one named export per item type):

import { itemGroups, itemTypes, itemList } from '@luzmo/analytics-components-kit/item-list';
import { barChartSlotsConfig } from '@luzmo/analytics-components-kit/item-slots-configs';
import { barChartOptionsConfig } from '@luzmo/analytics-components-kit/item-options-configs';
import { barChartContextConfig } from '@luzmo/analytics-components-kit/item-context-configs';

Use itemTypes for the complete, authoritative list of chart types (bar-chart, line-chart, donut-chart, scatter-plot, heat-map, tables, numbers, and more). See the Item Definitions guide for details.

Theming

Components are themed via global CSS custom properties (--luzmo-*). Set them on :root / html for app-wide theming, or scope them to a container. eg.

:root {
  --luzmo-primary: #4434ff;
  --luzmo-background-color: #ffffff;
  --luzmo-font-color: #333;
}

Each component also exposes --luzmo-{component}-* variables for fine-grained overrides (only override variables prefixed with --luzmo-):

luzmo-item-slot-drop {
  --luzmo-item-slot-drop-height: 3rem;
  --luzmo-item-slot-drop-border-radius: 8px;
}

Browser Support

Last 2 versions of Chrome, Firefox, Safari, and Edge.

License

Copyright © 2026 Luzmo. All rights reserved.

This package must be used according to the Luzmo Terms of Service. This license allows users with a current active Luzmo account to use this package.