Patterns

When you combine multiple components in the same application, a handful of shared patterns keep everything consistent and maintainable. This page covers those patterns: authentication, data configuration, state syncing, and layout, so you can wire things up correctly from the start.

Authentication and token management

Every component that fetches data from the Luzmo API needs an embed authorization token . This token is not the same as your org API credentials -- it is a short-lived, scoped token that you generate server-side and pass to the browser.

For a full walkthrough of how to request and manage embed tokens, see Generating an Embed token .

The two-tier model works as follows:

1. Server-side -- your backend uses your API key and 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.

Passing embed tokens to components

All components that access data accept the same two properties: auth-key and auth-token . Set them consistently on every component instance:

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

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

<luzmo-embed-viz-item
  auth-key="your-auth-key"
  auth-token="your-auth-token"
  app-server="https://app.luzmo.com"
  api-host="https://api.luzmo.com">
</luzmo-embed-viz-item>

Theming

All components share a single set of CSS custom properties prefixed with --luzmo- . Because custom properties inherit through the DOM, you can theme every component at once by setting variables on a common ancestor -- typically :root or html .

App-wide overrides

:root {
  --luzmo-primary: #0052cc;
  --luzmo-background-color: #fafafa;
  --luzmo-font-family: 'Inter', sans-serif;
  --luzmo-font-color: #1a1a1a;
  --luzmo-border-radius: 6px;
}

Scoped overrides

You can also scope overrides to a container so that components in different parts of your app look different:

.dark-sidebar {
  --luzmo-background-color: #1e1e1e;
  --luzmo-font-color: #e0e0e0;
  --luzmo-border-color: #333;
}

Mapping your own design tokens

If your app already has a design-token system, you can easily map your tokens to the Luzmo variables in one place:

:root {
  --luzmo-primary: var(--brand-primary);
  --luzmo-secondary: var(--brand-accent);
  --luzmo-background-color: var(--surface-default);
  --luzmo-font-color: var(--text-default);
  --luzmo-font-family: var(--font-stack);
  --luzmo-border-radius: var(--radius-m);
  --luzmo-border-color: var(--border-default);
}

Full list of theme tokens

The most commonly overridden variable groups are:

For a complete overview, these are all global theme tokens along with their default values:

Individual components also expose component-specific CSS variables (e.g. --luzmo-item-slot-drop-panel-gap ). See each component's reference page for the full list.

Language and localization

These components render labels, placeholders, and tooltips in the language you specify. There are two properties to be aware of:

• language -- controls the UI language (button labels, slot names, menu items). Supported values: en , nl , fr , es , de .

• content-language -- controls locale-aware formatting and data labels (number formats, date patterns). Defaults to the value of language .

Multi-language data labels

Dataset columns and formulas store their display names as language maps. When you provide data to components (for example through datasetsDataFields ), include translations for every language you want to support:

const datasets = [
  {
    id: 'ds_1',
    name: { en: 'Sales', nl: 'Verkoop', fr: 'Ventes' },
    columns: [
      {
        id: 'col_revenue',
        name: { en: 'Revenue', nl: 'Omzet', fr: 'Revenu' },
        type: 'numeric'
      }
    ]
  }
];

The component will pick the translation that matches its active language (or content-language for data labels).

How ACK maps to Flex SDK

Use ACK to let users configure a visualization, then pass that state into Flex SDK to render it. ACK components help users build and edit the chart configuration, while luzmo-embed-viz-item and framework wrappers such as luzmo-viz-item consume that configuration and draw the chart. Your application sits between the two and remains the single source of truth.

In practice, the wiring pattern is straightforward:

const itemType = 'bar-chart';

let slotsContents = [];
let options = {};
let filters = [];

// ACK updates your application state through component events.
// Your application then passes that state into Flex SDK.
vizItem.type = itemType;
vizItem.slots = slotsContents;
vizItem.options = options;
vizItem.filters = filters;

This is the core relationship between both libraries: ACK gives users the controls to shape the chart, and Flex SDK renders the resulting configuration.