Luzmo Data Visualization

Entry-point for building Flex charts in code in your application — ad-hoc, code-first visualizations with full slot/options control.

To embed an existing saved dashboard or chart by id, use core. To build a brand-new custom chart component when no built-in type fits, use custom-charts.

Doc Retrieval

• developer.luzmo.com is Luzmo's first-party, allowlisted documentation domain, maintained by the same publisher as this skill.
• If the Luzmo MCP search_docs tool is available, use it first to find the right pages: it returns matching passages with their live developer.luzmo.com or Academy URLs. Fetch the .md URL when you need the full page or anything newer than the server's docs build. Without MCP, go straight to the .md URLs below.
• Before starting implementation, you MUST consult the exact relevant https://developer.luzmo.com/.../*.md docs and their referenced URLs for implementation details.
• Use https://developer.luzmo.com/llms.txt and/or /llms-full.txt for discovery only.

[CRITICAL] Setup Rules

Read these rules BEFORE implementing ANY visualization — they prevent 80% of rendering failures:

Security Checkpoint

Generate embed tokens server-side:

• Embed token generated server-side using API credentials
• Only token id (as authKey) and token (as authToken) passed to frontend
• API keys NEVER in client-side code

If ANY checkbox is unchecked, STOP and fix before proceeding.

For full auth/embed-token guidance, see core.

For localhost CORS or reconnecting /realtime sockets, see core/references/local-development-proxy.md: proxy /0.1.0 and /realtime through the app origin, set Flex apiHost to that origin, and keep appServer pointed directly at the Luzmo app host.

1. Component Naming (Framework-Specific)

Using wrong names causes "component not found" errors:

[ERROR] WRONG:

// Vanilla JS - missing "embed"
<luzmo-viz-item type="bar-chart" />

[OK] CORRECT:

// Vanilla JS - includes "embed"
<luzmo-embed-viz-item type="bar-chart" />

2. Flex Chart Sizing (CRITICAL - Most Common Failure)

Without explicit dimensions → chart will be INVISIBLE (0 height)

Rule: Set dimensions on BOTH container AND component

┌─────────────────────────────────────────┐
   │  Container div                          │  ◄── height: 400px;
   │  (your wrapper element)                 │      width:  100%;
   │                                         │
   │   ┌──────────────────────────────────┐  │
   │   │ <luzmo-embed-viz-item>           │  │  ◄── height: 100%;
   │   │   ↑                              │  │      width:  100%;
   │   │   Without BOTH dimensions set    │  │
   │   │   on the container AND the       │  │
   │   │   component, height collapses    │  │
   │   │   to 0 and the chart is invisible│  │
   │   └──────────────────────────────────┘  │
   │                                         │
   └─────────────────────────────────────────┘

[ERROR] WRONG - Renders nothing visible:

// Container has no height
<div>
  <luzmo-embed-viz-item type="bar-chart" />
</div>
// Result: 0px height, invisible chart

[OK] CORRECT - Set BOTH:

// Container with explicit size
<div style={{ height: '400px', width: '100%' }}>
  <luzmo-embed-viz-item 
    type="bar-chart"
    height="400px"
    width="100%"
  />
</div>

Example (wrong - chart will be invisible):

<div>
  <luzmo-embed-viz-item type="bar-chart" ...></luzmo-embed-viz-item>
</div>

Context ID (Unique Per Chart)

contextId must be unique across all chart instances on the page. Reusing the same contextId causes conflicts and unexpected behavior.

Recommended pattern:

// Single chart
contextId="chart-1"

// Multiple charts - use a pattern
contextId={`chart-${dashboardId}-${itemId}`}
contextId={`${section}-${index}`}

Localized Strings (REQUIRED)

All user-facing text properties MUST be localized objects, never plain strings:

Properties that require localization:

• title
• label (in slots)
• description
• Any other user-visible text

Correct:

{
  label: { en: "Revenue" }
}

Wrong:

