Skip to content

OrigamSnackbarGroup ​

<OrigamSnackbarGroup> is a multi-toast notification system built on top of the same intent / token vocabulary as <OrigamSnackbar>. Unlike the single-shot snackbar, the stack is driven by a composable — useSnackbarGroup({ id }) — and renders any number of concurrent notifications in a chosen anchor location of the viewport.

The component itself owns no template-level state: callers programmatically push items via notify() and the stack handles ordering, FIFO eviction past max, per-item auto-dismiss timers, intent-driven ARIA role / aria-live, action buttons, and slide-in / slide-out transitions (automatically degraded under prefers-reduced-motion).

Basic usage ​

vue
<template>
    <OrigamBtn @click="ping">Notify</OrigamBtn>
    <OrigamSnackbarGroup location="bottom-right" />
</template>

<script setup lang="ts">
    import { useSnackbarGroup } from '@origam/composables'

    const { notify } = useSnackbarGroup()

    function ping() {
        notify({
            title: 'Saved',
            message: 'Your profile was updated.',
            intent: 'success',
            duration: 3000
        })
    }
</script>

Multiple independent stacks ​

Each useSnackbarGroup({ id }) call keys into its own bucket. Render as many <OrigamSnackbarGroup :id="…"> as you need — global, per-region, per-feature — and address them independently.

vue
<template>
    <OrigamSnackbarGroup id="global" location="top-right" />
    <OrigamSnackbarGroup id="builder" location="bottom-left" />
</template>

<script setup lang="ts">
    import { useSnackbarGroup } from '@origam/composables'

    const builder = useSnackbarGroup({ id: 'builder' })

    function onSaveDraft() {
        builder.notify({
            title: 'Draft saved',
            intent: 'info'
        })
    }
</script>

Action buttons ​

Each item can carry one or more action buttons. By default, clicking an action runs the handler and dismisses the item (set keepOpen: true to keep it visible).

vue
<script setup lang="ts">
    import { useSnackbarGroup } from '@origam/composables'

    const { notify } = useSnackbarGroup()

    function onDelete(row) {
        notify({
            title: 'Item deleted',
            intent: 'warning',
            duration: 8000,
            actions: [
                {
                    label: 'Undo',
                    intent: 'primary',
                    handler: () => restore(row)
                }
            ]
        })
    }
</script>

Props ​

PropTypeDefaultDescription
idstring'default'Identifier of the stack — pair with useSnackbarGroup({ id }).
locationTSnackbarGroupLocation'bottom-right'Anchor location (top-left, top-right, top-center, bottom-left, bottom-right, bottom-center, top, bottom).
maxnumber5Maximum number of items rendered concurrently. Excess items are evicted FIFO.
defaultDurationnumber5000Default auto-dismiss timeout (ms). 0 makes new items sticky.
spacingstring | number'12px'Gap between stacked items.
directionTSnackbarGroupDirectionauto'top-down' for top-* locations, 'bottom-up' for bottom-* locations. Override explicitly when needed.
tagstring'div'Root tag for the region.
attachboolean | string | Elementfalse (→ document.body)Teleport target, resolved through useTeleport() — same semantics as OrigamOverlay.attach. true renders in place; a CSS selector string or an Element teleports there instead of document.body.

The component teleports to document.body so its position is independent of any parent overflow / transform context.

Composable API — useSnackbarGroup ​

ts
import { useSnackbarGroup } from '@origam/composables'

const { notify, dismiss, dismissAll, items } = useSnackbarGroup({
    id: 'global',           // optional, default 'default'
    max: 20,                // optional global cap on the store
    defaultDuration: 5000   // optional, applied when item omits duration
})
MethodSignatureDescription
notify(opts: ISnackbarGroupItemOptions) => stringPushes an item, returns its generated id.
dismiss(id: string) => voidRemoves a specific item and fires its onDismiss.
dismissAll() => voidClears the stack — each item's onDismiss fires.
itemsReadonly<Ref<…>>Reactive read-only list. Use for debugging or custom rendering.

Calling useSnackbarGroup({ id }) multiple times with the same id returns handles backed by the same underlying store — notify here, dismiss there.

ISnackbarGroupItemOptions ​

