Building your own dashboard studio

npm install @luzmo/analytics-components-kit
# Optional (individual chart embedding/editing): npm install @luzmo/embed
# Optional (chart icons): npm install @luzmo/icons

// ACK editor components (individual imports for optimal bundle size)
import '@luzmo/analytics-components-kit/data-field-panel';
import '@luzmo/analytics-components-kit/item-slot-drop';
import '@luzmo/analytics-components-kit/item-slot-picker';
import '@luzmo/analytics-components-kit/item-slot-drop-panel';
import '@luzmo/analytics-components-kit/item-slot-picker-panel';
import '@luzmo/analytics-components-kit/filters';
import '@luzmo/analytics-components-kit/item-grid';
import '@luzmo/analytics-components-kit/item-option-panel';
// Or replace the above with a single import to register all ACK components:
// import '@luzmo/analytics-components-kit';

// Embed library - provides the <luzmo-embed-viz-item> chart component
import '@luzmo/embed';

<!-- luzmo-embed-viz-item: renders a single Flex chart.
     type: the chart type identifier (e.g. 'column-chart', 'line-chart', 'pie-chart')
     appServer/apiHost: configured via environment variables
     authKey/authToken: passed as arguments, fetched server-side before loading -->
<luzmo-embed-viz-item
  id="vizItem"
  type="column-chart"
></luzmo-embed-viz-item>

<script type="module">
  import '@luzmo/embed';

  // Fetch Embed Authorization token from your backend before initializing the component.
  // The token should provide "can use" access to the datasets referenced below.
  // See: https://developer.luzmo.com//guide/dashboard-embedding--generating-an-authorization-token
  async function initializeChart() {
    const { authKey, authToken } = await fetch('/api/embed-token').then(r => r.json());

    const vizItem = document.getElementById('vizItem');

    // Configure API endpoints from environment variables (e.g., VITE_LUZMO_API_HOST)
    vizItem.appServer = import.meta.env.VITE_LUZMO_APP_SERVER || 'https://app.luzmo.com';
    vizItem.apiHost = import.meta.env.VITE_LUZMO_API_HOST || 'https://api.luzmo.com';

    // Set authorization credentials from your backend
    vizItem.authKey = authKey;
    vizItem.authToken = authToken;

    // slots: define what data the chart displays. Each slot maps a named chart dimension
    // (e.g. 'measure', 'x-axis', 'legend') to one or more dataset column references.
    vizItem.slots = [
      {
        name: 'measure',          // Slot name — determines the chart dimension (y-axis for column chart)
        content: [{
          label: { en: 'Revenue' },
          datasetId: 'your-dataset-id',   // ID of the Luzmo dataset
          columnId: 'your-column-id',     // ID of the column within that dataset
          type: 'numeric',                // Column data type: 'numeric', 'hierarchy', or 'datetime'
          aggregationFunc: 'sum'          // Aggregation: 'sum', 'count', 'avg', 'min', 'max', etc.
        }]
      }
    ];
    // options: chart-type-specific display settings (colors, sorting, labels, axes, etc.)
    vizItem.options = {
      display: {
        title: false
      }
    };
    // filters: array of filter groups that narrow which data rows are queried (see Filters section)
    vizItem.filters = [];
  }

  initializeChart();
</script>

<!-- luzmo-grid: renders multiple items in a drag-and-resize grid layout.
     columns: number of grid columns (higher = more precise positioning)
     row-height: height in px of each grid row
     view-mode: (optional) disables drag, resize, and item actions for read-only dashboards
     placement-item-actions-menu: (optional) controls actions menu position (e.g., "right-start", "top-end")
     auth credentials and API endpoints are set via JavaScript -->
<luzmo-grid
  id="grid"
  language="en"
  columns="48"
  row-height="16"
></luzmo-grid>

<!-- Example with view-mode enabled for read-only dashboards: -->
<!-- <luzmo-grid id="grid" language="en" columns="48" row-height="16" view-mode></luzmo-grid> -->

