# Astro > Typed, SSR-safe Astro components. The `@arraypress` waveform family ships first-class Astro wrappers for all three runtimes. Each one turns the core library's `data-*` attribute contract into a typed `.astro` component: you pass camelCase props, the wrapper stringifies them into the exact attributes the framework-agnostic core scans for, and the core's auto-initialiser mounts the UI on the client. | Package | Component(s) | Wraps | | --- | --- | --- | | `@arraypress/waveform-player-astro` | `` | [`@arraypress/waveform-player`](/player/options/) | | `@arraypress/waveform-bar-astro` | ``, `` | `@arraypress/waveform-bar` | | `@arraypress/waveform-playlist-astro` | `` | `@arraypress/waveform-playlist` | All three share the same design: - **Props mirror core options 1:1** (camelCase). The component handles the kebab-case `data-*` conversion under the hood. - **Omission preserves defaults.** An omitted prop emits no attribute, so the core applies its own internal default. Never pass `null` to "reset" a value — just leave the prop out. - **The wrapper does not load the runtime.** You load the core JS + CSS once in a layout, so you stay in control of CDN vs. self-hosted vs. bundled. - **SSR-safe.** The server renders a plain container plus a small `is:inline` boot script; nothing in the wrapper touches `window` or the DOM at build time. - **View-Transitions-aware.** Each wrapper re-runs the core's idempotent `init()` on `astro:page-load` so client-side navigations remount fresh markup. ## Install Install the wrapper alongside the core runtime it wraps (the cores are peer dependencies, so they are not pulled in automatically). ```sh npm install @arraypress/waveform-player-astro @arraypress/waveform-player ``` ```sh pnpm add @arraypress/waveform-player-astro @arraypress/waveform-player ``` ```sh yarn add @arraypress/waveform-player-astro @arraypress/waveform-player ``` ```sh bun add @arraypress/waveform-player-astro @arraypress/waveform-player ``` Peer dependency ranges per wrapper: | Wrapper | Core peers | Astro | | --- | --- | --- | | `waveform-player-astro` | `@arraypress/waveform-player@^1.8.0` | `^6.0.0 \|\| ^7.0.0` | | `waveform-bar-astro` | `@arraypress/waveform-bar@^1.3.1`, `@arraypress/waveform-player@^1.7.2` | `^6.0.0 \|\| ^7.0.0` | | `waveform-playlist-astro` | `@arraypress/waveform-playlist@^1.3.0`, `@arraypress/waveform-player@^1.8.0` | `^6.0.0 \|\| ^7.0.0` | ## Load the runtime once (in a layout) The wrappers emit markup and a boot script, but they deliberately do **not** inject the core library's JS or CSS — you decide where and how it loads. Pull the assets into your root layout's `` once, and every `` on every page is covered. The cleanest pattern: import the CSS so Astro bundles and hashes it, and import the minified JS with the `?url` suffix so you get a hashed URL to mount via an `is:inline` script tag. ```astro title="src/layouts/Layout.astro" --- --- ``` The core's global `window.WaveformPlayer` is what every wrapper's boot script looks for. If it is missing when a lazy player tries to mount, the wrapper retries for ~1s and then logs a one-time `[WaveformPlayerAstro]` warning rather than failing silently — so a missing script tag is loud, not mysterious. ## The player component Import the default export and drop it anywhere. `url` is the one prop you almost always pass; everything else is optional and falls through to the core's defaults when omitted. ```astro --- --- ``` That renders a single `
` plus an inline init script. On the client, the core's auto-initialiser finds the container and builds the player into it. ### Prop reference Props are inherited verbatim from the core's `WaveformPlayerOptions`, so the [full option list](/player/options/) is the source of truth. The most common props: | Prop | Type | Notes | | --- | --- | --- | | `url` | `string` | Audio source. Alias `src` is also accepted; `url` wins if both are set. | | `waveformStyle` | `'bars' \| 'mirror' \| 'line' \| 'blocks' \| 'dots' \| 'seekbar'` | Visual style. Use this, **not** `style` (see below). | | `height` | `number` | Waveform height in px. | | `samples` | `number` | Source peak resolution decoded. | | `waveform` | `number[] \| string` | Pre-computed peaks: an array, a CSV/JSON string, or a `.json` URL. Arrays are JSON-encoded for you. | | `waveformColor` / `progressColor` | `string \| string[]` | A CSS colour or an array of gradient stops (top→bottom). Arrays are JSON-encoded into the `data-*` attribute automatically. | | `colorPreset` | `'dark' \| 'light'` | Forces a theme; omit for auto-detection. | | `markers` | `Array<{ time: number; label: string; color?: string }>` | Cue markers; JSON-encoded for you. | | `audioMode` | `'self' \| 'external'` | `'self'` owns an `