{
  label: "Revenue"  // [ERROR] This will cause errors
}

Chart Options: Title Gotcha

Avoid using the title option unless explicitly needed. If you do use it:

Correct:

options: {
  title: { en: "My Chart Title" }
}

Wrong:

options: {
  title: "My Chart Title"  // [ERROR] Not localized
}

// OR

options: {
  title: { title: { en: "My Chart Title" } }  // [ERROR] Nested, wrong structure
}

Slot Configuration Requirements

Every dataset-backed Flex chart slot must follow these rules (for charts fed by inlineData, see "Inline Data" below — slots use field instead):

Always required:

• datasetId (UUID of the dataset)

Recommended:

• label (localized object: { en: "Label" }) - any user-facing label you provide must be localized

Column-based slots (dimensions and measures using columns):

• columnId (UUID of the column)
• type (hierarchy, numeric, or datetime)

Formula-based slots (measures using formulas):

• formulaId (UUID of the formula) - when using this, do NOT include columnId, type, or aggregationFunc

Type-specific requirements:

Special aggregation functions requiring a secondary column:

rate and weightedaverage require an additional aggregationWeight field that specifies the denominator or weight column:

{
  datasetId: "...",
  columnId: "...",          // primary (numerator / value) column
  label: { en: "Revenue per Unit" },
  type: "numeric",
  aggregationFunc: "weightedaverage",  // or "rate"
  aggregationWeight: {
    datasetId: "...",       // dataset of weight/denominator column
    columnId: "..."         // weight or denominator column id
  }
}

Optional but recommended:

• subtype (if column has one): coordinates, currency, duration, hierarchy_element_expression, ip_address, topography

Before configuring any chart: Consult the chart-specific documentation for available slots and options:

• URL pattern: https://developer.luzmo.com/flex/charts/{chart-type}.md
• Chart catalog: https://developer.luzmo.com/guide/flex--chart-docs.md
• JSON schemas per chart:
  • Slots: https://developer.luzmo.com/assets/json-schemas/0.1.99/{chartType}-slots.schema.json
  • Options: https://developer.luzmo.com/assets/json-schemas/0.1.99/{chartType}-options.schema.json

Different chart types have different required and optional properties; consult the schema (and any relevant guides it references) before guessing field shapes.

Inline Data (Charts Without a Dataset)

Since @luzmo/embed / @luzmo/react-embed / @luzmo/vue-embed 8.1.0, @luzmo/ngx-embed 10.1.0 and @luzmo/react-native-embed 7.1.0 (7.1.1 escapes quotes in props), a Flex viz item can render records you pass in through the inlineData property instead of querying a dataset. Source: the inlineData row in each package README and CHANGELOG (not yet on developer.luzmo.com; the public Flex JSON schemas 0.1.99 predate slot field).

Shape: inlineData = { records: [...], sourceDescription?: string, topojson?: ... }. Each populated slot content names its record property with field (no datasetId, columnId, formulaId):

const chart = document.querySelector('luzmo-embed-viz-item'); // type="bar-chart"
chart.slots = [
  { name: 'measure', content: [{ field: 'revenue', type: 'numeric', label: { en: 'Revenue' } }] },
  { name: 'y-axis',  content: [{ field: 'product', type: 'hierarchy', label: { en: 'Product' } }] }
];
chart.inlineData = {
  sourceDescription: 'Revenue per product from the billing service',
  records: [
    { product: { id: 'analytics', name: { en: 'Analytics' } }, revenue: 124000 },
    { product: { id: 'embedded',  name: { en: 'Embedded' } },  revenue: 81000 }
  ]
};

React: <LuzmoVizItemComponent inlineData={...} />; Angular: [inlineData]; Vue: :inlineData.

