Multiple charts in grid

Introduction

luzmo-item-grid is a grid layout component that lets users arrange, resize, and manage multiple charts on a grid. Use it when you want to give end users an interactive canvas for building or customizing a multi-chart view.

The grid renders each chart internally using luzmo-embed-viz-item , so you don't need to wire up the embed component yourself. You do need to pass the same auth-key and auth-token credentials you would use for any embedded visualization.

This reference uses the controlled items pattern. In controlled mode, your app owns the items state and re-assigns event.detail.updatedItems after luzmo-item-grid-layout-changed and item actions that return updates (for example clone and delete ). If you want grid-managed state, use initial-items instead.

Use the <luzmo-item-grid> element in your HTML.

Interactive example

Controlled vs uncontrolled

luzmo-item-grid supports two state ownership models:

• Controlled : your app owns the state of the grid, and passes updates from the grid back into the component.

• Uncontrolled : the grid component owns the state after initial setup, you can still listen to its updates to keep track of the changes.

Choose separately for:

• grid items ( items for controlled, initial-items for uncontrolled)

• item action state ( item-states for controlled, initial-item-states for uncontrolled)

Use controlled when state must sync with other app state, business logic, persistence, or collaboration. Use uncontrolled for simpler standalone usage where internal grid state is enough.

Uncontrolled

Use uncontrolled mode when you want a simpler setup and the grid can manage state internally.

For grid items :

1. Pass initial-items once.

2. Do not re-assign items after each event.

3. Use the grid's imperative methods when you want to update items from your own UI (for example toolbar buttons, forms, or keyboard shortcuts).

4. Optionally listen to events for to keep track of any changes sinside the grid.

For item action state :

1. Pass initial-item-states once (optional).

2. Let the grid manage toggle state internally.

3. Optionally listen to luzmo-item-grid-item-states-changed if you want visibility into state changes (e.g. to open/close specific UI elements in your application based on the item action state).

See Uncontrolled code example below .

Controlled

Use controlled mode when your application should be the source of truth (for example: undo/redo, collaborative editing, syncing with other UI elements, etc.).

For grid items :

1. Pass items .

2. Listen to luzmo-item-grid-layout-changed and luzmo-item-grid-item-action .

3. When event.detail.updatedItems is present, assign it back to your app state, then pass that state back to items .

4. To add a dashboard item in controlled mode, either call addGridItem(newItem) or append the item in your own items state and pass that new array to items . Both approaches trigger luzmo-item-grid-layout-changed , and the event contains updatedItems with the latest item positions.

For item action state (toggle actions like edit-data , item-options ):

1. Pass item-states .

2. Listen to luzmo-item-grid-item-states-changed .

3. Assign event.detail.updatedItemStates back to your app state, then pass that state back to item-states .

See Controlled code example below .

Properties

Use HTML attributes for primitive values in markup, and JS properties for objects, arrays, and programmatic updates.

Events

Methods

These methods are especially useful in uncontrolled mode ( initial-items ), where the grid manages internal state and you still want to trigger item updates programmatically.

Most mutating methods return GridItemData[] (the updated items array), so you can optionally persist or inspect the latest layout in your app.

Types

The component entrypoint exports several component-owned types for grid items and actions. Shared types used in GridItemData properties come from the public types barrel.

import '@luzmo/analytics-components-kit/item-grid';

import type {
  Action,
  ActionGroup,
  DefaultActionType,
  GridItemData,
  GridItemPatch,
  GridItemPositionPatch,
  GridItemRenderer,
  GridItemSizePatch,
  InputActionGroup,
  ItemStates
} from '@luzmo/analytics-components-kit/item-grid';
import type {
  ItemFilterGroup,
  Placement,
  ThemeConfig,
  VizItemSlot,
  VizItemType
} from '@luzmo/analytics-components-kit/types';

GridItemData['options'] uses VizItemOptions from @luzmo/dashboard-contents-types , not from the ACK public types barrel. The grid's event detail types are not currently public exports; refer to the event payload shapes in the Events table above.

CSS Variables

All CSS variables in this list can be set on luzmo-item-grid { ... } .

Code examples

Uncontrolled

<luzmo-item-grid id="dashboardGrid"></luzmo-item-grid>

<script type="module">
  import '@luzmo/analytics-components-kit/item-grid';

  const dashboardGrid = document.getElementById('dashboardGrid');
  dashboardGrid.initialItems = [
    {
      id: 'sales-chart',
      type: 'bar-chart',
      options: {},
      slots: [],
      filters: [],
      position: { col: 0, row: 0, sizeX: 24, sizeY: 18 }
    }
  ];
  dashboardGrid.initialItemStates = {};

  dashboardGrid.addGridItem({
    id: 'profit-chart',
    type: 'line-chart',
    options: {},
    slots: [],
    filters: [],
    position: { sizeX: 24, sizeY: 18 }
  });
  dashboardGrid.updateGridItemPosition('profit-chart', { col: 24, row: 0 });
  dashboardGrid.activateItemAction('profit-chart', 'item-options');
</script>

Controlled

<luzmo-item-grid
  id="dashboardGrid"
  app-server="https://app.luzmo.com"
  api-host="https://api.luzmo.com"
  auth-key="your-auth-key"
  auth-token="your-auth-token"
  language="en"
  columns="48"
  row-height="16"
></luzmo-item-grid>

<script type="module">
  import '@luzmo/analytics-components-kit/item-grid';

  let items = [
    {
      id: 'sales-chart',
      type: 'bar-chart',
      options: { mode: 'stacked' },
      slots: [
        {
          name: 'measure',
          content: [
            {
              datasetId: '6f2f9f80-3d80-4f45-9d5c-6d1b2e4a8c11',
              columnId: '2a7c5e41-6d8f-4b2a-93c1-7e5d4f6a8b12',
              label: { en: 'Revenue' },
              type: 'numeric',
              aggregationFunc: 'sum'
            }
          ]
        }
      ],
      position: { col: 0, row: 0, sizeX: 24, sizeY: 18 }
    },
    {
      id: 'margin-chart',
      type: 'line-chart',
      options: {},
      slots: [
        {
          name: 'measure',
          content: [
            {
              datasetId: '6f2f9f80-3d80-4f45-9d5c-6d1b2e4a8c11',
              columnId: '3b8d6f52-7e9a-4c3b-a4d2-8f6e5a7b9c23',
              label: { en: 'Margin' },
              type: 'numeric',
              aggregationFunc: 'sum'
            }
          ]
        }
      ],
      position: { col: 24, row: 0, sizeX: 24, sizeY: 18 }
    }
  ];

  let itemStates = {};
  const dashboardGrid = document.getElementById('dashboardGrid');

  dashboardGrid.items = items;
  dashboardGrid.itemStates = itemStates;

  dashboardGrid.addEventListener('luzmo-item-grid-layout-changed', (event) => {
    if (event.detail.updatedItems) {
      items = event.detail.updatedItems;
      dashboardGrid.items = items;
    }
  });

  dashboardGrid.addEventListener('luzmo-item-grid-item-action', (event) => {
    if (event.detail.updatedItems) {
      items = event.detail.updatedItems;
      dashboardGrid.items = items;
    }

    console.log('item action', event.detail.action, event.detail.item.id);
  });

  dashboardGrid.addEventListener('luzmo-item-grid-item-states-changed', (event) => {
    itemStates = event.detail.updatedItemStates;
    dashboardGrid.itemStates = itemStates;
  });
</script>