Skip to content

Latest commit

 

History

History
404 lines (307 loc) · 9.34 KB

data-core-notices.md

File metadata and controls

404 lines (307 loc) · 9.34 KB
Raw

Notices Data

Namespace: core/notices.

Selectors

getNotices

Returns all notices as an array, optionally for a given context. Defaults to the global context.

Usage

import { useSelect } from '@wordpress/data';
import { store as noticesStore } from '@wordpress/notices';

const ExampleComponent = () => {
	const notices = useSelect( ( select ) =>
		select( noticesStore ).getNotices()
	);
	return (
		<ul>
			{ notices.map( ( notice ) => (
				<li key={ notice.ID }>{ notice.content }</li>
			) ) }
		</ul>
	);
};

Parameters

  • state Object: Notices state.
  • context ?string: Optional grouping context.

Returns

  • WPNotice[]: Array of notices.

Actions

createErrorNotice

Returns an action object used in signalling that an error notice is to be created. Refer to createNotice for options documentation.

Related

  • createNotice

Usage

import { __ } from '@wordpress/i18n';
import { useDispatch } from '@wordpress/data';
import { store as noticesStore } from '@wordpress/notices';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
	const { createErrorNotice } = useDispatch( noticesStore );
	return (
		<Button
			onClick={ () =>
				createErrorNotice( __( 'An error occurred!' ), {
					type: 'snackbar',
					explicitDismiss: true,
				} )
			}
		>
			{ __(
				'Generate an snackbar error notice with explicit dismiss button.'
			) }
		</Button>
	);
};

Parameters

  • content string: Notice message.
  • options [Object]: Optional notice options.

Returns

  • Object: Action object.

createInfoNotice

Returns an action object used in signalling that an info notice is to be created. Refer to createNotice for options documentation.

Related

  • createNotice

Usage

import { __ } from '@wordpress/i18n';
import { useDispatch } from '@wordpress/data';
import { store as noticesStore } from '@wordpress/notices';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
	const { createInfoNotice } = useDispatch( noticesStore );
	return (
		<Button
			onClick={ () =>
				createInfoNotice( __( 'Something happened!' ), {
					isDismissible: false,
				} )
			}
		>
			{ __( 'Generate a notice that cannot be dismissed.' ) }
		</Button>
	);
};

Parameters

  • content string: Notice message.
  • options [Object]: Optional notice options.

Returns

  • Object: Action object.

createNotice

Returns an action object used in signalling that a notice is to be created.

Usage

import { __ } from '@wordpress/i18n';
import { useDispatch } from '@wordpress/data';
import { store as noticesStore } from '@wordpress/notices';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
	const { createNotice } = useDispatch( noticesStore );
	return (
		<Button
			onClick={ () => createNotice( 'success', __( 'Notice message' ) ) }
		>
			{ __( 'Generate a success notice!' ) }
		</Button>
	);
};

Parameters

  • status string|undefined: Notice status ("info" if undefined is passed).
  • content string: Notice message.
  • options [Object]: Notice options.
  • options.context [string]: Context under which to group notice.
  • options.id [string]: Identifier for notice. Automatically assigned if not specified.
  • options.isDismissible [boolean]: Whether the notice can be dismissed by user.
  • options.type [string]: Type of notice, one of default, or snackbar.
  • options.speak [boolean]: Whether the notice content should be announced to screen readers.
  • options.actions [Array<WPNoticeAction>]: User actions to be presented with notice.
  • options.icon [string]: An icon displayed with the notice. Only used when type is set to snackbar.
  • options.explicitDismiss [boolean]: Whether the notice includes an explicit dismiss button and can't be dismissed by clicking the body of the notice. Only applies when type is set to snackbar.
  • options.onDismiss [Function]: Called when the notice is dismissed.

Returns

  • Object: Action object.

createSuccessNotice

Returns an action object used in signalling that a success notice is to be created. Refer to createNotice for options documentation.

Related

  • createNotice

Usage

import { __ } from '@wordpress/i18n';
import { useDispatch } from '@wordpress/data';
import { store as noticesStore } from '@wordpress/notices';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
	const { createSuccessNotice } = useDispatch( noticesStore );
	return (
		<Button
			onClick={ () =>
				createSuccessNotice( __( 'Success!' ), {
					type: 'snackbar',
					icon: '🔥',
				} )
			}
		>
			{ __( 'Generate a snackbar success notice!' ) }
		</Button>
	);
};

