[Snackbar] Display stacked Snackbars

docs/data/material/components/snackbars/snackbars.md

@@ -18,8 +18,6 @@ They may contain a text action, but no icons. You can use them to display notifi
 
 {{"component": "modules/components/ComponentLinkHeader.js"}}
 
-**Frequency**: Only one snackbar may be displayed at a time.
-
 ## Simple snackbars
 
 A basic snackbar that aims to reproduce Google Keep's snackbar behavior.
@@ -40,6 +38,26 @@ You can control the position of the snackbar by specifying the `anchorOrigin` pr
 
 {{"demo": "PositionedSnackbar.js"}}
 
+## Stacked snackbars
+
+The `Snackbar` component doesn't yet support displaying multiple stacked snackbars out of the box.
+However, there are currently two complementary alternatives to do that:
+
+### Lab's stacked snackbars
+
+We have been developing a native component to support this use case and [we've made it available in the lab](/material-ui/react-stacked-snackbars/) to gather feedback for its first versions and general API design.
+
+### notistack
+
+![stars](https://img.shields.io/github/stars/iamhosseindhv/notistack.svg?style=social&label=Stars)
+![npm downloads](https://img.shields.io/npm/dm/notistack.svg)
+
+This example demonstrates how to use [notistack](https://github.com/iamhosseindhv/notistack).
+notistack has an **imperative API** that makes it easy to display snackbars, without having to handle their open/close state.
+It also enables you to **stack** them on top of one another (although this is discouraged by the Material Design guidelines).
+
+{{"demo": "IntegrationNotistack.js", "defaultCodeOpen": false}}
+
 ## Message Length
 
 Some snackbars with varying message length.
@@ -88,21 +106,6 @@ Other examples:
 
 {{"demo": "DirectionSnackbar.js"}}
 
-## Complementary projects
-
-For more advanced use cases you might be able to take advantage of:
-
-### notistack
-
-![stars](https://img.shields.io/github/stars/iamhosseindhv/notistack.svg?style=social&label=Stars)
-![npm downloads](https://img.shields.io/npm/dm/notistack.svg)
-
-This example demonstrates how to use [notistack](https://github.com/iamhosseindhv/notistack).
-notistack has an **imperative API** that makes it easy to display snackbars, without having to handle their open/close state.
-It also enables you to **stack** them on top of one another (although this is discouraged by the Material Design guidelines).
-
-{{"demo": "IntegrationNotistack.js", "defaultCodeOpen": false}}
-
 ## Accessibility
 
 (WAI-ARIA: https://www.w3.org/TR/wai-aria-1.1/#alert)

docs/data/material/components/stacked-snackbars/CustomizedSnackbars.js

@@ -0,0 +1,46 @@
+import * as React from 'react';
+import SnackbarsProvider from '@mui/lab/SnackbarsProvider';
+import useSnackbars from '@mui/lab/useSnackbars';
+import Button from '@mui/material/Button';
+import MuiAlert from '@mui/material/Alert';
+import Stack from '@mui/material/Stack';
+
+const Alert = React.forwardRef(function Alert(props, ref) {
+  return <MuiAlert elevation={6} ref={ref} variant="filled" {...props} />;
+});
+
+function MyApp() {
+  const snackbars = useSnackbars();
+
+  return (
+    <Stack spacing={2} sx={{ width: '100%' }}>
+      <Button
+        variant="outlined"
+        onClick={() =>
+          snackbars.showSnackbar({
+            content: (key) => (
+              <Alert
+                onClose={snackbars.closeSnackbar(key)}
+                severity="success"
+                sx={{ width: '100%' }}
+              >
+                This is a success message!
+              </Alert>
+            ),
+          })
+        }
+      >
+        Open success snackbar
+      </Button>
+      <Alert severity="success">This is a success message!</Alert>
+    </Stack>
+  );
+}
+
+export default function CustomizedSnackbars() {
+  return (
+    <SnackbarsProvider autoHideDuration={4000}>
+      <MyApp />
+    </SnackbarsProvider>
+  );
+}

docs/data/material/components/stacked-snackbars/CustomizedSnackbars.tsx

@@ -0,0 +1,49 @@
+import * as React from 'react';
+import SnackbarsProvider from '@mui/lab/SnackbarsProvider';
+import useSnackbars from '@mui/lab/useSnackbars';
+import Button from '@mui/material/Button';
+import MuiAlert, { AlertProps } from '@mui/material/Alert';
+import Stack from '@mui/material/Stack';
+
+const Alert = React.forwardRef<HTMLDivElement, AlertProps>(function Alert(
+  props,
+  ref,
+) {
+  return <MuiAlert elevation={6} ref={ref} variant="filled" {...props} />;
+});
+
+function MyApp() {
+  const snackbars = useSnackbars();
+
+  return (
+    <Stack spacing={2} sx={{ width: '100%' }}>
+      <Button
+        variant="outlined"
+        onClick={() =>
+          snackbars.showSnackbar({
+            content: (key: string) => (
+              <Alert
+                onClose={snackbars.closeSnackbar(key)}
+                severity="success"
+                sx={{ width: '100%' }}
+              >
+                This is a success message!
+              </Alert>
+            ),
+          })
+        }
+      >
+        Open success snackbar
+      </Button>
+      <Alert severity="success">This is a success message!</Alert>
+    </Stack>
+  );
+}
+
+export default function CustomizedSnackbars() {
+  return (
+    <SnackbarsProvider autoHideDuration={4000}>
+      <MyApp />
+    </SnackbarsProvider>
+  );
+}

docs/data/material/components/stacked-snackbars/CustomizedSnackbars.tsx.preview

@@ -0,0 +1,3 @@
+<SnackbarsProvider autoHideDuration={4000}>
+  <MyApp />
+</SnackbarsProvider>

docs/data/material/components/stacked-snackbars/GlobalActionSnackbars.js

@@ -0,0 +1,53 @@
+import * as React from 'react';
+import SnackbarsProvider from '@mui/lab/SnackbarsProvider';
+import Button from '@mui/material/Button';
+import useSnackbars from '@mui/lab/useSnackbars';
+import IconButton from '@mui/material/IconButton';
+import CloseIcon from '@mui/icons-material/Close';
+
+function MyApp() {
+  const snackbars = useSnackbars();
+
+  return (
+    <React.Fragment>
+      <Button onClick={() => snackbars.showSnackbar({ message: 'Note Archived' })}>
+        Show Snackbar 1 with same action
+      </Button>
+      <Button onClick={() => snackbars.showSnackbar({ message: 'I love snacks' })}>
+        Show Snackbar 2 with same action
+      </Button>
+    </React.Fragment>
+  );
+}
+
+export default function GlobalActionSnackbars() {
+  const snackbarRef = React.useRef(null);
+
+  return (
+    <SnackbarsProvider
+      ref={snackbarRef}
+      autoHideDuration={4000}
+      action={(key) => (
+        <React.Fragment>
+          <Button
+            color="secondary"
+            size="small"
+            onClick={snackbarRef.current.closeSnackbar(key)}
+          >
+            UNDO
+          </Button>
+          <IconButton
+            size="small"
+            aria-label="close"
+            color="inherit"
+            onClick={snackbarRef.current.closeSnackbar(key)}
+          >
+            <CloseIcon fontSize="small" />
+          </IconButton>
+        </React.Fragment>
+      )}
+    >
+      <MyApp />
+    </SnackbarsProvider>
+  );
+}

docs/data/material/components/stacked-snackbars/GlobalActionSnackbars.tsx

@@ -0,0 +1,53 @@
+import * as React from 'react';
+import SnackbarsProvider, { CloseSnackbarRef } from '@mui/lab/SnackbarsProvider';
+import Button from '@mui/material/Button';
+import useSnackbars from '@mui/lab/useSnackbars';
+import IconButton from '@mui/material/IconButton';
+import CloseIcon from '@mui/icons-material/Close';
+
+function MyApp() {
+  const snackbars = useSnackbars();
+
+  return (
+    <React.Fragment>
+      <Button onClick={() => snackbars.showSnackbar({ message: 'Note Archived' })}>
+        Show Snackbar 1 with same action
+      </Button>
+      <Button onClick={() => snackbars.showSnackbar({ message: 'I love snacks' })}>
+        Show Snackbar 2 with same action
+      </Button>
+    </React.Fragment>
+  );
+}
+
+export default function GlobalActionSnackbars() {
+  const snackbarRef = React.useRef<CloseSnackbarRef>(null);
+
+  return (
+    <SnackbarsProvider
+      ref={snackbarRef}
+      autoHideDuration={4000}
+      action={(key) => (
+        <React.Fragment>
+          <Button
+            color="secondary"
+            size="small"
+            onClick={snackbarRef.current!.closeSnackbar(key)}
+          >
+            UNDO
+          </Button>
+          <IconButton
+            size="small"
+            aria-label="close"
+            color="inherit"
+            onClick={snackbarRef.current!.closeSnackbar(key)}
+          >
+            <CloseIcon fontSize="small" />
+          </IconButton>
+        </React.Fragment>
+      )}
+    >
+      <MyApp />
+    </SnackbarsProvider>
+  );
+}

docs/data/material/components/stacked-snackbars/GlobalContentSnackbars.js

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import SnackbarsProvider from '@mui/lab/SnackbarsProvider';
+import Button from '@mui/material/Button';
+import useSnackbars from '@mui/lab/useSnackbars';
+import MuiAlert from '@mui/material/Alert';
+
+const Alert = React.forwardRef(function Alert(props, ref) {
+  return <MuiAlert elevation={6} ref={ref} variant="filled" {...props} />;
+});
+
+function MyApp() {
+  const snackbars = useSnackbars();
+
+  return (
+    <React.Fragment>
+      <Button onClick={() => snackbars.showSnackbar()}>
+        Show Snackbar 1 with same content
+      </Button>
+      <Button onClick={() => snackbars.showSnackbar()}>
+        Show Snackbar 2 with same content
+      </Button>
+    </React.Fragment>
+  );
+}
+
+export default function GlobalContentSnackbars() {
+  const snackbarRef = React.useRef(null);
+
+  return (
+    <SnackbarsProvider
+      ref={snackbarRef}
+      autoHideDuration={4000}
+      anchorOrigin={{ vertical: 'top', horizontal: 'right' }}
+      content={(key) => (
+        <Alert
+          onClose={snackbarRef.current.closeSnackbar(key)}
+          severity="warning"
+          sx={{ width: '100%' }}
+        >
+          This is a warning message!
+        </Alert>
+      )}
+    >
+      <MyApp />
+    </SnackbarsProvider>
+  );
+}

docs/data/material/components/stacked-snackbars/GlobalContentSnackbars.tsx

@@ -0,0 +1,50 @@
+import * as React from 'react';
+import SnackbarsProvider, { CloseSnackbarRef } from '@mui/lab/SnackbarsProvider';
+import Button from '@mui/material/Button';
+import useSnackbars from '@mui/lab/useSnackbars';
+import MuiAlert, { AlertProps } from '@mui/material/Alert';
+
+const Alert = React.forwardRef<HTMLDivElement, AlertProps>(function Alert(
+  props,
+  ref,
+) {
+  return <MuiAlert elevation={6} ref={ref} variant="filled" {...props} />;
+});
+
+function MyApp() {
+  const snackbars = useSnackbars();
+
+  return (
+    <React.Fragment>
+      <Button onClick={() => snackbars.showSnackbar()}>
+        Show Snackbar 1 with same content
+      </Button>
+      <Button onClick={() => snackbars.showSnackbar()}>
+        Show Snackbar 2 with same content
+      </Button>
+    </React.Fragment>
+  );
+}
+
+export default function GlobalContentSnackbars() {
+  const snackbarRef = React.useRef<CloseSnackbarRef>(null);
+
+  return (
+    <SnackbarsProvider
+      ref={snackbarRef}
+      autoHideDuration={4000}
+      anchorOrigin={{ vertical: 'top', horizontal: 'right' }}
+      content={(key) => (
+        <Alert
+          onClose={snackbarRef.current!.closeSnackbar(key)}
+          severity="warning"
+          sx={{ width: '100%' }}
+        >
+          This is a warning message!
+        </Alert>
+      )}
+    >
+      <MyApp />
+    </SnackbarsProvider>
+  );
+}

docs/data/material/components/stacked-snackbars/GlobalContentSnackbars.tsx.preview

@@ -0,0 +1,16 @@
+<SnackbarsProvider
+  ref={snackbarRef}
+  autoHideDuration={4000}
+  anchorOrigin={{ vertical: 'top', horizontal: 'right' }}
+  content={(key) => (
+    <Alert
+      onClose={snackbarRef.current!.closeSnackbar(key)}
+      severity="warning"
+      sx={{ width: '100%' }}
+    >
+      This is a warning message!
+    </Alert>
+  )}
+>
+  <MyApp />
+</SnackbarsProvider>