DOCSEARCHbyAlgolia
Submit Docs

Bowser

repository·master·Indexed 27 days ago

https://github.com/bowser-js/bowser

A lightweight browser, platform, and engine detector for browser and Node.js environments. It provides tools to parse User-Agent strings and User-Agent Client Hints via Bowser.parse() and Bowser.getParser(), and includes a .satisfies() method for filtering browsers based on version, OS, and platform criteria.

Tokens
1.8K
Snippets
6
Records
8
Agent score
41%

What's inside Bowser

  1. Install and import Bowser

    master

    Bowser is a UMD module compatible with AMD, TypeScript, ES6, and CommonJS.

    By default, the exported version is the ES5 transpiled version and does not include polyfills. If you are not using your own babel-polyfill, you should use the bundled version which includes babel-polyfill.

    To use the bundled version with polyfills, require bowser/bundled instead of bowser.

    // CommonJS
const Bowser = require("bowser");
// For bundled version with polyfills:
// const Bowser = require("bowser/bundled");

// TypeScript
import * as Bowser from "bowser";

// ES6 (and TypeScript with --esModuleInterop enabled)
import Bowser from "bowser";

  2. Detect browser properties with getParser()

    master

    Use Bowser.getParser(userAgent) to create a parser instance. You can then use methods like getBrowserName() to retrieve specific properties of the user's browser.

    const browser = Bowser.getParser(window.navigator.userAgent);

console.log(`The current browser name is "${browser.getBrowserName()}"`);
// The current browser name is "Internet Explorer"

  3. Use User-Agent Client Hints for improved detection

    master

    Modern browsers support User-Agent Client Hints, which provide more accurate and privacy-friendly data. You can pass window.navigator.userAgentData as the second argument to getParser() or parse() to leverage this data.

    When using Client Hints, you can access:

    • getHints(): Returns the full ClientHints object or null.
    • hasBrand(brandName): Checks if a specific brand exists in the hints.
    • getBrandVersion(brandName): Returns the version of a specific brand.

    Client Hints are particularly useful for improving detection for Chromium-based browsers like DuckDuckGo.

    // Pass Client Hints as the second parameter
const browser = Bowser.getParser(
  window.navigator.userAgent,
  window.navigator.userAgentData
);

console.log(`The current browser name is "${browser.getBrowserName()}"`);

// Working with Client Hints
const hints = browser.getHints();

if (browser.hasBrand('Google Chrome')) {
  console.log('This is Chrome!');
}

const chromeVersion = browser.getBrandVersion('Google Chrome');
console.log(`Chrome version: ${chromeVersion}`);

  4. Parse User-Agent into a structured object with parse()

    master
    The Bowser.parse() method returns a structured object containing details about the browser, os, platform, and engine. You can also pass Client Hints as the second argument to enhance the accuracy of the returned object.

  5. Filter browsers using satisfies()

    master

    The .satisfies() method allows you to filter browsers based on specific criteria. You can define rules for specific operating systems (e.g., windows, macos), platforms (e.g., mobile), or general browser requirements.

    Rules support several operators:

    • Equality: =20.1.1432 (matches a particular build only)
    • Loose-equality (sub-version): ~20.1 (matches any 20.1.* sub-version)
    • Loose-equality (major version): ~20 (matches any 20.* sub-version)
    • Comparison: >10, >=9, etc.

    Note: Settings for a specific OS or platform take priority over general browser settings.

    const browser = Bowser.getParser(window.navigator.userAgent);
const isValidBrowser = browser.satisfies({
  // declare browsers per OS
  windows: {
    "internet explorer": ">10",
  },
  macos: {
    safari: ">10.1"
  },

  // per platform (mobile, desktop or tablet)
  mobile: {
    safari: '>=9',
    'android browser': '>3.10'
  },

  // or in general
  chrome: "~20.1.1432",
  firefox: ">31",
  opera: ">=22",

  // also supports equality operator
  chrome: "=20.1.1432", // will match particular build only

  // and loose-equality operator
  chrome: "~20",        // will match any 20.* sub-version
  chrome: "~20.1"       // will match any 20.1.* sub-version
});

  7. Create a Parser instance with Bowser.getParser()

    master

    Use Bowser.getParser() to create a Parser instance for a specific User-Agent string. This instance allows you to perform detailed detection and access the parsed results. You can optionally provide User-Agent Client Hints (e.g., navigator.userAgentData) to improve detection accuracy in modern browsers.

    Arguments:

    • UA (String): The User-Agent string to parse.
    • skipParsingOrHints (Boolean|Object, optional): If true, skips parsing. If an object, it is treated as Client Hints.
    • clientHints (Object, optional): User-Agent Client Hints data.
    const parser = Bowser.getParser(window.navigator.userAgent);
const result = parser.getResult();

// With User-Agent Client Hints
const parserWithHints = Bowser.getParser(
  window.navigator.userAgent,
  window.navigator.userAgentData
);

  8. Parse a User-Agent string immediately with Bowser.parse()

    master

    Use Bowser.parse() to quickly obtain the parsed result of a User-Agent string without manually managing a Parser instance. This is a convenience method that runs .getResult() immediately.

    Arguments:

    • UA (String): The User-Agent string to parse.
    • clientHints (Object, optional): User-Agent Client Hints data (e.g., navigator.userAgentData).
    const result = Bowser.parse(window.navigator.userAgent);

// With User-Agent Client Hints
const resultWithHints = Bowser.parse(
  window.navigator.userAgent,
  window.navigator.userAgentData
);