UserAgent Storybook Addon

Features

- Test and simulate different user agents directly in Storybook
- Display content differently based on device and browser detection
- Go beyond simple screen-size based device detection with actual UserAgent parsing
- Use without installing additional dependencies
- Support for modern User-Agent Client Hints API for more accurate browser and device detection

Installation and Compatibility

| Storybook Version | Installation Command | Status |
| ----------------- | -------------------------------------- | ------------------------------------------ |
| v8 | npm i -D storybook-addon-useragent@8 | Current major version, actively maintained |
| v7 | npm i -D storybook-addon-useragent@7 | Legacy support |
| v6 | npm i -D storybook-addon-useragent@6 | Legacy support |

You can check for updates and upgrade to the latest version:

``bash
npm outdated
npm install storybook-addon-useragent@latest
`

Setup

Add the addon to your Storybook configuration in .storybook/main.js (or .storybook/main.ts):

`js
export default {
stories: ["../src//.mdx", "../src//.stories.@(js|jsx|mjs|ts|tsx)"],
addons: [
// Other addons...
"storybook-addon-useragent",
],
};
`

Usage

$3

Once installed, the UserAgent addon will appear in your Storybook UI. You can select from a list of predefined user agents to simulate different browsers and devices.

$3

You can customize the list of user agents available in the addon by creating a configuration file:

.storybook/userAgent.js:

`js
export const customUserAgents = [
{
name: "Windows_7-IE_11",
userAgent:
"Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko",
},
// Add more custom user agents as needed
];
`

Then import and use it in your .storybook/preview.js file:

`js
import { customUserAgents } from "./userAgent";

export const parameters = {
// Other parameters...
userAgent: customUserAgents,
};
`

$3

You can set a default UserAgent for individual stories:

`js
import React from "react";
import { UserAgentExample } from "./UserAgentExample";

export default {
title: "Example/UserAgentExample",
component: UserAgentExample,
argTypes: { useragent: { control: "text" } },
};

const Template = (args) => ;

export const IOS = Template.bind({});
IOS.args = {
useragent:
"Mozilla/5.0 (iPhone; CPU iPhone OS 12_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.1 Mobile/15E148 Safari/604.1",
};
`

Client Hints Support

This addon supports the User-Agent Client Hints API, which is a more modern and privacy-preserving way to get browser and device information than the traditional user agent string.

$3

- Browser information (brand, version)
- Platform information (platform, platformVersion)
- Architecture information (architecture, bitness)
- Mobile status detection
- Device model information

The addon automatically uses Client Hints in modern browsers while falling back to traditional User-Agent string parsing in older browsers.

Browser Compatibility

This addon uses modern browser APIs to simulate user agents:

| Browser Category | Support Level | Browsers | Notes |
| ---------------- | ------------- | ------------------------------- | -------------------------------------------- |
| Full Support | ✅ | Chrome 89+, Edge 89+, Opera 75+ | All features work as expected |
| Good Support | ⚠️ | Firefox 90+, Safari 16.4+ | Most features work, some limitations |
| Limited | ⚠️ | Safari 15-16.3, Firefox 78-89 | UserAgent string works, Client Hints limited |
| Minimal | ⚠️ | IE11, Legacy Edge | Basic functionality only |

In browsers with limited support, the addon falls back to basic functionality while showing appropriate warnings.

Performance Considerations

The UserAgent addon has minimal impact on Storybook performance:

- First-time initialization: ~5-20ms
- Subsequent UserAgent changes: ~1-5ms
- Memory usage: Negligible (<1MB)

In rare cases, changing UserAgent in rapid succession may cause temporary UI flickering. We recommend:

- Avoid changing UserAgent in loops
- Allow sufficient time between UserAgent changes (>100ms)
- Consider using the addon only in specific stories that require it

Testing Across Environments

$3

This example shows how to test a responsive component across multiple devices:

`js
// ResponsiveComponent.stories.js
import { ResponsiveComponent } from "./ResponsiveComponent";

export default {
title: "Components/ResponsiveComponent",
component: ResponsiveComponent,
};

// Basic template
const Template = (args) => ;

// Create stories for different device types
export const Desktop = Template.bind({});
Desktop.args = {
// Default desktop user agent is used
};

export const iPhone = Template.bind({});
iPhone.args = {
useragent:
"Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.0 Mobile/15E148 Safari/604.1",
};

export const Android = Template.bind({});
Android.args = {
useragent:
"Mozilla/5.0 (Linux; Android 12; Pixel 6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.104 Mobile Safari/537.36",
};
`

You can then create a testing matrix to ensure your components work across browsers:

1. Test baseline functionality in your default browser
2. Use the UserAgent addon to test across different simulated environments
3. Verify with real devices for critical features

Security Considerations

This addon modifies the navigator object to simulate different user agents. While we've implemented safeguards:

- Some browser security policies may restrict these modifications
- The addon uses proxies and fallback mechanisms when possible
- Changes are isolated to the Storybook iframe
- All modifications are reverted when the story changes

Troubleshooting

$3

| Issue | Possible Cause | Solution |
| ----------------------------------------- | -------------------------------- | ----------------------------------------------- |
| UserAgent not changing | Browser security restrictions | Try a different browser (Chrome works best) |
| UI components not responding to UserAgent | Component not using UA detection | Ensure component checks navigator.userAgent |
| Stories show error when changing UA | Timing or cleanup issues | Reload the story or check for errors in console |
| Inconsistent behavior | Caching or stale state | Clear browser cache and restart Storybook |

$3

If you encounter issues with the UserAgent addon:

1. Check browser console for errors
2. Verify UserAgent is actually changing by adding:
`js
console.log(window.navigator.userAgent);
`
3. Test with a simple component first to isolate the issue
4. Try using the UserAgent addon in isolation (disable other addons)

Real-world Use Cases

$3

Test how your components adapt to different device characteristics beyond just screen size:

`jsx
// DeviceResponsiveMenu.jsx
import React from "react";
import { useUserAgent } from "./useUserAgent";

export function DeviceResponsiveMenu({ items }) {
const { isMobile, isTablet, isMacOS } = useUserAgent();

// Adapt menu based on device type
return (