Visualize, debug, and validate walkerOS event tracking in your Storybook stories. Real-time event capture with visual DOM highlighting for data-attribute based tagging.
npm install @walkeros/storybook-addonA Storybook addon that integrates walkerOS tagging support for data collection
and tracking validation. Visualize, debug, and validate walkerOS events in your
stories.
- 📊 Events Tab: View all detected walkerOS events with JSON syntax
highlighting
- 🔴 Live Events Tab: Real-time event capture as you interact with
components
- 🎯 Visual Highlighting: Toggle highlights for Context, Entity, Property,
and Action attributes
- 🔄 Auto-refresh: Updates automatically when navigating stories or changing
controls
- ⚙️ Custom Prefix Support: Configure custom data attribute prefixes
- 🚀 Zero Configuration: Works out of the box with walkerOS data attributes
| Addon Version | Storybook Version | Status |
| ------------- | ----------------- | --------------------------- |
| ^0.2.x | ^9.0.0 | ✅ Current (Active Support) |
| ^1.0.0 | ^10.0.0 | 📋 Planned |
> Note: Storybook 10 support is planned for v1.0.0. See
> STORYBOOK_10_MIGRATION.md for migration
> details.
``bash`
npm install --save-dev @walkeros/storybook-addon
`ts`
// .storybook/main.ts
const config: StorybookConfig = {
addons: ['@walkeros/storybook-addon'],
};
1. Install and register the addon
2. Add walkerOS tracking to your components:
`tsx
import { tagger } from '../utils/tagger';
export const Button = ({ label, onClick }) => {
const trackingProps = tagger('button').data({ label }).action('click').get();
return (
);
};
`
3. Use in stories:
`ts`
export const Primary: Story = {
args: {
label: 'Button',
dataElb: {
entity: 'button',
action: 'click',
data: { category: 'primary' },
},
},
};
Configure a custom prefix in your Storybook preview:
`ts`
// .storybook/preview.ts
const preview: Preview = {
parameters: {
walkerOS: {
prefix: 'data-elb',
autoRefresh: true,
},
},
};
Update your tagger configuration to match:
`ts`
// utils/tagger.ts
const taggerInstance = createTagger({
prefix: 'data-elb',
});
Shows all walkerOS events detected in the current story's DOM. Click "Update
events" to manually refresh.
Captures events in real-time as you interact with components. Events are
automatically sent to the panel via the walker collector.
Use the highlight toggles to visually identify different types of walkerOS
attributes:
- Context: Yellow outline for context attributes
- Entity: Green outline for entity attributes
- Property: Red outline for property attributes
- Action: Purple outline for action attributes
`ts`
import { DataElb, dataElbArgTypes } from '@walkeros/storybook-addon';
`ts`
interface DataElb {
entity?: string;
trigger?: string;
action?: string;
data?: WalkerOS.Properties;
context?: WalkerOS.Properties;
globals?: WalkerOS.Properties;
link?: Record
}
`ts`
export default {
argTypes: {
...dataElbArgTypes,
// Adds a walkerOS object control to your story
},
};
| Option | Type | Default | Description |
| ------------- | --------- | ------------ | ---------------------------------------------------- |
| prefix | string | 'data-elb' | Data attribute prefix (must match your walker setup) |autoRefresh
| | boolean | true | Auto-refresh events on story/control changes |
- Ensure components have walkerOS attributes: data-elb, data-elb-*`, etc.
- Check prefix matches between addon config and tagger config
- Try manual refresh with "Update events" button
- Verify walker is properly initialized with matching prefix
- Check browser console for walker initialization errors
- Ensure components generate events when clicked/interacted with
- Confirm prefix configuration matches in both addon and tagger
- Check that elements have the expected data attributes in DOM inspector
MIT © elbwalker GmbH