<!-- Example with custom action menu placement: -->
<!-- <luzmo-grid id="grid" language="en" columns="48" row-height="16" placement-item-actions-menu="right-start"></luzmo-grid> -->

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

  // Fetch Embed Authorization token from your backend before initializing the grid.
  // The token should provide "can use" access to all datasets referenced in grid items.
  // See: https://developer.luzmo.com//guide/dashboard-embedding--generating-an-authorization-token
  async function initializeGrid() {
    const { authKey, authToken } = await fetch('/api/embed-token').then(r => r.json());

    const grid = document.getElementById('grid');

    // Configure API endpoints from environment variables (e.g., VITE_LUZMO_API_HOST)
    grid.appServer = import.meta.env.VITE_LUZMO_APP_SERVER || 'https://app.luzmo.com';
    grid.apiHost = import.meta.env.VITE_LUZMO_API_HOST || 'https://api.luzmo.com';
    grid.authKey = authKey;
    grid.authToken = authToken;

    // items: array of chart definitions. Each item has its own type, slots, options,
    // filters, and position within the grid.
    grid.items = [
      {
        id: 'chart-1',               // Unique identifier for this grid item
        type: 'column-chart',        // Chart type identifier
        options: {},                  // Chart-type-specific display settings
        filters: [],                 // Filter groups applied to this chart
        slots: [
          {
            name: 'measure',         // Slot name — determines the chart dimension
            content: [{
              label: { en: 'Revenue' },
              columnId: 'your-column-id',
              datasetId: 'your-dataset-id',
              type: 'numeric',
              aggregationFunc: 'sum'
            }]
          }
        ],
        // position: grid placement. col/row are 0-based; sizeX/sizeY are in grid units.
        // With columns=48, sizeX=24 means the item spans half the grid width.
        position: { col: 0, row: 0, sizeX: 24, sizeY: 20 }
      },
      {
        id: 'chart-2',
        type: 'line-chart',
        options: {},
        filters: [],
        slots: [
          {
            name: 'measure',
            content: [{
              label: { en: 'Sales' },
              columnId: 'your-other-column-id',
              datasetId: 'your-dataset-id',
              type: 'numeric',
              aggregationFunc: 'sum'
            }]
          }
        ],
        position: { col: 24, row: 0, sizeX: 24, sizeY: 20 }
      }
    ];

    // Fired when users drag or resize items. e.detail.items contains the full
    // updated items array with new positions — persist this to save the layout.
    grid.addEventListener('luzmo-item-grid-changed', (e) => {
      console.log('Grid layout changed:', e.detail.items);
    });

    // Fired when a user clicks an action button on a grid item.
    // action: 'edit' | 'clone' | 'delete' — use 'edit' to open a config panel.
    // id: the item's id; items: the full items array after the action.
    grid.addEventListener('luzmo-item-grid-item-action', (e) => {
      const { action, id, items } = e.detail;
      console.log(`Action "${action}" on item "${id}"`);
    });

    // Optional: Apply a custom theme to style the grid and its items.
    // See the "Theme" section below for the full customTheme object structure.
    // grid.theme = customTheme;
  }

  initializeGrid();
</script>

<!-- Chart type selector grid -->
<div id="chartTypeGrid" style="display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 8px;"></div>

<!-- luzmo-embed-viz-item renders a single chart; it re-renders automatically when
     type, slots, options, or filters change. -->
<luzmo-embed-viz-item
  id="vizItem"
  type="column-chart"
></luzmo-embed-viz-item>

