user-agents

The dataset is built from a snapshot of the last 24 hours of real-world browser traffic and is refreshed daily.

Key characteristics:

• Real-world weighting: User agents are not selected with uniform probability. Each profile is weighted according to its real-world usage frequency. For example, Chrome on Windows will appear much more often than niche configurations.
• Dynamic updates: Because the data is refreshed daily, older browser versions naturally phase out as they disappear from real-world traffic.

The project is transitioning from v1 (UMD bundle) to v2 (Native ESM/CJS).

Key changes in v2:

• Rewritten in TypeScript with exported types for UserAgentData and Filter.
• Built with tsup for native ESM and CJS support.
• Removed Function class inheritance to resolve Content Security Policy (CSP) errors in browser extensions.

Migration: Both versions share an identical API surface and receive the same daily data, so upgrading should be straightforward. To install the v2 version, use the @next tag:

npm install user-agents@next

You can install the user-agents package using npm, pnpm, or yarn.

# With npm
npm install user-agents

# With pnpm
pnpm install user-agents

# With yarn
yarn add user-agents

To efficiently generate many user agents with the same configuration, initialize one UserAgent instance with your filters and then call that instance as a function (or use .random()) to produce new random instances using the same filter set.

import UserAgent from 'user-agents';

const userAgent = new UserAgent({ platform: 'Win32' });
const userAgents = Array(1000).fill().map(() => userAgent());

To generate a random user agent and its associated browser fingerprint, instantiate the UserAgent class. You can retrieve the raw user agent string using .toString() or access the detailed fingerprint data via the .data property.

import UserAgent from 'user-agents';

const userAgent = new UserAgent();
console.log(userAgent.toString());
console.log(JSON.stringify(userAgent.data, null, 2));

To restrict generation to modern browsers, combine user-agents with browserslist and browserslist-useragent. Use a browserslist query to define your criteria and a custom filter function to validate the userAgent.data.userAgent string.

import browserslist from 'browserslist';
import { matchesUA } from 'browserslist-useragent';
import UserAgent from 'user-agents';

const browsers = browserslist('last 2 versions and not dead');

function isModernBrowser(data) {
  return matchesUA(data.userAgent, { browsers, allowHigherVersions: true });
}

const userAgent = new UserAgent(isModernBrowser);

You can pass an array to the UserAgent constructor to apply multiple filters simultaneously. This array can contain objects, regular expressions, or functions.

import UserAgent from 'user-agents';

const userAgent = new UserAgent([
  /Safari/,
  {
    connection: {
      type: 'wifi',
    },
    platform: 'MacIntel',
  },
]);

You can pass a RegExp to the UserAgent constructor to ensure the generated user agent string matches the specified pattern.

import UserAgent from 'user-agents';

const userAgent = new UserAgent(/Safari/);

Pass an object to the UserAgent constructor to restrict the generated user agent to a specific deviceCategory. Supported values include 'desktop', 'mobile', and 'tablet'.

import UserAgent from 'user-agents';

const userAgent = new UserAgent({ deviceCategory: 'mobile' });

For complex logic, pass a function to the UserAgent constructor. The function receives the userAgent.data object as an argument and must return true for the user agent to be accepted.

import UserAgent from 'user-agents';
import { parse } from 'useragent';

const userAgent = new UserAgent((data) => {
  const os = parse(data.userAgent).os;
  return os.family === 'iOS' && parseInt(os.major, 10) > 11;
});