> Part of the walkerOS documentation. Project overview and full index: <https://www.walkeros.io/llms.txt>

# Storybook addon

The walkerOS Storybook addon integrates event tracking visualization into Storybook. It enables developers to inspect walker attributes, monitor real-time events, and visually highlight tagged elements while building components.

## Installation[​](#installation "Direct link to Installation")

```
npm install --save-dev @walkeros/storybook-addon
```

## Setup[​](#setup "Direct link to Setup")

Register the addon in your Storybook configuration:

```
// .storybook/main.ts
const config: StorybookConfig = {
  addons: ['@walkeros/storybook-addon'],
};

export default config;
```

## Configuration[​](#configuration "Direct link to Configuration")

Optionally customize the addon behavior in your preview file:

```
// .storybook/preview.ts
const preview: Preview = {
  parameters: {
    walkerOS: {
      prefix: 'data-elb',      // Custom data attribute prefix
      autoRefresh: true,       // Auto-refresh on story changes
    },
  },
};

export default preview;
```

| Option        | Type      | Default      | Description                                                |
| ------------- | --------- | ------------ | ---------------------------------------------------------- |
| `prefix`      | `string`  | `'data-elb'` | Data attribute prefix for walker attributes                |
| `autoRefresh` | `boolean` | `true`       | Automatically refresh events when story or controls change |

## Features[​](#features "Direct link to Features")

The addon panel provides three tabs for inspecting walkerOS data:

### Events tab[​](#events-tab "Direct link to Events tab")

Displays all detected walkerOS events in the current story's DOM. Click "Update events" to manually refresh the event list.

### Live events tab[​](#live-events-tab "Direct link to Live events tab")

Captures events in real-time as you interact with components. Shows timestamps for each event and stores up to 50 events. Use the "Clear" button to reset.

### Skeleton tab[​](#skeleton-tab "Direct link to Skeleton tab")

Shows a hierarchical tree of the entities found in the DOM, with each entity's properties resolved onto it the way the walker reads them:

* Generic (`data-elb-`) and scoped (`data-elb_`) values are shown on the entities that consume them, labeled by origin (`G` for generic, `S` for scoped; directly declared properties are unlabeled)
* Expandable/collapsible entity structure
* Click to view element markup
* Attribute counts by type

### Visual highlighting[​](#visual-highlighting "Direct link to Visual highlighting")

Toggle buttons highlight elements with different attribute types:

| Attribute | Color  | Data Attribute            |
| --------- | ------ | ------------------------- |
| Globals   | Cyan   | `data-elbglobals`         |
| Context   | Yellow | `data-elbcontext`         |
| Entity    | Green  | `data-elb`                |
| Property  | Red    | `data-elb-*`, `data-elb_` |
| Action    | Purple | `data-elbaction`          |

Multiple highlights can be active simultaneously, displaying layered outlines.

## Usage in stories[​](#usage-in-stories "Direct link to Usage in stories")

Import `dataElbArgTypes` to add walkerOS controls to your stories:

```
import { dataElbArgTypes } from '@walkeros/storybook-addon';

export default {
  title: 'Components/Button',
  argTypes: {
    ...dataElbArgTypes,
  },
};
```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

**No events detected:**

* Verify components have `data-elb` attributes
* Check the prefix matches your configuration
* Click "Update events" to manually refresh

**Highlights not showing:**

* Ensure the story iframe has loaded
* Toggle highlights off and on again
* Check browser console for errors

## Next steps[​](#next-steps "Direct link to Next steps")

* **[Storybook Demo](https://storybook.walkeros.io/)**: See the addon in action
* **[HTML Attributes](https://www.walkeros.io/docs/sources/web/browser/tagging/html-attributes.md)**: Learn walker attribute syntax
* **[Browser Source](https://www.walkeros.io/docs/sources/web/browser.md)**: Understand DOM event capture