<script type="module">
  // itemTypes: list of all available item types (column-chart, line-chart, pie-chart, etc.)
  import { itemTypes } from '@luzmo/analytics-components-kit/item-list';
  // switchItem: migrates slot data + options when switching between item types
  import { switchItem } from '@luzmo/analytics-components-kit/utils';
  import '@luzmo/embed';

  // Fetch Embed Authorization token from your backend before initializing the chart.
  // The token should provide access to the datasets referenced in the chart.
  // See: https://developer.luzmo.com/guide/dashboard-embedding--generating-an-authorization-token
  async function initializeChartEditor() {
    const { authKey, authToken } = await fetch('/api/embed-token').then(r => r.json());

    const chartTypeGrid = document.getElementById('chartTypeGrid');
    const vizItem = document.getElementById('vizItem');

    // Configure API endpoints from environment variables (e.g., VITE_LUZMO_API_HOST)
    vizItem.appServer = import.meta.env.VITE_LUZMO_APP_SERVER || 'https://app.luzmo.com';
    vizItem.apiHost = import.meta.env.VITE_LUZMO_API_HOST || 'https://api.luzmo.com';
    vizItem.authKey = authKey;
    vizItem.authToken = authToken;

    // Filter to only item types that visualize data (excludes decorative items like text boxes)
    const chartOptions = itemTypes
      .filter(item => item.containsData)
      .map(item => ({
        label: item.label,   // Human-readable name, e.g. "Column chart"
        value: item.type      // Identifier used in type prop, e.g. "column-chart"
      }));

    let currentType = 'column-chart';
    // slots: define what data the chart displays. Each slot has a name (e.g. 'measure',
    // 'x-axis', 'legend') and content array of column references.
    let currentSlots = [
      {
        name: 'measure',          // Slot name — determines the chart dimension (y-axis for column chart)
        content: [{
          label: { en: 'Revenue' },
          datasetId: 'your-dataset-id',   // ID of the Luzmo dataset
          columnId: 'your-column-id',     // ID of the column within that dataset
          type: 'numeric',                // Column data type: 'numeric', 'hierarchy', or 'datetime'
          aggregationFunc: 'sum'          // Aggregation: 'sum', 'count', 'avg', 'min', 'max', etc.
        }]
      }
    ];
    // options: chart-type-specific display settings (colors, sorting, labels, axes, etc.)
    let currentOptions = {};
    vizItem.slots = currentSlots;
    vizItem.options = currentOptions;

    const applyChartType = async (nextType) => {
      const previousType = currentType;

      // switchItem redistributes slot contents to compatible slots in the new chart type.
      // Numeric fields go to numeric/mixed slots; categorical fields go to categorical/mixed slots.
      const result = await switchItem({
        oldItemType: previousType,
        newItemType: nextType,
        slots: currentSlots,
        options: currentOptions
      });

      currentType = nextType;
      currentSlots = result.slots;       // Migrated slots for the new chart type
      currentOptions = result.options || {};

      vizItem.setAttribute('type', currentType);
      vizItem.slots = currentSlots;
      vizItem.options = currentOptions;

      // Tip: feed currentSlots into luzmo-item-slot-drop-panel or
      // luzmo-item-slot-picker-panel, and currentOptions into luzmo-item-option-panel
      // to keep editor panels in sync after switching.
    };

    chartOptions.forEach((option) => {
      const button = document.createElement('button');
      button.type = 'button';
      button.style.display = 'flex';
      button.style.gap = '6px';
      button.style.alignItems = 'center';
      button.style.padding = '6px 8px';
      button.textContent = option.label;
      button.addEventListener('click', () => void applyChartType(option.value));
      chartTypeGrid.appendChild(button);
    });
  }

  initializeChartEditor();
</script>

<div style="display: flex; gap: 16px;">
  <!-- luzmo-data-field-panel: browsable list of all dataset columns.
       Users drag fields from here into slot drop targets.
       dataset-picker: shows a dataset switcher when multiple datasets are provided.
       search="auto": shows search input when column count exceeds threshold (default 20).
       search-threshold: customize when search appears (e.g., 10 columns instead of 20). -->
  <luzmo-data-field-panel
    id="fieldsPanel"
    language="en"
    size="m"
    dataset-picker
    search="auto"
    search-threshold="10"
  ></luzmo-data-field-panel>

  <!-- luzmo-item-slot-drop-panel: renders all drop targets for a given chart type.
       item-type: must match the chart's type so the correct slots are shown
       (e.g. column-chart has 'measure', 'x-axis', 'legend' slots). -->
  <luzmo-item-slot-drop-panel
    id="dropPanel"
    item-type="column-chart"
    language="en"
    size="m"
  ></luzmo-item-slot-drop-panel>

  <!-- The chart that visualizes the current slot configuration -->
  <luzmo-embed-viz-item
    id="vizItem"
    type="column-chart"
  ></luzmo-embed-viz-item>
</div>