Parameters

  • content string: Notice message.
  • options [Object]: Optional notice options.

Returns

  • Object: Action object.

createWarningNotice

Returns an action object used in signalling that a warning notice is to be created. Refer to createNotice for options documentation.

Related

  • createNotice

Usage

import { __ } from '@wordpress/i18n';
import { useDispatch } from '@wordpress/data';
import { store as noticesStore } from '@wordpress/notices';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
	const { createWarningNotice, createInfoNotice } =
		useDispatch( noticesStore );
	return (
		<Button
			onClick={ () =>
				createWarningNotice( __( 'Warning!' ), {
					onDismiss: () => {
						createInfoNotice(
							__( 'The warning has been dismissed!' )
						);
					},
				} )
			}
		>
			{ __( 'Generates a warning notice with onDismiss callback' ) }
		</Button>
	);
};

Parameters

  • content string: Notice message.
  • options [Object]: Optional notice options.

Returns

  • Object: Action object.

removeAllNotices

Removes all notices from a given context. Defaults to the default context.

Usage

import { __ } from '@wordpress/i18n';
import { useDispatch, useSelect } from '@wordpress/data';
import { store as noticesStore } from '@wordpress/notices';
import { Button } from '@wordpress/components';

export const ExampleComponent = () => {
	const notices = useSelect( ( select ) =>
		select( noticesStore ).getNotices()
	);
	const { removeAllNotices } = useDispatch( noticesStore );
	return (
		<>
			<ul>
				{ notices.map( ( notice ) => (
					<li key={ notice.id }>{ notice.content }</li>
				) ) }
			</ul>
			<Button onClick={ () => removeAllNotices() }>
				{ __( 'Clear all notices', 'woo-gutenberg-products-block' ) }
			</Button>
			<Button onClick={ () => removeAllNotices( 'snackbar' ) }>
				{ __(
					'Clear all snackbar notices',
					'woo-gutenberg-products-block'
				) }
			</Button>
		</>
	);
};

Parameters

  • noticeType string: The context to remove all notices from.
  • context string: The context to remove all notices from.

Returns

  • Object: Action object.

removeNotice

Returns an action object used in signalling that a notice is to be removed.

Usage

import { __ } from '@wordpress/i18n';
import { useDispatch } from '@wordpress/data';
import { store as noticesStore } from '@wordpress/notices';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
	const notices = useSelect( ( select ) =>
		select( noticesStore ).getNotices()
	);
	const { createWarningNotice, removeNotice } = useDispatch( noticesStore );

	return (
		<>
			<Button
				onClick={ () =>
					createWarningNotice( __( 'Warning!' ), {
						isDismissible: false,
					} )
				}
			>
				{ __( 'Generate a notice' ) }
			</Button>
			{ notices.length > 0 && (
				<Button onClick={ () => removeNotice( notices[ 0 ].id ) }>
					{ __( 'Remove the notice' ) }
				</Button>
			) }
		</>
	);
};

Parameters

  • id string: Notice unique identifier.
  • context [string]: Optional context (grouping) in which the notice is intended to appear. Defaults to default context.

Returns

  • Object: Action object.

removeNotices

Returns an action object used in signalling that several notices are to be removed.

Usage

import { __ } from '@wordpress/i18n';
import { useDispatch, useSelect } from '@wordpress/data';
import { store as noticesStore } from '@wordpress/notices';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
	const notices = useSelect( ( select ) =>
		select( noticesStore ).getNotices()
	);
	const { removeNotices } = useDispatch( noticesStore );
	return (
		<>
			<ul>
				{ notices.map( ( notice ) => (
					<li key={ notice.id }>{ notice.content }</li>
				) ) }
			</ul>
			<Button
				onClick={ () =>
					removeNotices( notices.map( ( { id } ) => id ) )
				}
			>
				{ __( 'Clear all notices' ) }
			</Button>
		</>
	);
};

Parameters

  • ids string[]: List of unique notice identifiers.
  • context [string]: Optional context (grouping) in which the notices are intended to appear. Defaults to default context.

Returns

  • Object: Action object.