Toaster-Ui Library Documentation

OpenSource feel free to fork and make a pull request.

Toaster-Ui is a lightweight JavaScript library that allows you to easily display toast messages in your web application. This documentation provides a comprehensive guide on how to install and use Toaster-Ui in your project.

Installation

To use Toaster-Ui, you have two options for installation:

Option 1: Script Tag

Include the following script tag in your HTML file:

<script src="https://unpkg.com/[email protected]/dist/main.js"></script>

or

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/main.js"></script>

Option 2: NPM

Install Toaster-Ui using npm:

npm i toaster-ui

Usage

Once Toaster-Ui is installed in your project, you can start using it by following the instructions below.

If you imported the library using a module bundler like webpack or Rollup:

import ToasterUi from 'toaster-ui';

If you included the library using a script tag, there's no need to import it explicitly.

Create a new instance of ToasterUi:

const toaster = new ToasterUi();

Basic Usage

To display a basic toast message, use the addToast() method:

toaster.addToast("This is a toast");

The addToast() method takes three parameters:

• content (required): The message content of the toast.
• type (optional): The type of the toast. It can be one of the following: default, success, error, warning, info, loading. Default is default.
• options (optional): Additional options to customize the toast. See the Options section for more details.

Options

The addToast() method's third parameter, options, allows you to customize various aspects of the toast. The available options are:

Option	Type	Default	Description
duration	number	3000	The duration in milliseconds that the toast should be displayed before automatically closing.
autoClose	boolean	true	Specifies whether the toast should automatically close after the duration. Set it to false to disable auto-closing.
styles	object	null	An object containing CSS styles to be applied to the toast element.
allowHtml	boolean	false	Specifies whether HTML content should be allowed in the toast message.
onClose	function	()=>{}	A callback function to be executed when the toast is closed.

Updating a Toast

To update a toast message after it has been displayed, you can use the updateToast() method. This method requires the id of the toast that needs to be updated, which is returned when adding a toast.

Here's an example of how to update a toast:

const toastId = toaster.addToast("Initial toast content");

// To update the toast
toaster.updateToast(toastId, "New toast content", "success", { duration: 5000 });

The updateToast() method takes four parameters:

• id (required): The ID of the toast to be updated.
• newContent (optional): The new message content of the toast.
• newType (optional): The new type of the toast.
• newOptions (optional): New options to customize the toast. Only the specified options will be updated, and the rest will remain unchanged.

Manual Update for Loading Toasts

Toasts of type "loading" have their autoClose option set to false by default, requiring manual updates using the updateToast() function. This allows you to control when to close the toast and provide status updates to users. Use the updateToast() function with the toast's ID to modify its content, type, and other options as needed.

When the type of the toast is "loading", the autoClose option is automatically set to false. This means that the toast will not close automatically after a duration. Instead, you'll need to update the toast manually using the updateToast() function to indicate when the loading is complete or any other desired changes.

Here's an example of how to create a loading toast and manually update it:

const toastId = toaster.addToast("Loading in progress", "loading");

// Simulate loading completion after 3 seconds
setTimeout(() => {
  toaster.updateToast(toastId, "Loading complete!", "success", { autoClose: true });
}, 3000);

In this example, we first create a loading toast by setting the type to "loading". Since the autoClose option is set to false, the toast will remain visible until we manually update it. After a simulated loading process of 3 seconds, we use the updateToast() function to change the toast's content, type to "success", and enable autoClose by setting it to true. This causes the toast to automatically close after the specified duration.

Remember, for loading toasts, you need to manually update the toast using updateToast() to reflect changes or indicate completion.

Here's a clarification on how the update process works:

When using the updateToast() function, you can specify new values for the content, type, and options of the toast. If you omit any of these parameters, the corresponding property of the toast will retain its existing value.

For example:

const toastId = toaster.addToast("Initial toast", "default", { duration: 3000 });

// Update the toast without modifying the type or options
toaster.updateToast(toastId, "Updated toast");

// The toast will still have the "default" type and a duration of 3000

In the example above, the updateToast() function is called without providing a new type or options. As a result, the toast will retain its original type ("default") and the duration option of 3000 milliseconds.

However, if you explicitly provide a new type parameter during the update, it will override the existing type:

const toastId = toaster.addToast("Initial toast", "default", { duration: 3000 });

