@justeattakeaway/pie-toast-provider

Source Code | Design Documentation | NPM

@justeattakeaway/pie-toast-provider is a Web Component built using the Lit library. It offers a simple and accessible toast provider component for web applications.

Table of Contents

• Installation
• Documentation
  • Properties
  • Slots
  • CSS Variables
  • Events
• Usage Examples
  • Creating Toasts with toaster
  • Multiple Providers
• Questions and Support
• Contributing

Installation

To install any of our web components in your application, we would suggest following the getting started guide to set up your project.

Ideally, you should install the component using the @justeattakeaway/pie-webc package, which includes all of the components. Or you can install the individual component package.

Documentation

Properties

| Prop | Options | Description | Default | |----------|---------|---------------------------------------------------------------------------------------------------|---------| | options | {} | Default options for all toasts; accepts all toast props. | {} | | position | "default", "bottom-left", "bottom-right", "bottom-center" | Sets the position of the toast provider. When set to default, the toasts will be positioned at bottom-left for RTL languages and bottom-right for LTR languages. | default |

Slots

This component does not have any slots. All content is controlled through properties.

CSS Variables

| Name | Description | Default | |--------------------------|---------------------------------------------|-----------------------------| | --toast-provider-z-index | Controls the stacking order of the toasts. | --dt-z-index-toast (6000) | | --toast-provider-position | Controls the CSS positioning of the provider. Set to absolute to position relative to the nearest positioned ancestor instead of the viewport. | fixed | | --toast-provider-offset | Controls the gap between toasts and the boundary of the viewport. | --dt-spacing-c (Desktop) / --dt-spacing-d (Mobile) |

Events

| Event | Description | |-----------------------------------|--------------------------------------------------| | pie-toast-provider-queue-update | Triggered when a toast is added or removed from the queue. |

Usage Examples

The usage guideline is:

• Place pie-toast-provider wherever toasts should appear (e.g. root of your application, page or inside a modal).
• Use the toaster utility to dynamically create toasts from anywhere in your app.

For HTML:

// import as module into a js file e.g. main.js
import '@justeattakeaway/pie-webc/components/toast-provider.js'

<!-- pass js file into <script> tag -->
<pie-toast-provider></pie-toast-provider>
<script type="module" src="/main.js"></script>

For Native JS Applications, Vue, Angular, Svelte etc.:

// Vue templates (using Nuxt 3)
import '@justeattakeaway/pie-webc/components/toast-provider.js';

<pie-toast-provider></pie-toast-provider>

For React Applications:

import { PieToastProvider } from '@justeattakeaway/pie-webc/react/toast-provider.js';

<PieToastProvider></PieToastProvider>

Creating Toasts with toaster

The toaster utility dynamically creates toasts. It can be imported and called from any file or component in your application.

import { toaster } from '@justeattakeaway/pie-webc/components/toast-provider.js';

toaster.create({
  message: 'This is a success toast!',
  variant: 'success',
  isDismissible: true,
});

To clear all active and queued toasts:

toaster.clearAll();

Multiple Providers

You can use multiple pie-toast-provider instances in the same page or application (e.g. one at the root level and one inside a modal). Each provider maintains its own independent toast queue and logic.

When providerId is not specified, the toaster utility resolves the target provider automatically:

• If there is only one provider in the DOM, it is always used.
• If there are multiple providers, the provider in the nearest containing scope of the currently focused element is used. For example, if a button inside a modal triggers a toast, the modal's own provider is selected.

For explicit control when using multiple providers, give each one a native id attribute and pass the providerId option when creating or clearing toasts:

<pie-toast-provider id="main"></pie-toast-provider>

<pie-modal>
  <pie-toast-provider id="modal" position="bottom-center"></pie-toast-provider>
</pie-modal>

import { toaster } from '@justeattakeaway/pie-webc/components/toast-provider.js';

// Target the main page provider
toaster.create({
  message: 'Saved successfully!',
  variant: 'success',
  providerId: 'main',
});

// Target the modal provider
toaster.create({
  message: 'Form submitted!',
  variant: 'success',
  providerId: 'modal',
});

To clear toasts for a specific provider:

toaster.clearAll('modal');

Questions and Support

If you work at Just Eat Takeaway.com, please contact us on #help-designsystem. Otherwise, please raise an issue on Github.

Contributing

Check out our contributing guide for more information on local development and how to run specific component tests.