> For the complete documentation index, see [llms.txt](https://docs.jackf.red/jackfredlib/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.jackf.red/jackfredlib/jackfredlib-toasts/overview.md).

# Overview

The Toasts module is a simple way of showing [Toasts](https://en.wikipedia.org/wiki/Pop-up_notification) to the player. 

<figure><img src="/files/2XUaWztGDzUf0yMtQRqx" alt=""><figcaption><p>Example toast being created, with automatically gathered information</p></figcaption></figure>

Toasts created by this module are composed of a background [format](#built-in-formats), a title, an optional message, and optional icon made of an image file or ItemStack, and an optional progress bar along the bottom.

{% hint style="info" %}
Minecraft has 5 slots available to any given toast, and a given toast can be up to 5 slots in height. Any toasts not able to immediately be placed on the screen will be queued until there is space.

![](/files/Vb5XEkyFhYLrdpWRg7TL)
{% endhint %}

## Getting Started

The simplest way to get a message across is to use `Toasts.INSTANCE.sendFromMod()`:

```java
Toasts.INSTANCE.sendFromMod("jackfredlib", 
        Component.literal("Common code and hooks for JackFred's mods."))
```

This automatically grabs the icon and title from the given mod ID, adds the given message, and adds a timer and matching progress bar. You can see it in action in the above GIF.

## Using the Builder

For anything more interesting, you can use the builder from `ToastBuilder.builder()`. This allows you to use custom images, progress bar mechanics and colours.

{% code fullWidth="false" %}

```java
List<ItemStack> ironArmour = List.of(
        Items.IRON_HELMET.getDefaultInstance(),
        Items.IRON_CHESTPLATE.getDefaultInstance(),
        Items.IRON_LEGGINGS.getDefaultInstance(),
        Items.IRON_BOOTS.getDefaultInstance()
);

var items = ToastBuilder.builder(ToastFormat.DARK, Component.literal("New Armour!"))
        .addMessage(Component.literal("You have unlocked iron armour!"))
        .withIcon(ToastIcon.items(ironArmour))
        .progressShowsVisibleTime()
        .expiresAfter(4000L)
        .build();
        
Toasts.INSTANCE.send(items);
```

{% endcode %}

<figure><img src="/files/f1gjMq9iALHeyfZzwjvl" alt=""><figcaption><p>Toast cycling through a list of items</p></figcaption></figure>

## Built-in Formats

There are 4 built-in formats for toasts, recreating the 4 types used in the vanilla game. They are available under the `ToastFormat` class.

<figure><img src="/files/LrD08Wz6CTXBKG8mY7kH" alt=""><figcaption><p>An example of all the shipped toast formats, and their vanilla uses.</p></figcaption></figure>

{% hint style="info" %}
It is possible to create your own formats with according text and progress bar colours; simply create your own instance of the ToastFormat record. However, for multi-version mods the format varies depending on the version you are targeting:

* For 1.20.2 and above, create a GUI sprite as normal, [as seen here.](https://github.com/JackFred2/JackFredLib/tree/3c9986823554faa24d23907af3cc330f19b6280c/jackfredlib-toasts/src/client/resources/assets/jackfredlib-toasts/textures/gui/sprites)
* For 1.20.1 and below, you will need to supply the sprite and UV information in the code, [as seen here.](https://github.com/JackFred2/JackFredLib/blob/f2e5c647c873d9fe03f61358050f25be3799596d/jackfredlib-toasts/src/client/java/red/jackf/jackfredlib/client/api/toasts/ToastFormat.java)
  {% endhint %}

## Progress Bars

Progress bars are shown at the bottom of the toast. Their values range between 0f and 1f, and can be used in 3 different ways:

1. As an indicator for how long the toast has left, as seen in the above two examples;E
2. Pushing progress values from outside, by using `CustomToast.setProgress()` on the built toast object;
3. Pulling progress values from the toast every frame, by using `ToastBuilder.progressPuller()`.

## Images

Toasts can optionally have images, supplied via `ToastBuilder.withIcon()`. There are built-in methods to create icons that display textures, items or lists of items in the `ToastIcon` class.

```java
// shows a diamond as the icon
ToastBuilder.builder(ToastFormat.DARK, literal("with items"))
    .withIcon(ToastIcon.item(Items.DIAMOND.getDefaultInstance()))
    .build();
    
// make the item twice as large
ToastBuilder.builder(ToastFormat.DARK, literal("with items but bigger"))
    .withIcon(ToastIcon.item(Items.DIAMOND.getDefaultInstance(), 2))
    .build();
    
// an image under assets/mymod/image.png, with a size of 128x128px
// rendered on the toast at 20x20px
ResourceLocation image = ResourceLocation.fromNamespaceAndPath("mymod", "image.png");
ToastBuilder.builder(ToastFormat.DARK, literal("with image"))
    .withIcon(ToastIcon.image(image, 128, 128))
    .build();
    
// enlarge the image so it fits 3 slots
ToastBuilder.builder(ToastFormat.DARK, literal("with image but massive"))
    .withIcon(ToastIcon.image(image, 3, 128, 128))
    .build();
    
// grab a mod's icon from a mod ID
// no image will be shown if mod doesn't have a resolvable icon
ToastBuilder.builder(ToastFormat.DARK, literal("with mod icon"))
    .withIcon(ToastIcon.modIcon("emi"))
    .build();
```

It is also possible to implement the `ToastIcon` interface yourself if you so wish.

## Expiry

By default, toasts expire after a given number of milliseconds (modified by the accessibility multiplier). However, if you want it to disappear based on other criteria you can use `expiresWhenProgressComplete()`. This will cause the given toast to expire when progress is set to 1.

{% hint style="warning" %}
**Make sure you remember to complete the progress bar if this is the case**, either through `CustomToast.setProgress` or `ToastBuilder.progressPuller`. Otherwise, they may never disappear off the user's screen.
{% endhint %}