Storybook addon
The walkerOS Storybook addon adds a panel to Storybook in which you inspect walker attributes, watch events as they fire and highlight tagged elements while you build components.
Installation
The addon needs Storybook 10.
npm install --save-dev @walkeros/storybook-addonSetup
Register the addon in your Storybook configuration:
// .storybook/main.ts
const config: StorybookConfig = {
addons: ['@walkeros/storybook-addon'],
};
export default config;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
The addon panel provides three tabs for inspecting walkerOS data:
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
Captures events in real-time as you interact with components. Shows timestamps for each event and stores up to 50 events. Use the "Clear Events" button to reset.
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, marked(generic)or(scoped); directly declared properties are unmarked - Expandable/collapsible entity structure
- Click to view element markup
- The tab title counts the entities found; "Update skeleton" refreshes the tree
Visual highlighting
Toggle buttons highlight elements with different attribute types:
| Attribute | Color | Data Attribute |
|---|---|---|
| Globals | Blue | data-elbglobals |
| Context | Orange | data-elbcontext |
| Entity | Green | data-elb |
| Property | Red | data-elb-*, data-elb_ |
| Action | Purple | data-elbaction |
Several highlights can be on at once; they show as layered outlines.
Usage in stories
Import dataElbArgTypes to add a walkerOS control to your stories:
import { dataElbArgTypes } from '@walkeros/storybook-addon';
export default {
title: 'Components/Button',
argTypes: {
...dataElbArgTypes,
},
};It adds one object control, dataElb (the exported DataElb type: entity,
action, trigger, data, context, globals, link), in a walkerOS
category. Your component receives it as the dataElb arg and renders the
attributes from it, for example with the
tagger.
Troubleshooting
No events detected:
- Verify components have
data-elbattributes - 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
- Storybook Demo: See the addon in action
- HTML Attributes: Learn walker attribute syntax
- Browser Source: Understand DOM event capture