- Docs
- createToaster
createToaster
Mount or update the singleton toaster and return its controller.
Mount, or update, the singleton toaster and return its controller. It is idempotent: calling it twice with different options applies the difference through controller.update().
Signature
function createToaster(options?: ToasterOptions): ToasterController
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
options |
ToasterOptions |
no | The toaster configuration. Every field has a default. |
Returns
A ToasterController. It is the same instance on every call, because there is exactly one singleton per page.
Throws
Error('createToaster() requires a DOM environment (browser)')when it is called in a context without a DOM, such as server-side rendering.Error('createToaster() requires document.body; call it after DOMContentLoaded')whendocument.bodydoes not exist yet.
Behaviour
First call
- Mounts the container with the
data-notify-toasterattribute ondocument.body. - Applies the data attributes and the CSS custom properties the stylesheet reads, including the offsets, the width, and the gap.
- Subscribes to the shared observer. Every toast create, update, and dismiss is rendered to the DOM.
- Stores the controller in the singleton slot.
Subsequent calls
If a controller is already mounted, createToaster calls controller.update(options) with the new options and returns the same controller. The existing container and its active toasts stay in place. Only the data attributes, the CSS variables, and the timers change.
Examples
Mount a default toaster
import { createToaster } from '@samline/notify'
import '@samline/notify/style.css'
createToaster()
The container is mounted at bottom-right with the light theme and every other default. The first toast(...) call now has somewhere to render.
Mount a configured toaster
import { createToaster } from '@samline/notify'
import '@samline/notify/style.css'
createToaster({
position: 'top-right',
theme: 'dark',
richColors: true,
duration: 5000,
visibleToasts: 4,
offset: 24,
mobileOffset: 16,
})
Update later
import { createToaster } from '@samline/notify'
const toaster = createToaster({ position: 'bottom-right' })
// The user toggles dark mode.
toaster.update({ theme: 'dark' })
// The user resizes to a small viewport.
toaster.update({ position: 'bottom-center' })
Use the returned controller
import { createToaster, getToaster } from '@samline/notify'
createToaster({ position: 'bottom-right' })
const controller = getToaster()
controller?.element // the mounted container element
controller?.options // the current merged options
Edge cases
- Server-side rendering. It throws. The standalone build guards the same call against a missing DOM and skips it.
- Multiple toasters on the same page. The singleton is the only one
createToasterknows about. For a multi-toaster interface, callmountToasterdirectly and keep your own map of controllers. mountToasterversuscreateToaster.mountToasteris the lower-level escape hatch: it accepts a root, returns a fresh controller per call, and does not touch the singleton.createToasteris the high-level entry point that routes through the singleton.- Reusing the singleton. The active timers and the existing elements are kept. New options take effect immediately.
Related
configureToaster— the intent-revealing alias.destroyToaster— unmount the singleton.getToaster— read the singleton.- Configuration