Skip to content

Latest commit

 

History

History
90 lines (66 loc) · 3.15 KB

README.md

File metadata and controls

90 lines (66 loc) · 3.15 KB

Snackbar

Use Snackbars to communicate low priority, non-interruptive messages to the user.

Table of contents

  1. Design guidelines
  2. Development guidelines
  3. Related components

Design guidelines

A Snackbar displays a succinct message that is cleared out after a small delay. It can also offer the user options, like viewing a published post but these options should also be available elsewhere in the UI.

Development guidelines

Usage

To display a plain snackbar, pass the message as a children prop:

const MySnackbarNotice = () => (
	<Snackbar>Post published successfully.</Snackbar>
);

For more complex markup, you can pass any JSX element:

const MySnackbarNotice = () => (
	<Snackbar>
		<p>
			An error occurred: <code>{ errorDetails }</code>.
		</p>
	</Snackbar>
);

Props

The following props are used to control the display of the component.

children: ReactNode

The displayed message of a notice. Also used as the spoken message for assistive technology, unless spokenMessage is provided as an alternative message.

  • Required: Yes

spokenMessage: ReactNode

Used to provide a custom spoken message in place of the children default.

  • Required: No
  • Default: children

politeness: 'polite' | 'assertive'

A politeness level for the notice's spoken message. Should be provided as one of the valid options for an aria-live attribute value. Defaults to "polite". Note that this value should be considered a suggestion; assistive technologies may override it based on internal heuristics.

  • A value of 'assertive' is to be used for important, and usually time-sensitive, information. It will interrupt anything else the screen reader is announcing in that moment.
  • A value of 'polite' is to be used for advisory information. It should not interrupt what the screen reader is announcing in that moment (the "speech queue") or interrupt the current task.
  • Required: No
  • Default: 'polite'

actions: Action[]

An array of action objects. Each member object should contain a label and either a url link string or onClick callback function.

  • Required: No
  • Default: []

onRemove: Function

Function called when dismissing the notice.

  • Required: No
  • Default: () => void

icon: WPElement | null

The icon to render in the snackbar.

  • Required: No
  • Default: null

explicitDismiss: boolean

Whether to require user action to dismiss the snackbar. By default, this is dismissed on a timeout, without user interaction.

  • Required: No
  • Default: false

onDismiss: Function

A callback executed when the snackbar is dismissed. It is distinct from onRemove, which looks like a callback but is actually the function to call to remove the snackbar from the UI.

  • Required: No
  • Default: () => void

listRef: MutableRefObject< HTMLDivElement >

A ref to the list that contains the snackbar.

  • Required: No

Related components

  • To create a prominent message that requires a higher-level of attention, use a Notice.