Constraints (enforced by the chart; violations show the chart's error state):

• Records are final: no aggregation, sorting, ranking, limiting, dashboard filters, or period-over-period. records: [] renders "no data" (it does not fall back to a query).
• Every populated slot content needs a non-empty field, and fields must be unique across all slots.
• Period-over-period on a slot content is rejected; the payload is capped at 2 MB.
• Not supported for regular-table, pivot-table, custom-chart, venn-diagram, or filter types (date-filter, date-comparison-filter, dropdown-filter, search-filter, slicer-filter, slider-filter).
• ACK's luzmo-item-grid does not forward inlineData (ACK 1.0.8); render inline charts with the standalone viz item.

[SECURITY] Inline records are treated as already authorized. Embed-token filters and parameter_overrides are NOT applied to them. Filter rows to what the viewer may see on your server before sending them to the browser.

Flex Theming and Dark Backgrounds

Flex viz-items do not have a theme prop. The component API props are appServer, apiHost, authKey, authToken, type, slots, options, contextId, and optional interaction props. For standalone Flex viz-items, put chart styling in options (for example options.theme, options.color, or chart-specific options after fetching the chart schema).

When using dark chart styling, the chart content can adapt, but the container background does not.

Required: Set an explicit dark background on the container element.

Example:

<div style="background-color: #1a1a2e;">
  <luzmo-embed-viz-item id="sales-chart" type="bar-chart"></luzmo-embed-viz-item>
</div>

document.querySelector('#sales-chart').options = {
  theme: {
    itemsBackground: '#1a1a2e',
    colors: ['#FFB74D', '#FFEB3B', '#FF4081'],
    font: { fontFamily: 'Inter, system-ui, sans-serif', fontSize: 13 },
  },
}

Bundled References

• references/flex-charts.md — Flex chart embedding. Covers code-first chart creation, slot/options configuration, chart-type catalog, JSON schema access, and advanced slot patterns (formulas, bins, datetime levels).

Common Rendering Issues

If your visualization isn't working as expected, check these common issues:

Common Mistakes

Each pitfall below includes the error you'll see, why it fails, a frequency marker ([WARNING] VERY COMMON / [WARNING] COMMON / [WARNING] OCCASIONAL), and where to escalate if you need deeper troubleshooting.

[ERROR] Using plain strings instead of localized objects ([WARNING] VERY COMMON):

label: "Revenue"  // Wrong

You'll see: Invalid label / Invalid title / Invalid localized string format. Why this fails: Luzmo requires every user-facing text field to be a language object so it can handle i18n consistently. A bare string has no language tag, so the validator rejects it. [OK] Always use localized objects:

label: { en: "Revenue" }  // Correct

See also: troubleshooting → "Title and Label Errors".

[ERROR] Reusing the same contextId ([WARNING] COMMON):

<luzmo-embed-viz-item contextId="chart-1" />
<luzmo-embed-viz-item contextId="chart-1" />  // Conflict!

You'll see: charts swapping data on reload, filter changes affecting the wrong chart, stale data not refreshing. Why this fails: contextId is the key Luzmo uses to deduplicate state and queries across chart instances. Two charts sharing one id share state — chaos follows. [OK] Make each contextId unique:

<luzmo-embed-viz-item contextId="chart-1" />
<luzmo-embed-viz-item contextId="chart-2" />  // Good

See also: troubleshooting → "Chart Rendering But Shows Wrong Data".

[ERROR] Forgetting dimensions on Flex charts ([WARNING] VERY COMMON — most common failure mode):

<luzmo-embed-viz-item type="bar-chart" />  // Invisible

You'll see: nothing on the page. No error. DevTools shows the element with 0px height. Why this fails: Flex charts use their container's box for layout — without explicit dimensions on BOTH container and component, the chart computes 0px and renders invisibly. [OK] Always set height and width on BOTH:

<div style="height: 400px; width: 100%;">
  <luzmo-embed-viz-item style="height: 100%; width: 100%;" />
</div>

See also: troubleshooting → "Component Not Rendering At All".

[ERROR] Missing required slot fields ([WARNING] COMMON):

{
  datasetId: "...",
  columnId: "..."
  // Missing: label, type, aggregationFunc
}

You'll see: Missing aggregationFunc (for numeric measures), Missing level (for datetime/hierarchy), or Invalid label. Why this fails: Slots are typed configurations — different column types need different bookkeeping. A numeric measure without aggregationFunc is ambiguous; a datetime without level can't be bucketed. [OK] Include all required fields:

{
  datasetId: "...",
  columnId: "...",
  label: { en: "Total Sales" },
  type: "numeric",
  aggregationFunc: "sum"
}

See also: troubleshooting → "Slot Configuration Errors" and the chart-specific doc at https://developer.luzmo.com/flex/charts/{chart-type}.md.

[ERROR] Treating inlineData like a dataset ([WARNING] COMMON):

chart.slots = [{ name: 'measure', content: [{ datasetId: '...', columnId: '...', field: 'revenue', aggregationFunc: 'sum' }] }];
chart.inlineData = { records: rawTransactions };   // per-transaction rows, all tenants

You'll see: one bar per raw row instead of totals, rows from other tenants visible, or a slot-binding error. Why this fails: Inline records skip the query engine, so nothing is aggregated or filtered, and token filters never touch them. [OK] Send final, already-filtered results and bind by field only:

chart.slots = [{ name: 'measure', content: [{ field: 'revenue', type: 'numeric', label: { en: 'Revenue' } }] }, /* ... */];
chart.inlineData = { records: totalsForThisViewer };   // aggregated + filtered server-side

[ERROR] Using deprecated <cumul-*> tag names ([WARNING] OCCASIONAL but increasing):

<luzmo-viz-item type="bar-chart" ...></luzmo-viz-item>  <!-- Wrong: missing "embed" in vanilla JS -->

You'll see: Component not found in console, or the element renders as inert markup. Why this fails: The product rebranded from Cumul.io to Luzmo and the tag/component names changed. [OK] Use the current Luzmo names:

<luzmo-embed-viz-item type="bar-chart" ...></luzmo-embed-viz-item>

Avoid

• Using wrong component names for the target framework — always verify against the framework table before generating code.
• Omitting explicit height/width on Flex chart containers (causes invisible 0-height chart).
• Reusing the same contextId across multiple chart instances on the same page.
• Recommending GET/PUT/DELETE calls — the API is POST-only; direct any auth or API questions to core.
• Passing unfiltered or other-tenant rows as inlineData — token filters do not apply to inline records.

Hand Off

When to escalate to other skills:

• WHEN the user wants to embed an existing saved dashboard or chart by id → use core
• WHEN the user mentions API credentials, embed tokens, or auth setup → use core
• WHEN the user has tenants/customers and data must be isolated → use multitenancy (SECURITY CRITICAL)
• WHEN the user wants end-users to CREATE or EDIT charts (not just view) → use analytics-studio
• WHEN the user wants to brand, theme, or apply custom CSS → use theming
• WHEN the user needs to connect a data source or push data → use data-integration
• WHEN the user wants AI/natural-language data Q&A → use ai-analytics
• WHEN the user needs to build a brand-new custom chart component (no built-in type fits) → use custom-charts
• WHEN a chart "just doesn't work" or shows an error → use troubleshooting FIRST, then return here for the fix

This skill does NOT cover:

• Embedding an existing saved dashboard or chart by id (use core)
• Configuring authentication, embed tokens, or SDK setup (use core)
• Self-service editors or ACK component configuration (use analytics-studio)
• Server-side resource CRUD scripts (use resource-management)

Canonical Sources

• Index: https://developer.luzmo.com/llms.txt, https://developer.luzmo.com/llms-full.txt
• API: https://developer.luzmo.com/api/{action}{Resource}.md
• Guides: https://developer.luzmo.com/guide/*.md
• Flex charts: https://developer.luzmo.com/flex/charts/{type}.md

If content exists on developer.luzmo.com, link — do not duplicate specs here.