Toast Notification Element

Overview

The <hype-toast> is a flexible component for displaying toast notifications. To use it manually, you must create and configure it using JavaScript in response to an event. This gives you full control over when and how toasts appear.

The primary use case is to show a notification when a Hype discount is applied or a campaign becomes active. To do this, you should listen for events from the HypeSDK and use the global Hype window objects to get campaign and configuration data.

Manual Usage

For prerequisites and an explanation of the integration patterns, please see the UI Elements Overview.

To display a toast, listen for a HypeSDK event and then create, configure, and append the <hype-toast> element to the page.

Example

This script shows how to display a toast that you have already configured in the Hype admin. It listens for the hype:campaigns-loaded event, finds the active campaign and its associated toast configuration, and then displays it.

For a full list of available SDK events, please refer to the HypeSDK Documentation.

document.addEventListener('hype:campaigns-loaded', () => {
	// Get data from the global window objects
	const activeCampaigns = window.Hype?.campaigns || [];
	const uiBlockSchemas = window.HypeUIBlocksSchema || {};

	for (const campaign of activeCampaigns) {
		const campaignBlocks = uiBlockSchemas[campaign.campaignId];
		if (!campaignBlocks) continue;

		// Find the specific toast block you configured
		const toastBlock = campaignBlocks.find((block) => block.type === 'toast');
		if (!toastBlock) continue;

		// 1. Create the element
		const toast = document.createElement('hype-toast');

		// 2. Configure it using the settings from your Hype admin
		toast.setAttribute('message', toastBlock.settings.message);
		toast.setAttribute('icon-name', toastBlock.settings.icon.name);
		toast.setAttribute('icon-type', toastBlock.settings.icon.type);
		toast.setAttribute('toast-position', toastBlock.settings.toast_position);

		if (toastBlock.settings.toastAutoClose) {
			toast.setAttribute('toast-auto-close', '');
		}

		// 3. Add it to the page to display it
		document.body.appendChild(toast);
	}
});

Attributes

When creating the element in JavaScript, you configure it with these attributes.

Attribute	Type	Description	Default
message	string	The text content to display in the toast.	null
icon-name	string	The name of an icon to display.	null
icon-type	filled | outline	The type of icon set to use.	filled
toast-auto-close	boolean	If this attribute is present, the toast will automatically disappear.	false
timeout	number	The time in milliseconds before the toast automatically disappears. Requires toast-auto-close.	7000
background-style	string	solid or a gradient variable (e.g., --magic-gradient).	solid
toast-position	string	e.g., top-right, bottom-center.	bottom-center
toast-width	fit | medium | full	The width of the toast container.	fit

Styling with CSS Custom Properties

Property	Description	Default
--background-color	The background color when background-style is solid.	#000
--color	The color of the message text and icon.	#fff
--font-size	The font size of the message text.	14px
--block-padding	The vertical padding (top and bottom).	8px
--inline-padding	The horizontal padding (left and right).	15px
--border-radius	The border radius of the toast container.	16px
--font-weight	The font weight of the message text.	normal
--content-alignment	The alignment of the icon and text. Can be flex-start or center.	center

Advanced Styling with Shadow Parts

For more granular control, you can directly style internal elements of the component using the ::part() CSS pseudo-element.

Example

/* Add a border to the toast */
hype-toast::part(normal-toast) {
	border: 2px solid purple;
}

/* Change the close button color on hover */
hype-toast::part(close-button):hover {
	color: red;
}

Available Parts

Part Name	Element Description
toast-main	The main wrapper for the entire component.
normal-toast	The visible container for the toast content.
message	The <p> tag containing the icon and text.
close-button	The container for the close button.