# Overview
The Toasts module is a simple way of showing [Toasts](https://en.wikipedia.org/wiki/Pop-up_notification) to the player.
Example toast being created, with automatically gathered information
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.
{% 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 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 %}
Toast cycling through a list of items
## 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.
An example of all the shipped toast formats, and their vanilla uses.
{% 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 %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.jackf.red/jackfredlib/jackfredlib-toasts/overview.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.