<script type="module">
  import '@luzmo/analytics-components-kit/data-field-panel';
  import '@luzmo/analytics-components-kit/item-slot-drop-panel';
  import '@luzmo/embed';

  // Fetch Embed Authorization token from your backend before initializing editor components.
  // The token should provide access to all datasets referenced in the editor.
  // See: https://developer.luzmo.com/guide/dashboard-embedding--generating-an-authorization-token
  async function initializeSlotEditor() {
    const { authKey, authToken } = await fetch('/api/embed-token').then(r => r.json());

    const fieldsPanel = document.getElementById('fieldsPanel');
    const dropPanel = document.getElementById('dropPanel');
    const vizItem = document.getElementById('vizItem');

    // Configure API endpoints from environment variables (e.g., VITE_LUZMO_API_HOST)
    const apiHost = import.meta.env.VITE_LUZMO_API_HOST || 'https://api.luzmo.com';
    const appServer = import.meta.env.VITE_LUZMO_APP_SERVER || 'https://app.luzmo.com';

    // Set API configuration for all components
    fieldsPanel.apiUrl = apiHost;
    fieldsPanel.authKey = authKey;
    fieldsPanel.authToken = authToken;

    dropPanel.apiUrl = apiHost;
    dropPanel.authKey = authKey;
    dropPanel.authToken = authToken;

    vizItem.appServer = appServer;
    vizItem.apiHost = apiHost;
    vizItem.authKey = authKey;
    vizItem.authToken = authToken;

    // datasetIds: which datasets to show fields for in the panel.
    // The component fetches column metadata from the API automatically.
    fieldsPanel.datasetIds = ['your-dataset-id'];

    // slotsContents: shared state between the drop panel and the chart.
    // Same format as vizItem.slots — array of { name, content } objects.
    let slotsContents = [];
    let options = {};
    let filters = [];
    dropPanel.slotsContents = slotsContents;
    vizItem.options = options;
    vizItem.filters = filters;

    // Fired when a user drops a field into a slot, removes a field, or reorders fields.
    // e.detail.slotsContents: the full updated slots array — pass it to both the
    // drop panel (to keep its UI in sync) and the chart (to re-render).
    dropPanel.addEventListener('luzmo-slots-contents-changed', (e) => {
      slotsContents = e.detail.slotsContents;
      dropPanel.slotsContents = slotsContents;
      vizItem.slots = slotsContents;
    });
  }

  initializeSlotEditor();
</script>

<!-- luzmo-item-slot-picker-panel: dropdown-based alternative to drag-and-drop.
     Users pick fields from a dropdown inside each slot.
     item-type: must match the chart's type so the correct slots are shown.
     dataset-picker: adds a dataset switcher dropdown above the slot pickers. -->
<luzmo-item-slot-picker-panel
  id="pickerPanel"
  item-type="column-chart"
  language="en"
  size="m"
  dataset-picker
></luzmo-item-slot-picker-panel>

<luzmo-embed-viz-item
  id="vizItem"
  type="column-chart"
></luzmo-embed-viz-item>

<script type="module">
  import '@luzmo/analytics-components-kit/item-slot-picker-panel';
  import '@luzmo/embed';

  // Fetch Embed Authorization token from your backend before initializing picker panel.
  // The token should provide access to all datasets used in the picker.
  // See: https://developer.luzmo.com//guide/dashboard-embedding--generating-an-authorization-token
  async function initializePicker() {
    const { authKey, authToken } = await fetch('/api/embed-token').then(r => r.json());

    const pickerPanel = document.getElementById('pickerPanel');
    const vizItem = document.getElementById('vizItem');

    // Configure API endpoints from environment variables (e.g., VITE_LUZMO_API_HOST)
    const appServer = import.meta.env.VITE_LUZMO_APP_SERVER || 'https://app.luzmo.com';
    const apiHost = import.meta.env.VITE_LUZMO_API_HOST || 'https://api.luzmo.com';

    // Set API configuration for all components
    pickerPanel.apiUrl = apiHost;
    pickerPanel.authKey = authKey;
    pickerPanel.authToken = authToken;

    vizItem.appServer = appServer;
    vizItem.apiHost = apiHost;
    vizItem.authKey = authKey;
    vizItem.authToken = authToken;

    // datasetIds: which datasets to show fields for in the picker.
    // The component fetches column metadata from the API automatically.
    pickerPanel.datasetIds = ['your-dataset-id'];

    // slotsContents: shared state between the picker panel and the chart.
    // Same format as vizItem.slots — array of { name, content } objects.
    let slotsContents = [];
    let options = {};
    let filters = [];
    pickerPanel.slotsContents = slotsContents;
    vizItem.options = options;
    vizItem.filters = filters;

    // Fired when a user selects or removes a field from any slot dropdown.
    // e.detail.slotsContents: the full updated slots array — pass it to both the
    // picker panel (to keep its UI in sync) and the chart (to re-render).
    pickerPanel.addEventListener('luzmo-slots-contents-changed', (e) => {
      slotsContents = e.detail.slotsContents;
      pickerPanel.slotsContents = slotsContents;
      vizItem.slots = slotsContents;
    });
  }

  initializePicker();
</script>

<luzmo-edit-filters
  id="editFilters"
  language="en"
  size="m"
></luzmo-edit-filters>

<luzmo-embed-viz-item
  id="vizItem"
  type="column-chart"