FieldTypeDefaultDescription
titlestring—Bold first line.
messagestring—Body text under the title (or sole line if no title).
intentTIntent'info'Semantic intent — drives icon defaults, role=status/alert, surface coloring.
durationnumberstack defaultAuto-dismiss timeout (ms). 0 = sticky.
iconTIconper-intentPrepend icon override.
actionsArray<ISnackbarGroupItemAction>—Action buttons rendered in the footer.
dismissiblebooleantrueWhether to show the close (X) button.
onDismiss() => void—Callback fired once the item leaves the stack (any cause).

ISnackbarGroupItemAction ​

FieldTypeRequiredDescription
labelstringyesButton label.
handler() => voidyesInvoked on click.
intentTIntentnoOptional intent override for the action button color.
keepOpenbooleannoWhen true, the item stays visible after the click.

Accessibility ​

  • The stack root carries role="region" + aria-label="Notifications" so assistive technology can navigate to it directly.
  • Each item carries either role="status" + aria-live="polite" for info / success / neutral intents, or role="alert" + aria-live="assertive" for warning / danger intents. Screen readers therefore announce critical errors immediately while informational toasts wait for a free moment.
  • aria-atomic="true" is set so updates to the item announce as a unit.
  • The dismiss button is a real <button type="button"> with a descriptive aria-label, focusable through the regular Tab order.
  • The slide-in / slide-out transition collapses to a quick fade under prefers-reduced-motion: reduce.

Slots ​

<OrigamSnackbarGroup> is composable-driven and does not expose a default slot. Item content is configured per-notify() call (title, message, intent, icon, actions). This is intentional — it keeps the declarative template free of imperative spawn logic and lets background services (auth, sync, validation) push notifications from anywhere without holding a component ref.

Design tokens ​

Stack container ​

CSS variableDescription
--origam-snackbar-group---z-indexStack z-index (default toast).
--origam-snackbar-group---gapGap between stacked items.
--origam-snackbar-group---max-widthMax width of the stack container.
--origam-snackbar-group---transition-durationSlide-in / slide-out duration.
--origam-snackbar-group---position-topTop offset for top-anchored stacks.
--origam-snackbar-group---position-bottomBottom offset for bottom-anchored stacks.
--origam-snackbar-group---position-leftLeft offset for left-anchored stacks.
--origam-snackbar-group---position-rightRight offset for right-anchored stacks.

Per-item overrides (__item) ​

OrigamSnackbarItem reads its own --origam-snackbar-item---* channel. The group bridges the __item family onto it inside a :deep(.origam-snackbar-item) block (#436), so setting one of these re-skins the items only while stacked — a standalone <OrigamSnackbar> keeps the -item defaults. Each bridged token falls back to the item's own value, so the stack renders identically until you actually set one.

CSS variableDescription
--origam-snackbar-group__item---background-colorItem surface background.
--origam-snackbar-group__item---border-colorItem surface border colour.
--origam-snackbar-group__item---border-widthItem border width.
--origam-snackbar-group__item---border-radiusItem corner radius.
--origam-snackbar-group__item---colorItem text colour.
--origam-snackbar-group__item---font-sizeItem font size.
--origam-snackbar-group__item---paddingItem inner padding.
--origam-snackbar-group__item---gapGap between the item's zones.
--origam-snackbar-group__item---min-width / ---max-widthItem width clamp.
--origam-snackbar-group__item---prepend-colorLeading icon colour.
--origam-snackbar-group__item---title-font-weightTitle weight.
--origam-snackbar-group__item---message-font-weightMessage weight.
--origam-snackbar-group__item---message-colorMessage colour.
--origam-snackbar-group__item---message-opacityMessage opacity.
--origam-snackbar-group__item---action-colorAction button colour.

Declared but not bridged ​

--origam-snackbar-group__item---box-shadow is declared in light.css / dark.css but is not wired — the :deep() bridge deliberately leaves it out, because the value declared for it does not match what OrigamSnackbarItem renders today, so bridging it would change the current appearance rather than merely make it themeable. Overriding it has no effect. To change a stacked item's elevation, set --origam-snackbar-item---box-shadow instead.

Intent-based surface colors fall through to the shared semantic --origam-color__feedback--{intent}---* tokens, so a single design-token brand swap re-skins both OrigamSnackbar and OrigamSnackbarGroup together.