API Reference
The tables below are auto-generated from custom-elements.json at build time.
Attributes
All attributes are reactive — changing them after mount updates the UI immediately.
| Attribute | Type | Default | Description |
|---|---|---|---|
size | VisualizerSize | 'md' | Visual size variant. Controls bar width, container height, and gap between bars. |
color | string | undefined | inherits currentColor | Bar fill colour — any valid CSS color value (`#hex`, `rgb()`, named colour, etc.). When omitted the bars inherit `color` from the surrounding document via `currentColor`. Prefer the `--audio-visualizer-color` CSS custom property for stylesheet-based theming — it takes priority over this attribute. |
bar-count | number | undefined | 3 (icon/sm) or 5 | Number of frequency-band bars to display. Defaults to 3 for `icon`/`sm` sizes and 5 for `md`/`lg`/`xl`. |
Properties
| Property | Type | Description |
|---|---|---|
isActive | boolean | `true` while a microphone stream is active and the animation loop is running. Useful for toggling button labels or disabling UI controls. |
Methods
| Method | Signature | Description |
|---|---|---|
startMicrophone | (deviceId?: string) => | Requests microphone access and starts the bar animation loop. - **Must be called from a user gesture** (e.g. a button `click` handler) to satisfy the browser's permissions policy. - If already active, the current stream is stopped and a new one is started with the supplied `deviceId` — safe to call on device switch. |
stopMicrophone | () => void | Stops the animation loop and releases the microphone stream. Safe to call at any time, including when the mic is not yet active. The component resets to its idle (dot) state. |
CSS Custom Properties
| Property | Default | Description |
|---|---|---|
--audio-visualizer-color | currentColor | Bar fill colour. Takes priority over the `color` attribute and CSS colour inheritance (`currentColor`). Set via CSS for stylesheet-based theming. Default: unset (falls back to `color` attr or the inherited `currentColor`). |
--audio-visualizer-transition | 100ms | Transition duration for bar height changes. Increase for a smoother, slower response; decrease for snappier reaction to transient sounds. Default: `100ms`. |
Attribute detail
Section titled “Attribute detail”Controls the visual scale of the element. Bar dimensions and gap size all scale together:
| Value | Height | Bar width | Gap | Default bars |
|---|---|---|---|---|
icon | 24 px | 4 px | 2 px | 3 |
sm | 56 px | 8 px | 4 px | 3 |
md | 112 px | 16 px | 8 px | 5 |
lg | 224 px | 32 px | 16 px | 5 |
xl | 448 px | 64 px | 32 px | 5 |
Sets the bar fill colour directly. Any CSS colour string is valid.
Prefer --audio-visualizer-color for stylesheet-level theming — it takes priority over this attribute when set.
bar-count
Section titled “bar-count”Overrides the number of frequency bands shown. Defaults to 3 for icon/sm and 5 for md/lg/xl.
Method detail
Section titled “Method detail”startMicrophone(deviceId?)
Section titled “startMicrophone(deviceId?)”startMicrophone(deviceId?: string): Promise<void>Requests microphone access and starts the animation loop.
- Must be called from a user gesture (click, keydown, etc.) to satisfy the browser permissions policy.
- If the mic is already active, the current stream is stopped automatically before opening the new one — safe to call repeatedly when switching devices.
- Rejects with a
DOMExceptionon failure:NotAllowedError— user denied permissionOverconstrainedError— the specifieddeviceIddoesn’t exist
stopMicrophone()
Section titled “stopMicrophone()”stopMicrophone(): voidStops the animation loop and releases the microphone stream. Safe to call at any time, even before the mic has been started. Resets all bars to the idle pill state.