astro-useragent
Advanced tools
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:
user-agent header.navigator.userAgent.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
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).
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.
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
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
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;
}
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;
}
Please see the Changelog for more information on what has changed recently.
astro-useragent is a port from next-useragent to Astro. so big thanks to the contributors behind next-useragent package.
FAQs
Parses browser user-agent strings for Astro
The npm package astro-useragent receives a total of 590 weekly downloads. As such, astro-useragent popularity was classified as not popular.
We found that astro-useragent demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A malicious Chrome extension posing as an Ethereum wallet steals seed phrases by encoding them into Sui transactions, enabling full wallet takeover.
Security News
Socket is heading to London! Stop by our booth or schedule a meeting to see what we've been working on.
Security News
OWASP’s 2025 Top 10 introduces Software Supply Chain Failures as a new category, reflecting rising concern over dependency and build system risks.