showSnackbar

showSnackbar() is the programmatic entry point for transient notifications. It renders a snackbar into the shared stack owned by the application's OverlayHost, waits for it to close, and resolves with the outcome.

Prerequisite

Create a controller and render <OverlayHost :host="overlays" /> before calling the function returned by useOverlays() or createOverlayService(host). The host is only required for programmatic overlays; declarative Snackbar instances do not need it. See OverlayHost for Vue and Nuxt setup.

Basic Usage

import { useOverlays } from '@chillet/m3-vue';
const { showSnackbar } = useOverlays(); // Capture during setup.

await showSnackbar({
  message: 'Saved',
});

Configure Defaults

Set application-level defaults when installing M3VuePlugin. These defaults apply to future showSnackbar() calls. Refs and getters are supported, and options passed to an individual call always take precedence.

import { M3VuePlugin } from '@chillet/m3-vue';

app.use(M3VuePlugin, {
  snackbarDefaults: {
    dismissible: false,
    duration: 6_000,
    position: 'bottom-end',
  },
});

Component Subtree Defaults

Call provideSnackbarDefaults() in an ancestor and capture the nearest defaults with useSnackbar() in descendant components. The returned function can be used later in event handlers. The imported showSnackbar(host, options) uses the defaults of its explicit host. Provide the host through provideOverlayHost() or the OverlayHost default slot before calling useSnackbar().

<!-- NotificationArea.vue -->
<script setup lang="ts">
import { provideSnackbarDefaults } from '@chillet/m3-vue';

provideSnackbarDefaults({
  dismissible: false,
  position: 'top-end',
});
</script>

<template>
  <slot />
</template>

<!-- DescendantComponent.vue -->
<script setup lang="ts">
import { useSnackbar } from '@chillet/m3-vue';

const showSnackbar = useSnackbar();

function notify() {
  void showSnackbar({ message: 'Saved' });
}
</script>

The precedence order is built-in defaults, application plugin defaults, the nearest subtree defaults, and finally the options passed to the individual call.

Return Value

The promise resolves when the snackbar closes.

• Action click resolves to action.value, or 'action' by default.
• Dismiss button resolves to dismissValue, or 'dismiss' by default.
• Auto timeout resolves to timeoutValue, or 'timeout' by default.

The promise rejects if the function is called outside a browser environment, if the target host is absent or disposed, or if action.onClick throws or rejects.

Options

The tables below are generated from source types and stay in sync with API changes.

ShowSnackbarOptions

Field	Type	Required	Description	Default
message	string | undefined	No	Supporting text displayed inside the snackbar.	-
action	SnackbarAction | undefined	No	Optional action button.	-
duration	number | null | undefined	No	Milliseconds before the snackbar closes automatically. Use `null` to disable auto close.	-
timeoutValue	string | undefined	No	Value returned when the snackbar closes automatically.	-
dismissValue	string | undefined	No	Value returned when the dismiss button closes the snackbar.	-
position	SnackbarPosition | undefined	No	Where the snackbar stack is placed in the viewport.	-
actionOnNewLine	boolean | undefined	No	Whether the action should be placed on a separate line.	false
dismissible	boolean | undefined	No	Whether to show a dismiss button.	false
dismissButtonLabel	string | undefined	No	Accessible label for the dismiss button.	"Dismiss notification"

ShowSnackbarDefaults

Field	Type	Required	Description	Default
duration	number | null | undefined	No	Milliseconds before the snackbar closes automatically. Use `null` to disable auto close.	-
timeoutValue	string | undefined	No	Value returned when the snackbar closes automatically.	-
dismissValue	string | undefined	No	Value returned when the dismiss button closes the snackbar.	-
position	SnackbarPosition | undefined	No	Where the snackbar stack is placed in the viewport.	-
actionOnNewLine	boolean | undefined	No	Whether the action should be placed on a separate line.	false
dismissible	boolean | undefined	No	Whether to show a dismiss button.	false
dismissButtonLabel	string | undefined	No	Accessible label for the dismiss button.	"Dismiss notification"

SnackbarAction

Field	Type	Required	Description	Default
label	string	Yes	Label shown in the action area.	-
value	string | undefined	No	Value returned when the action closes the snackbar.	-
disabled	boolean | undefined	No	Whether the action button is disabled.	-
autofocus	boolean | undefined	No	Whether the action button should autofocus when rendered.	-
closeOnClick	boolean | undefined	No	Whether clicking the action should close the snackbar.	-
onClick	(() => void | boolean | Promise<void | boolean>) | undefined	No	Optional callback invoked before the snackbar closes. Return `false` to keep it open.	-

Behavior Notes

• Programmatic snackbars include a dismiss button by default. Set dismissible: false to hide it.
• Multiple snackbars can be shown at the same time.
• Stacks are separated by host and position, so top and bottom placements do not interfere with each other.
• Snackbar actions inherit application-level provides and CSS custom properties from OverlayHost.
• Hovering or focusing the snackbar pauses the auto-close timer.
• Leaving the snackbar resumes the remaining time instead of restarting the full duration.

For manually rendered snackbars, see Snackbar.