Notistack npm library documentation website logo
npm downloads

This is a guide for migration from notistack v2 (and below) to v3.

Notistack v3 primarily focuses on flexibility, scalibity and customisation. There has been numerous issues and pull requests on the repository asking support for customising Snackbars more easily.

So far, customisation was only possible by overriding the existing styles, but this is not always enough. There is only so much you can do by overriding styles. Since we can't cover everyone's requirements natively on notistack, in v3, we give you the tools to build your own Snackbars. This is achieved through Components prop.

  • content prop is still supported but marked as deprecated and it will be removed in future releases. If you find yourself using this prop quite often, consider defining your own custom variant/content using Components props.

  • Drop ariaAttributes from props. If you need to pass aria-attributes, use a custom component.

  • HTML attributes applied to Snackbar root component should be passed inside SnackbarProps prop.

<SnackbarProvider
-    data-test="test"
+    SnackbarProps={{
+        'data-test': 'test',
+    }}
>
</SnackbarProvider>

enqueueSnackbar('message', {
-    'data-test': 'test',
+    SnackbarProps: {
+       'data-test': 'test',
+    },
})
  • Drop support for resumeHideDuration, onEntering and onExisting transition callbacks due to the fact that they are rarely used. Get in touch if this decision affects you to potentially bring them back to life.

  • onClose won't be called with reason: 'clickaway'. Notistack never needed this functionality and it was something inherited from Material-UI. This change is done to reduce bundle size.

  • Drop Customisation through classes.variant(Success|Error|Info|Warning). To customise Snackbars according to their variant, use customization.

  • Any customisation through Material-UI theme is not applied to the elements. This would also mean toggling Material-UI theme mode to Dark/Light would not affect the appearance of snackbars. You can easily use a custom component to have full control over your snackbars. This example demonstrates how your snackbars can react to change of theme mode.

  • Drop support for withSnackbar Higher-order component (HOC). Consequently, exported type WithSnackbarProps which was kept in type declerations for backwards compatibility for over a year, has been also removed. (ProviderContext type can be used instead). There are two options to migrate the code:

    • Option 1: Migrate your code to be functional component and use useSnackar.
    • Option 2: Remove withSnackbar and import the function(s) you need directly from notistack:
- import { withSnackbar } from 'notistack'
+ import { enqueueSnackbar, closeSnackbar } from 'notistack'

class MyButton extends React.Component {
    render() {
-       const { enqueueSnackbar } = this.props
    }
}

- export default withSnackbar(MyButton)
+ export default MyButton

You can now define your own variants and show entirely customized Snackbars. Your custom component accepts all props passed to enqueueSnackbar or SnackbarProvider, so you have full control over it. On top of that, you'll be able pass additional options in options parameter of enqueueSnackbar. Example usage:

<SnackbarProvider
    Components={{
        success: MyCustomSuccessNotification,
        reportComplete: ReportComplete,
    }}
>
</SnackbarProvider>

interface ReportCompleteProps extends CustomContentProps {
    allowDownload: boolean;
}

const ReportComplete = React.forwardRef((props: ReportCompleteProps, ref) => {
    const {
        // You have access to notistack props, options 👇🏼
        variant,
        message
        // as well as your own custom props 👇🏼
        allowDownload,
    } = props;

    //
})

enqueueSnackbar('Your report is ready to download', {
   variant: 'reportComplete',
   persist: true,
   allowDownload: true, // <-- pass any additional options
})