# Frontend notices ## Table of contents - [useStoreNotices()](#usestorenotices) - [API](#api) - [`addDefaultNotice( text = '', noticeProps = {} )`](#adddefaultnotice-text---noticeprops---) - [`addErrorNotice( text = '', noticeProps = {} )`](#adderrornotice-text---noticeprops---) - [`addWarningNotice( text = '', noticeProps = {} )`](#addwarningnotice-text---noticeprops---) - [`addInfoNotice( text = '', noticeProps = {} )`](#addinfonotice-text---noticeprops---) - [`addSuccessNotice( text = '', noticeProps = {} )`](#addsuccessnotice-text---noticeprops---) - [`hasNoticesOfType( type )`](#hasnoticesoftype-type-) - [`notices`](#notices) - [`removeNotice( id, ctx )`](#removenotice-id-ctx-) - [`removeNotices( status = null )`](#removenotices-status--null-) - [`setIsSuppressed( val )`](#setissuppressed-val-) - [StoreNoticesProvider](#storenoticesprovider) - [Actions](#actions) - [`createNotice( status = 'default', content = '', options = {} )`](#createnotice-status--default-content---options---) - [`createSnackbarNotice( content = '', options = {} )`](#createsnackbarnotice-content---options---) - [`removeNotice( id, ctx )`](#removenotice-id-ctx--1) - [`setIsSuppressed( val )`](#setissuppressed-val--1) - [Statuses](#statuses) - [Notice options](#notice-options) - [useStoreSnackbarNotices()](#usestoresnackbarnotices) - [API](#api-1) - [`addSnackbarNotice( text = '', noticeProps = {} )`](#addsnackbarnotice-text---noticeprops---) - [`notices`](#notices-1) - [`removeNotices( status = null )`](#removenotices-status--null--1) - [StoreSnackbarNoticesProvider](#storesnackbarnoticesprovider) - [Actions](#actions-1) - [`createSnackbarNotice( content = '', options = {} )`](#createsnackbarnotice-content---options----1) - [`removeSnackbarNotice( id, ctx )`](#removesnackbarnotice-id-ctx-) - [`setIsSuppressed( val )`](#setissuppressed-val--2) - [Example usage](#example-usage) ## useStoreNotices() The `useStoreNotices()` hook allows reading and manipulating notices in the frontend. ### API > _Note: if the context is not specified in `noticeProps` or `ctxt` params (depending on the method), the current context is used._ #### `addDefaultNotice( text = '', noticeProps = {} )` Create a new notice with `default` status. | Argument | Type | Description | | ------------- | ------ | -------------------------------------------------- | | `text` | string | Text to be displayed in the notice. | | `noticeProps` | Object | Object with the [notice options](#notice-options). | #### `addErrorNotice( text = '', noticeProps = {} )` Create a new error notice. | Argument | Type | Description | | ------------- | ------ | -------------------------------------------------- | | `text` | string | Text to be displayed in the notice. | | `noticeProps` | Object | Object with the [notice options](#notice-options). | #### `addWarningNotice( text = '', noticeProps = {} )` Create a new warning notice. | Argument | Type | Description | | ------------- | ------ | -------------------------------------------------- | | `text` | string | Text to be displayed in the notice. | | `noticeProps` | Object | Object with the [notice options](#notice-options). | #### `addInfoNotice( text = '', noticeProps = {} )` Create a new info notice. | Argument | Type | Description | | ------------- | ------ | -------------------------------------------------- | | `text` | string | Text to be displayed in the notice. | | `noticeProps` | Object | Object with the [notice options](#notice-options). | #### `addSuccessNotice( text = '', noticeProps = {} )` Create a new success notice. | Argument | Type | Description | | ------------- | ------ | -------------------------------------------------- | | `text` | string | Text to be displayed in the notice. | | `noticeProps` | Object | Object with the [notice options](#notice-options). | #### `hasNoticesOfType( type )` Check whether there are notices of the provided type in the current context. | Argument | Type | Description | | -------- | ------ | ----------------------------- | | `type` | string | Type of the notices to check. | #### `notices` An array of the notices in the current context. #### `removeNotice( id, ctx )` Remove an existing notice. | Argument | Type | Description | | -------- | ------ | --------------------------------------------- | | `id` | string | Id of the notice to remove. | | `ctx` | string | Context where the notice to remove is stored. | #### `removeNotices( status = null )` Remove all notices from the current context. If a `status` is provided, only the notices with that status are removed. | Argument | Type | Description | | -------- | ------ | ----------------------------------------------------------------------------------------------------- | | `status` | string | Status that notices must match to be removed. If not provided, all notices of any status are removed. | #### `setIsSuppressed( val )` Whether notices are suppressed. If true, it will hide the notices from the frontend. | Argument | Type | Description | | -------- | ------- | --------------------------- | | `val` | boolean | Id of the notice to remove. | ## StoreNoticesProvider The `StoreNoticesProvider` allows managing notices in the frontend. Notices are rendered before React Children. Internally, it uses the `StoreNoticesContext` which relies on the [`notices` package](https://github.com/WordPress/gutenberg/tree/master/packages/notices) from Gutenberg. ### Actions #### `createNotice( status = 'default', content = '', options = {} )` This action creates a new notice. If the context is not specified in the `options` object, the current context is used. | Argument | Type | Description | | --------- | ------ | -------------------------------------------------- | | `status` | string | One of the statuses listed below. | | `content` | string | Text to be displayed in the notice. | | `options` | Object | Object with the [notice options](#notice-options). | #### `createSnackbarNotice( content = '', options = {} )` This action creates a new snackbar notice. If the context is not specified in the `options` object, the current context is used. | Argument | Type | Description | | --------- | ------ | -------------------------------------------------- | | `content` | string | Text to be displayed in the notice. | | `options` | Object | Object with the [notice options](#notice-options). | #### `removeNotice( id, ctx )` This action removes an existing notice. If the context is not specified, the current context is used. | Argument | Type | Description | | -------- | ------ | ----------------------------------------------------------------------------------------------------------- | | `id` | string | Id of the notice to remove. | | `ctx` | string | Context where the notice to remove is stored. If the context is not specified, the current context is used. | #### `setIsSuppressed( val )` Whether notices are suppressed. If true, it will hide the notices from the frontend. | Argument | Type | Description | | -------- | ------- | --------------------------- | | `val` | boolean | Id of the notice to remove. | ### Statuses All notices must have one of the following statuses: `default`, `error`, `success`, `info`, `warning`. ### Notice options Object of the form: ```js { id: 'checkout', type: string, isDismissible: false, } ``` Refer to the [Gutenberg docs](https://github.com/WordPress/gutenberg/blob/master/packages/notices/src/store/actions.js#L46) to know the available options. ## useStoreSnackbarNotices() The `useStoreNotices()` hook allows reading and manipulating snackbar notices in the frontend. The snackbar is a small toast-like notification that appears at the bottom of a user's screen. ![Applied coupon code](https://user-images.githubusercontent.com/5656702/124294673-dd803b80-db4f-11eb-81ec-02fb962d04ed.png) ### API #### `addSnackbarNotice( text = '', noticeProps = {} )` Create a new snackbar notice. | Argument | Type | Description | | ------------- | ------ | -------------------------------------------------- | | `text` | string | Text to be displayed in the notice. | | `noticeProps` | Object | Object with the [notice options](#notice-options). | #### `notices` An array of the notices in the current context. #### `removeNotices( status = null )` Remove all notices from the current context. If a `status` is provided, only the notices with that status are removed. | Argument | Type | Description | | -------- | ------ | ----------------------------------------------------------------------------------------------------- | | `status` | string | Status that notices must match to be removed. If not provided, all notices of any status are removed. | ## StoreSnackbarNoticesProvider The `StoreSnackbarNoticesProvider` allows managing snackbar notices in the frontend. Snackbar notices are displayed in the bottom left corner and disappear after a certain time. Internally, it uses the `StoreNoticesContext` which relies on the [`notices` package](https://github.com/WordPress/gutenberg/tree/master/packages/notices) from Gutenberg. ### Actions #### `createSnackbarNotice( content = '', options = {} )` This action creates a new snackbar notice. If the context is not specified in the `options` object, the current context is used. | Argument | Type | Description | | --------- | ------ | -------------------------------------------------- | | `content` | string | Text to be displayed in the notice. | | `options` | Object | Object with the [notice options](#notice-options). | #### `removeSnackbarNotice( id, ctx )` This action removes an existing notice. If the context is not specified, the current context is used. | Argument | Type | Description | | -------- | ------ | ----------------------------------------------------------------------------------------------------------- | | `id` | string | Id of the notice to remove. | | `ctx` | string | Context where the notice to remove is stored. If the context is not specified, the current context is used. | #### `setIsSuppressed( val )` Whether notices are suppressed. If true, it will hide the notices from the frontend. | Argument | Type | Description | | -------- | ------- | --------------------------- | | `val` | boolean | Id of the notice to remove. | ## Example usage The following example shows a `CheckoutProcessor` component that displays an error notice when the payment process fails and it removes it every time the payment is started. When the payment is completed correctly, it shows a snackbar notice. ```jsx const CheckoutProcessor = () => { const { addErrorNotice, removeNotice } = useStoreNotices(); // ... const paymentFail = () => { addErrorNotice( 'Something went wrong.', { id: 'checkout' } ); }; const paymentStart = () => { removeNotice( 'checkout' ); }; // ... }; ``` ```jsx // ... ``` --- [We're hiring!](https://woocommerce.com/careers/) Come work with us! 🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/block-client-apis/notices.md)