// Update the toast and change its type
toaster.updateToast(toastId, "Updated toast", "success");

// The toast will now have the "success" type and a duration of 3000

In this case, the type parameter is explicitly set to "success" during the update, causing the toast to change its type accordingly.

To update specific options while retaining the rest, you can pass only the updated options as the newOptions parameter:

const toastId = toaster.addToast("Initial toast", "default", { duration: 3000, styles: { color: "blue" } });

// Update the toast and change only the styles
toaster.updateToast(toastId, "Updated toast", null, { styles: { color: "red" } });

// The toast will retain its type, duration, and the updated styles { color: "red" }

In the example above, the styles option is updated while retaining the existing type ("default") and duration (3000 milliseconds).

I apologize for any confusion caused by my previous response. Thank you for bringing it to my attention, and I hope this clarifies the behavior of updating options and types when using the updateToast() function.

That's it! You now have That's it! You now have a basic understanding of how to use Toaster-Ui in your web application. Below, you'll find some additional examples and usage details to further enhance your experience with the library.

Creating Custom Types

To create a custom toast type, you can define your own CSS class and apply it to the toast element. Here's an example:

.toaster-ui-lib-custom {
  background-color: #ff00ff; /* Replace with your desired background color */
  /* Add any other custom styles here */
}

You can apply the custom type to a toast by setting the type parameter to your custom type name:

toaster.addToast("Custom toast message", "custom");

The toast will now have the custom type styling applied to it.

Examples

Example 1: Customizing Toast Styles

You can customize the styles of a toast by providing a styles object in the options parameter. Here's an example:

const options = {
  duration: 2000,
  styles: {
    backgroundColor: '#ff0000',
    color: '#ffffff',
    border: '1px solid #ffffff',
  },
};

toaster.addToast("Customized toast", "success", options);

Example 2: Allowing HTML Content

To display HTML content in a toast message, set the allowHtml option to true. Here's an example:

const options = {
  allowHtml: true,
};

toaster.addToast("<strong>This is a bold toast message</strong>", "info", options);

Example 3: Handling Toast Closure

You can specify a callback function to be executed when a toast is closed by providing the onClose option. Here's an example:

const options = {
  onClose: () => {
    console.log("Toast closed!");
  },
};

toaster.addToast("Toast with closure callback", "default", options);

Example 4: Updating toast

example of fetching data from an application using Toaster-Ui:

const toaster = new ToasterUi();

// Create a function to fetch some data from the application
async function dataFetch() {
  // Add a toast of type loading
  const toastId = toaster.addToast("Loading, please wait", "loading");

  const data = await fetch("https://jsonplaceholder.typicode.com/todos/1");

  const promise = await new Promise((resolve, reject) => {
    setTimeout(() => {
      resolve("Promise resolved.");
    }, 2000);
  });

  if (data.status !== 200) {
    // Update the toast with error message
    toaster.updateToast(toastId, "Error while fetching data", "error");
    return;
  } else {
    // Update the toast with success message
    toaster.updateToast(toastId, "Data fetched successfully", "success");
  }

  setTimeout(() => {
    toaster.updateToast(toastId, "Promise resolved", "success", {
      autoClose: true,
    });
  }, 2000);

  const json = await data.json();
  return json;
}

dataFetch();

In this example, the dataFetch function is created to fetch data from an application. It starts by adding a toast of type "loading" using toaster.addToast and assigns the returned toastId to a variable.

Next, it makes an asynchronous fetch request to retrieve data from the specified URL. It also simulates a promise being resolved after a 2-second delay using setTimeout.

If the data response has a status other than 200, indicating an error, the toast is updated with an error message using toaster.updateToast. Otherwise, if the data is successfully fetched, the toast is updated with a success message.

After 2 seconds, another toast update is triggered to display the message "Promise resolved" with a success type, and the autoClose option set to true to automatically close the toast.

Finally, the fetched data is converted to JSON using data.json() and returned.

When you run the dataFetch function, the toast messages will be displayed in the Toaster-Ui component based on the progress and status of the data fetching process.

Summary

Congratulations! You've successfully learned how to install, import, and use Toaster-Ui in your web application. You're now equipped with the knowledge to display toast messages with custom styles, handle toast closure, and take advantage of advanced features offered by the library. Explore and experiment with the different options and methods to enhance your user interface with informative and visually appealing toast messages. Happy coding!