Documentation
01
See it in context
Preview
02
Copy a working example
Usage
Astro examples assume UIPrimitives is mounted once in your root layout. Do not add the runtime next to each component instance.
---
import {
Button,
Sonner
} from '@santi020k/lumen-astro'
---
<Sonner aria-label="Notifications" />
<Button variant="outline" data-ex-toast-trigger>Show toast</Button>
<script>
document.querySelector('[data-ex-toast-trigger]')?.addEventListener('click', () => {
document.dispatchEvent(new CustomEvent('ui:toast', {
detail: { description: 'Your changes are live.', title: 'Saved', variant: 'success' }
}))
})
</script>---
import {
Button,
Sonner
} from '@santi020k/lumen-astro'
---
<Sonner aria-label="Notifications" />
<Button variant="outline" data-ex-toast-trigger>Show toast</Button>
<script>
document.querySelector('[data-ex-toast-trigger]')?.addEventListener('click', () => {
document.dispatchEvent(new CustomEvent('ui:toast', {
detail: { description: 'Your changes are live.', title: 'Saved', variant: 'success' }
}))
})
</script>import { Button, Sonner } from '@santi020k/lumen-react'
export const Example = () => (
<>
<Sonner aria-label="Notifications" />
<Button
variant="outline"
onClick={() => {
document.dispatchEvent(new CustomEvent('ui:toast', {
detail: { description: 'Your changes are live.', title: 'Saved', variant: 'success' }
}))
}}
>
Show toast
</Button>
</>
)import { Button, Sonner } from '@santi020k/lumen-react'
export const Example = () => (
<>
<Sonner aria-label="Notifications" />
<Button
variant="outline"
onClick={() => {
document.dispatchEvent(new CustomEvent('ui:toast', {
detail: { description: 'Your changes are live.', title: 'Saved', variant: 'success' }
}))
}}
>
Show toast
</Button>
</>
)<script type="module">
import { defineLumenElements } from '@santi020k/lumen-elements/define'
defineLumenElements()
</script>
<lumen-sonner aria-label="Notifications"></lumen-sonner>
<lumen-button variant="outline" data-ex-toast-trigger>Show toast</lumen-button>
<script>
document.querySelector('[data-ex-toast-trigger]')?.addEventListener('click', () => {
document.dispatchEvent(new CustomEvent('ui:toast', {
detail: { description: 'Your changes are live.', title: 'Saved', variant: 'success' }
}))
})
</script><script type="module">
import { defineLumenElements } from '@santi020k/lumen-elements/define'
defineLumenElements()
</script>
<lumen-sonner aria-label="Notifications"></lumen-sonner>
<lumen-button variant="outline" data-ex-toast-trigger>Show toast</lumen-button>
<script>
document.querySelector('[data-ex-toast-trigger]')?.addEventListener('click', () => {
document.dispatchEvent(new CustomEvent('ui:toast', {
detail: { description: 'Your changes are live.', title: 'Saved', variant: 'success' }
}))
})
</script>03
Choose your target
Add this component
Choose the package for your runtime. All adapters share the Lumen stylesheet. Use the matching registry command when you want a local wrapper for that framework.
pnpm add @santi020k/lumen-astropnpm add @santi020k/lumen-astrolumen add Sonnerlumen add Sonnerpnpm add @santi020k/lumen-reactpnpm add @santi020k/lumen-reactlumen add Sonner --target reactlumen add Sonner --target reactpnpm add @santi020k/lumen-elementspnpm add @santi020k/lumen-elementslumen add Sonner --target elementslumen add Sonner --target elementsAPI reference
Lumen-specific props and runtime attributes for the Astro primitive. React props follow the same names; Elements use equivalent kebab-case attributes where custom elements expose them.
| Attribute | Values | Default | Description |
|---|---|---|---|
| placement | "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" | "bottom-right" | Positions the toast viewport. |
| maxCount | number | - | Limits the number of runtime toasts kept in the viewport. The runtime default is 5 when omitted. |
| aria-atomic | ARIA boolean string | "false" | Sets the live-region atomicity attribute. |
| aria-live | "off" | "polite" | "assertive" | "polite" | Sets the live-region announcement priority. |
| class, className | string | "" | Merges custom classes with the generated ui-* root classes. |
| ...native attributes | HTML attributes | - | Forwards standard attributes to the root element unless the component consumes them. |
Runtime events
CustomEvents dispatched by the Astro UIPrimitives runtime for this component.
| Event | Target | Detail | When |
|---|---|---|---|
| ui:toast | Document | { id?: string, title?: string, description?: string, variant?: string, duration?: number, placement?: string, action?: { label: string } } | Creates a programmatic toast in the matching Sonner viewport. |
| ui:toast-update | Document | { id: string, title?: string, description?: string, variant?: string, duration?: number } | Updates a programmatic toast created by ui:toast or window.LumenToast.create(detail). |
| ui:toast-dismiss | Document | { id?: string } | Dismisses one programmatic toast by id, or all runtime toasts when id is omitted. |