🚀 Astro UserAgent

Astro UserAgent is a simple helper for parsing user agent strings so you can detect browsers and devices in your Astro projects.

It works both:

On the server (SSR) by reading the request's user-agent header.
In the browser (client-side) by reading navigator.userAgent.

📦 Installation

First, install the astro-useragent package using your package manager. (If you aren’t sure which package manager you’re using, run the first command.)

Using PNPM

pnpm install astro-useragent

Using NPM

npm install astro-useragent

Using Yarn

yarn add astro-useragent

🥑 Usage

Usage in the browser (client-side)

You can parse the user agent entirely in the browser. This does not require SSR. Just pass navigator.userAgent to useUserAgent:

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Client-side UA detection</title>
  </head>
  <body>
    <p id="ua"></p>
    <p id="device"></p>

    <script type="module">
      import { useUserAgent } from 'astro-useragent';

      const { source, isMobile, browser } = useUserAgent(navigator.userAgent);
      document.getElementById('ua').textContent = `UA: ${source}`;
      document.getElementById('device').textContent = isMobile
        ? 'On mobile'
        : `On ${browser || 'unknown'} desktop/tablet`;
    </script>
  </body>
</html>

If you prefer, you can use a framework component (React/Vue/Svelte) and call useUserAgent(navigator.userAgent) inside a client component with your desired hydration directive (e.g. client:load).

Usage on the server (SSR)

If you want to parse the user agent on the server (e.g., in Astro Pages or API routes), enable SSR features with the output: 'server' configuration option:

import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'server'
});

You only need SSR if you plan to detect the user agent on the server. For more info about SSR mode, please refer to the official docs.

Usage with Astro pages (server-side)

To parse a user-agent string inside any of your top level Astro pages, import useUserAgent and then use it inside the frontmatter section:

---
import { useUserAgent } from 'astro-useragent';

const uaString = Astro.request.headers.get('user-agent') ?? '';
const { source, isMobile } = useUserAgent(uaString);
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>My Astro website</title>
  </head>
  <body>
    <p>Source: {source}</p>
    {isMobile ? <p>I'm on mobile</p> : <p>I'm on desktop</p>}
  </body>
</html>

Note Read more about Astro request headers here: Astro Docs

Usage with Astro API routes (server-side)

useUserAgent can also be used inside your API routes, to perform some logic based on the client user-agent.

In the example below, an API route is used to redirect a user to a different mobile page when he is using a mobile client, otherwise it serves the normal content.

import type { APIContext } from 'astro';
import { useUserAgent } from 'astro-useragent';

export async function get({ request }: APIContext) {
  const uaString = request.headers.get('user-agent');
  const { isMobile } = useUserAgent(uaString);

  if (isMobile) {
    return Response.redirect('https://mobile.mysite.com/', 307);
  }

  const greetings = {
    message: 'hello from astro API'
  };

  return new Response(JSON.stringify(greetings), {
    status: 200
  });
}

Note Read more about Astro API routes here: Astro Docs

We have also setup an example repository available here: example-useragent

Parsed object interface

The parsed UserAgent object will have the following interface:

export interface UserAgent {
  readonly source: string | null; // The original user agent string.
  readonly browser: string | null;
  readonly browserVersion: number;
  readonly cpu: string | null;
  readonly deviceType: string | null;
  readonly deviceVendor: string | null;
  readonly engine: string | null;
  readonly engineVersion: number | null;
  readonly os: string | null;
  readonly osVersion: number | null;
  readonly isAndroid: boolean;
  readonly isChrome: boolean;
  readonly isChromeOS: boolean;
  readonly isDesktop: boolean;
  readonly isEdge: boolean;
  readonly isFirefox: boolean;
  readonly isIE: boolean;
  readonly isIos: boolean;
  readonly isIpad: boolean;
  readonly isIphone: boolean;
  readonly isMac: boolean;
  readonly isMobile: boolean;
  readonly isOpera: boolean;
  readonly isSafari: boolean;
  readonly isTablet: boolean;
  readonly isWindows: boolean;
  readonly isBot: boolean;
  readonly isAIBot: boolean;
  readonly isChromeFamily: boolean;
  readonly isAppleSilicon: boolean;
  getUA(): string;
  getBrowser(): IBrowser;
  getCPU(): ICPU;
  getDevice(): IDevice;
  getEngine(): IEngine;
  getOS(): IOS;
}

Caveats

UserAgent-based mobile detection isn’t always accurate. Instead, use the following client-side function:

function isMobile() {
  const match = window.matchMedia('(pointer:coarse)');
  return match && match.matches;
}

Changelog

Please see the Changelog for more information on what has changed recently.

Acknowledgements

astro-useragent is a port from next-useragent to Astro. so big thanks to the contributors behind next-useragent package.