, 'title'> {
+ /**
+ * Title of the toast. Should be used with text only. Do not pass complex content or custom components.
+ * Ensure to always pass a title. It's currently marked as optional for backwards compatibility.
+ * In a future major release, this will be required.
+ */
title?: ReactNode;
- color?: ToastColor;
+ /**
+ * Main component text. Accepts text, text block elements such as ``, and inline elements such as ``, ``, `` or ``.
+ * Avoid passing complex layouts or custom components. Use `children` instead.
+ */
+ text?: ReactNode;
+ /**
+ * Can be used for additional, non-inline content. Use sparingly, as toasts are not meant to have complex content.
+ * Where possible, use `text` and `actionProps` instead to display text and actions.
+ */
+ children?: ReactNode;
+ color?: EuiToastColor;
+ /**
+ * Defines a custom icon to be displayed.
+ * When no `iconType` is set, a default icon will be used based on the `color` of the toast.
+ */
iconType?: IconType;
onClose?: () => void;
+ /**
+ * Duration in milliseconds that drives a countdown animation on the toast's decor bar.
+ * When not set the bar is static at full width.
+ */
+ animationMs?: number;
+ /**
+ * Props for primary and secondary actions within the toast.
+ */
+ actionProps?: {
+ primary?: EuiToastActionPrimaryProps;
+ secondary?: EuiToastActionSecondaryProps;
+ };
}
export const EuiToast: FunctionComponent = ({
title,
- color,
+ text,
+ color = 'primary',
iconType,
- onClose,
children,
className,
+ actionProps,
+ style,
+ onClose,
+ animationMs,
...rest
}) => {
- const baseStyles = useEuiMemoizedStyles(euiToastStyles);
- const baseCss = [baseStyles.euiToast, color && baseStyles.colors[color]];
+ const { euiTheme } = useEuiTheme();
+
+ const styles = useEuiMemoizedStyles(euiToastStyles);
+ const iconStyles = useEuiMemoizedStyles(euiNotificationIconStyles);
const headerStyles = useEuiMemoizedStyles(euiToastHeaderStyles);
- const headerCss = [
- headerStyles.euiToastHeader,
- children && headerStyles.withBody,
- ];
- const classes = classNames('euiToast', className);
+ const cssStyles = [styles.euiToast];
+ const decorCssStyles = [styles.decor, animationMs && styles.hasAnimation];
+
+ const classes = classNames('euiToast', className, {
+ [`euiToast--${color}`]: color,
+ });
+
+ const highlightColorToken = getTokenName(
+ 'borderStrong',
+ color
+ ) as keyof _EuiThemeBorderColors;
+ const typeColor = euiTheme.colors[highlightColorToken];
+ const backgroundLightToken = getTokenName(
+ 'backgroundLight',
+ color
+ ) as keyof _EuiThemeBackgroundColors;
+ const backgroundLightColor = euiTheme.colors[backgroundLightToken];
+
+ const cssVariables = useMemo(
+ () => ({
+ '--euiToastTypeColor': typeColor,
+ '--euiToastTypeBackgroundColor': backgroundLightColor,
+ ...(animationMs && {
+ '--euiToastAnimationMs': `${animationMs}ms`,
+ }),
+ }),
+ [typeColor, backgroundLightColor, animationMs]
+ );
+
+ const dismissButton = useMemo(() => {
+ if (!onClose) return;
+
+ return (
+
+ {(dismissToast: string) => (
+
+ )}
+
+ );
+ }, [onClose, styles]);
+
+ const header = useMemo(() => {
+ if (!title) return;
+
+ const headerCssStyles = [
+ headerStyles.euiToastHeader,
+ onClose && headerStyles.hasDismissButton,
+ ];
+
+ return (
+
+ {title}
+
+ );
+ }, [title, headerStyles, onClose]);
+
+ const icon = useMemo(() => {
+ if (!iconType) {
+ const defaultIconType = COLOR_TO_NOTIFICATION_ICON_MAP[color] ?? 'info';
+
+ return (
+
+ );
+ }
+
+ return (
+
+ );
+ }, [iconType, color, typeColor, styles, iconStyles]);
+
+ const optionalChildren = useMemo(() => {
+ if (!text && !children) return null;
+
+ return (
+
+ {text && (
+
+ {text}
+
+ )}
+ {children && (
+
+ {children}
+
+ )}
+
+ );
+ }, [text, children, styles]);
+
+ const actionControls = useMemo(() => {
+ const actionPrimaryProps = {
+ ...actionProps?.primary,
+ color: color,
+ };
+ const actionSecondaryProps = {
+ ...actionProps?.secondary,
+ color: color,
+ };
+ const hasActionPrimary = Boolean(actionProps?.primary);
+ const hasActionSecondary = Boolean(actionProps?.secondary);
+
+ if (!hasActionPrimary && !hasActionSecondary) return null;
+
+ const actionPrimary = hasActionPrimary && (
+
+ );
+
+ const actionSecondary = hasActionSecondary && (
+
+ );
+
+ return (
+
+ {actionPrimary}
+ {actionSecondary}
+
+ );
+ }, [actionProps, color, styles]);
return (
-
+
+
{/* Screen reader announcement */}
@@ -62,57 +278,32 @@ export const EuiToast: FunctionComponent = ({
/>
+
+
+ {icon}
- {/* Header */}
-
- {(notification: string) => (
-
- {iconType && (
-
- )}
-
-
- {title}
-
+
+ {
+ // Note: the DOM position of the dismiss button matters to screen reader users.
+ // We generally want them to have some context of _what_ they're dismissing,
+ // instead of navigating to the dismiss button first before the content
+ header && optionalChildren ? (
+ <>
+ {header}
+ {dismissButton}
+ {optionalChildren}
+
+ ) : (
+ <>
+ {header || optionalChildren}
+ {dismissButton}
+
+ )
+ }
- )}
-
-
- {/* Close button */}
- {onClose && (
-
- {(dismissToast: string) => (
-
- )}
-
- )}
-
- {/* Body */}
- {children && (
-
- {children}
-
- )}
+
);
};
diff --git a/packages/eui/src/components/toast/toast_action.tsx b/packages/eui/src/components/toast/toast_action.tsx
new file mode 100644
index 000000000000..cc60aa0486cc
--- /dev/null
+++ b/packages/eui/src/components/toast/toast_action.tsx
@@ -0,0 +1,60 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import React from 'react';
+
+import { ExclusiveUnion } from '../common';
+import { EuiButton, EuiButtonEmpty, EuiButtonEmptyProps } from '../button';
+import { Props as EuiButtonProps } from '../button/button';
+import { EuiToastColor } from './types';
+
+export type EuiToastActionPrimaryProps = Omit<
+ EuiButtonProps,
+ 'color' | 'size' | 'fill'
+>;
+
+export type EuiToastActionSecondaryProps = Omit<
+ EuiButtonEmptyProps,
+ 'color' | 'size' | 'flush'
+>;
+
+type EuiToastActionPrimary = EuiToastActionPrimaryProps & {
+ actionType: 'primary';
+};
+
+type EuiToastActionSecondary = EuiToastActionSecondaryProps & {
+ actionType: 'secondary';
+};
+
+type EuiToastActionProps = ExclusiveUnion<
+ EuiToastActionPrimary,
+ EuiToastActionSecondary
+>;
+
+export const EuiToastAction = ({
+ children,
+ actionType = 'primary',
+ color = 'primary',
+ ...rest
+}: EuiToastActionProps & {
+ color?: EuiToastColor;
+}) => {
+ if (actionType === 'primary') {
+ return (
+
+ {children}
+
+ );
+ } else {
+ return (
+
+ {children}
+
+ );
+ }
+};
diff --git a/packages/eui/src/components/toast/types.ts b/packages/eui/src/components/toast/types.ts
new file mode 100644
index 000000000000..6bffb7e67cc6
--- /dev/null
+++ b/packages/eui/src/components/toast/types.ts
@@ -0,0 +1,10 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+export const COLORS = ['primary', 'success', 'warning', 'danger'] as const;
+export type EuiToastColor = (typeof COLORS)[number];
diff --git a/packages/website/docs/components/display/toast/_guidelines.mdx b/packages/website/docs/components/display/toast/_guidelines.mdx
index ca69e5476189..348a8d26eb2c 100644
--- a/packages/website/docs/components/display/toast/_guidelines.mdx
+++ b/packages/website/docs/components/display/toast/_guidelines.mdx
@@ -1,4 +1,4 @@
-import { EuiButton, EuiCallOut, EuiFlexGroup, EuiFlexItem, EuiSpacer, EuiToast } from '@elastic/eui';
+import { EuiCallOut, EuiFlexGroup, EuiFlexItem, EuiSpacer, EuiToast } from '@elastic/eui';
This page documents patterns for using toasts, short messages that appears on the lower right corner and time out after a few seconds. They are a popular design choice because they don't need to fit in a layout and don't disrupt the user.
@@ -116,61 +116,52 @@ By default, a toast stays on the screen 10 seconds. Users should be able read th
-### Toasts should only contain a single action
+### Toasts can have max. two actions
-A toast can have a single action, styled as a standard button. If more actions are needed, or if the action is important enough to interrupt the user, use a modal instead.
+A toast should have a single action most of the time. If you need a secondary one, you can include it.
+If even more actions are needed, or if the action is important enough to interrupt the user, use a modal instead.
-
+
-
- Download
-
-
+ actionProps={{ primary: { children: 'Download' } }}
+ />
-
-
- Cancel
-
-
- Delete
-
-
-
+ actionProps={{
+ primary: { children: 'Cancel' },
+ secondary: { children: 'Delete' },
+ }}
+ />
### Icons should emphasize actions
-An icon on the left of the message can help define the message type.
+Each color variant automatically displays a corresponding icon. Use `iconType` only when you need to override it with something more specific to the context.
-
+
-
+
-
- Learn more
-
-
+ actionProps={{
+ primary: { children: 'Learn more' },
+ }}
+ />
- The maximum bucket size of 200 was exceeded.
-
- {}}>See the full error
-
-
+ text="The maximum bucket size of 200 was exceeded."
+ actionProps={{
+ primary: { children: 'See the full error' },
+ }}
+ />
- An extremely long error trace.
-
+ />
diff --git a/packages/website/docs/components/display/toast/index.mdx b/packages/website/docs/components/display/toast/index.mdx
index 2a83fea1b65e..02b07357fcfb 100644
--- a/packages/website/docs/components/display/toast/index.mdx
+++ b/packages/website/docs/components/display/toast/index.mdx
@@ -18,12 +18,11 @@ They should not be used for historical actions (**your report built 30 minutes a
import { EuiToast } from '@elastic/eui';
export default () => (
-
{}}>
-
- A good toast message is short and to the point. It should very rarely
- include multiple paragraphs.
-
-
+
{}}
+ />
);
```
@@ -161,72 +160,52 @@ export default () => {
};
```
-### Info
+### Colors
-For informative messages use `type="info"`.
+Each `color` variant displays a specific visual type toast and renders by default a corresponding icon.
-
- ```tsx interactive
- import React from 'react';
- import { EuiToast } from '@elastic/eui';
+* Use `primary` for general information.
+* Use `success` to let the user know that something completed successfully. Show a success message when the program detects that **something completed successfully**.
+* Use `warning` to warn the user against decisions they might regret. Show a warning message when the program detects that **something is not behaving right, but it didn't cause any termination.**
+* Use `danger` to let the user know that something went wrong. For example if you want to communicate an error. You should show an error message when the issue is **terminal, this doesn't always mean that the operation stops completely, but the task is not complete**.
- export default () => (
- {}}>
-
- Icons should be used rarely. They are good for warnings, but when paired
- with long titles they look out of place.
-
-
- );
- ```
-
-
-### Success
-
-For success messages use `color="success"`.
+If you need to use a custom icon, use the `iconType` prop to override it.
```tsx interactive
import React from 'react';
- import {
- EuiButton,
- EuiLink,
- EuiToast,
- EuiFlexGroup,
- EuiFlexItem,
- } from '@elastic/eui';
+ import { EuiToast, EuiSpacer } from '@elastic/eui';
export default () => (
-
-
- While the layout will adjust properly for wrapping titles, they do not
- look particularly good. Similarly, do not use a whole lot of text in your
- body either. At a certain point people will not have enough time to read
- these things. Like, you probably are not even reading this now.
-
-
-
- And some other stuff on another line, just for kicks. And{' '}
- here’s a link.
-
-
-
-
- Download report
-
-
-
+ <>
+
+
+
+
+
+
+
+
+
);
```
-### Warning
+### Actions
-Use this callout to warn the user against decisions they might regret. Show a warning message when the program detects that **something is not behaving right, but it didn't cause any termination.** For warning messages use `color="warning"`.
+Use `actionProps` to add a primary and an optional secondary action. A standalone secondary action without a primary is not supported.
```tsx interactive
@@ -235,40 +214,18 @@ Use this callout to warn the user against decisions they might regret. Show a wa
export default () => (
);
```
-### Danger
-
-Use this callout to let the user know that something went wrong. For example if you want to communicate an error. You should show an error message when the issue is **terminal, this doesn't always mean that the operation stops completely, but the task is not complete**. For errors messages use `color="danger"`.
-
-
- ```tsx interactive
- import React from 'react';
- import { EuiToast } from '@elastic/eui';
-
- const esError =
- 'Error: expected _scroll_id in the polling Elasticsearch response: ' +
- '{"took":0,"timed_out":false,"_shards":{"total":0,"successful":0,"skipped":0,"failed":0},' +
- '"hits":{"total":0,"max_score":0,"hits":[]}}';
-
- export default () => (
-
- {esError}
-
- );
- ```
-
-
## Guidelines
import Guidelines from './_guidelines.mdx';