></luzmo-embed-viz-item>

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

  async function initializeFilters() {
    const { authKey, authToken } = await fetch('/api/embed-token').then(r => r.json());

    const editFilters = document.getElementById('editFilters');
    const vizItem = document.getElementById('vizItem');

    const apiHost = import.meta.env.VITE_LUZMO_API_HOST || 'https://api.luzmo.com';
    const appServer = import.meta.env.VITE_LUZMO_APP_SERVER || 'https://app.luzmo.com';

    editFilters.apiUrl = apiHost;
    editFilters.authKey = authKey;
    editFilters.authToken = authToken;

    vizItem.appServer = appServer;
    vizItem.apiHost = apiHost;
    vizItem.authKey = authKey;
    vizItem.authToken = authToken;

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

    editFilters.filters = [
      {
        condition: 'and',
        filters: [
          {
            expression: '? > ?',
            parameters: [
              { columnId: 'volume-column-id', datasetId: 'your-dataset-id' },
              100
            ]
          },
          {
            expression: '? in ?',
            parameters: [
              { columnId: 'product-column-id', datasetId: 'your-dataset-id' },
              ['Earthly Shoes', 'Luzmo Sneakers']
            ]
          }
        ],
        subGroups: [
          {
            condition: 'or',
            filters: [
              {
                expression: '? in ?',
                parameters: [
                  { columnId: 'location-column-id', datasetId: 'your-dataset-id' },
                  ['New York']
                ]
              },
              {
                expression: '? in ?',
                parameters: [
                  { columnId: 'location-column-id', datasetId: 'your-dataset-id' },
                  ['London']
                ]
              }
            ],
            subGroups: []
          }
        ]
      }
    ];

    editFilters.addEventListener('luzmo-filters-changed', (e) => {
      vizItem.filters = e.detail.filters;
    });
  }

  initializeFilters();
</script>

<div style="display: flex; gap: 16px;">
  <!-- luzmo-item-option-panel: renders all configuration controls for the chart type.
       item-type: must match the chart's type so the correct options are shown.
       options: current chart options object (kept in sync with the chart).
       slots: current chart slots array (some options depend on which data is assigned). -->
  <luzmo-item-option-panel
    id="optionPanel"
    item-type="column-chart"
    language="en"
    size="m"
  ></luzmo-item-option-panel>

  <!-- For individual controls instead of the full panel, use luzmo-item-option:
  <luzmo-item-option
    id="modeOption"
    item-type="column-chart"
    option-key="mode"
    language="en"
    size="m"
  ></luzmo-item-option>
  -->

  <!-- The chart that visualizes the current option configuration -->
  <luzmo-embed-viz-item
    id="vizItem"
    type="column-chart"
  ></luzmo-embed-viz-item>
</div>

<script type="module">
  import '@luzmo/analytics-components-kit/item-option-panel';
  // For individual controls, import: '@luzmo/analytics-components-kit/item-option'
  import '@luzmo/embed';

  async function initializeOptionEditor() {
    const optionPanel = document.getElementById('optionPanel');
    const vizItem = document.getElementById('vizItem');

    const appServer = import.meta.env.VITE_LUZMO_APP_SERVER || 'https://app.luzmo.com';
    const apiHost = import.meta.env.VITE_LUZMO_API_HOST || 'https://api.luzmo.com';

    vizItem.appServer = appServer;
    vizItem.apiHost = apiHost;

    let slotsContents = [
      {
        name: 'measure',
        content: [{
          label: { en: 'Total Sales' },
          columnId: 'sales-column-id',
          datasetId: 'your-dataset-id',
          type: 'numeric',
          aggregationFunc: 'sum'
        }]
      },
      {
        name: 'x-axis',
        content: [{
          label: { en: 'Country' },
          columnId: 'country-column-id',
          datasetId: 'your-dataset-id',
          type: 'hierarchy'
        }]
      }
    ];

    let options = {
      mode: 'grouped',
      display: {
        legend: true
      }
    };

    let filters = [];

    optionPanel.slots = slotsContents;
    optionPanel.options = options;
    vizItem.slots = slotsContents;
    vizItem.options = options;
    vizItem.filters = filters;

    // Fired when a user changes any option setting.
    // e.detail.options: the updated full options object — pass it to both the
    // option panel (to keep its UI in sync) and the chart (to re-render).
    optionPanel.addEventListener('luzmo-options-changed', (e) => {
      options = e.detail.options;
      optionPanel.options = options;
      vizItem.options = options;
    });
  }

  initializeOptionEditor();
</script>