--- title: "How to add guides and surveys to an Astro site" description: "Show Amplitude guides and surveys on an Astro site: guide links through the ClientRouter, guide UI kept across swaps, stable pins, a survey button." canonical: "https://amplitude.com/en-us/build/astro-guides-surveys" --- # How to add guides and surveys to an Astro site Show Amplitude guides and surveys on an Astro site: guide links through the ClientRouter, guide UI kept across swaps, stable pins, a survey button. Source: https://amplitude.com/en-us/build/astro-guides-surveys --- # How to add guides and surveys to an Astro site Turn on guides and surveys in an Astro site, send guide links through Astro's navigate(), keep guide UI on screen when \ replaces the page, anchor a pin, and open a survey from your own button. About 20 minutes, all copy-paste. - Astro 6+ - Static or on-demand - Unified SDK 1.x - 20 min Chris Tam · Last updated 19 October 2026 Astro sites are mostly static HTML with a little JavaScript where you need it. [Guides and surveys](https://amplitude.com/guides-and-surveys) add tours, announcements, and feedback prompts to those pages, and you edit them in Amplitude instead of shipping a new build. In this tutorial, you'll turn on guides and surveys, route guide links through Astro's router, keep guide UI across page swaps, anchor a pin, and open a survey. It builds on [the Astro product analytics page](/build/astro-product-analytics). ## What you'll build An Astro site where guides and surveys boot once per page load, in the browser, with the same user and device ID as your analytics. Guide links set to Use router go through Astro's `navigate()` when the page uses ``, a guide button runs an `open_new_project` callback in your code, guide UI stays on screen when the router replaces ``, a pin anchors to `[data-guide="new-project-button"]`, and a "Give feedback" button opens the survey with the key `product-feedback`. By the end you'll see the SDK report a booted user, `Guide Viewed` in your test user's event stream, and your answer on the survey's Responses tab. ## Prerequisites - The setup from [How to add product analytics to an Astro site](/build/astro-product-analytics): `@amplitude/unified` installed, `PUBLIC_AMPLITUDE_API_KEY` in `.env`, `initAll` and the `amplitudeReady` export in `src/scripts/amplitude.ts`, and `` rendered first in `` in `src/layouts/Layout.astro`. - From the same page: `src/components/SignOutButton.astro`, the `src/lib/auth.ts` stub or your own auth helper, and the `/projects/new` page. The guide's callback goes to `/projects/new`. - Either output mode works, with or without ``. Guides and surveys run only in the browser, so prerendered pages show them too. - Your Amplitude project API key. In Amplitude, go to Settings > Projects > your project > General. Guides and surveys must use the same key as your analytics. No Amplitude account yet? A free account is enough for this tutorial: the Free plan includes one live guide and one live survey, which is what this page builds. [Sign up for free](https://app.amplitude.com/signup) to get your project API key, and [compare plans](https://amplitude.com/pricing) when you need more. ## 1. Turn guides and surveys on The [Quickstart](https://amplitude.com/docs/get-started/amplitude-quickstart) installs `@amplitude/unified` for browser apps that use npm, and the Browser Unified SDK includes guides and surveys and initializes them by default. If you followed the [product analytics page](/build/astro-product-analytics), it's already installed. Otherwise install it, then add the key to `.env` as that page's step 1 shows. Terminal ```sh npm install @amplitude/unified ``` The `initAll` call in `src/scripts/amplitude.ts` already starts guides and surveys with the analytics user, so don't call `engagement.init()` or `engagement.boot()` yourself; the docs say calling boot more than once causes unexpected behavior, especially for guides and surveys set to appear immediately. Don't pass `engagement: { skip: true }` either, which stops guides and surveys from loading at all. This page adds one `engagement` block to the `initAll` options, next to `analytics` and `sessionReplay`. It makes the SDK write the styles for guide and survey UI as text inside `