Progress Toast

Toast variant with embedded progress bar for long-running operations. Same positioning and animation as toast but persists until complete.

Components

Progress Toast

feedback

interactive

<arc-progress-toast>

Overview

ProgressToast extends the toast pattern with an embedded progress bar for long-running operations like file uploads, data exports, and batch processing. Unlike standard toast (which auto-dismisses after a timeout), progress toast persists until the operation completes or is canceled, giving users continuous visual feedback on the operation's progress. A single `<arc-progress-toast>` element acts as the host — place it once in your layout and call its `show()` method with a message, initial progress, and optional cancel callback. The method returns an ID that you use to update progress via `updateToast(id, { progress })` (optionally including a new `message`) and to signal completion via `complete(id)`. Multiple progress toasts can stack vertically, each tracking an independent operation. The component shares the same positioning options and enter/exit animations as toast, so it integrates visually with any existing toast notifications. Each progress toast includes a cancel button that fires an `arc-cancel` event with the operation ID, and the `arc-complete` event fires when an operation reaches 100%.

Guidelines

When to use

Use progress-toast for operations that take more than 2-3 seconds
Update progress frequently enough that the bar moves visibly (every 5-10%)
Provide a cancel button for operations that can be aborted
Call complete() to trigger the success state and auto-dismiss animation
Place a single <arc-progress-toast> at the root of your layout for all pages

When not to use

Do not use progress-toast for operations that complete instantly — use regular toast instead
Do not fire more than 3-4 concurrent progress toasts — it overwhelms the UI
Do not update progress on every byte — batch updates to avoid performance issues
Do not forget to handle errors — call complete() or remove the toast on failure
Do not use progress-toast for indeterminate loading — use loading-overlay or spinner instead

Features

Imperative show() API — returns an ID for tracking each operation
Embedded progress bar with smooth fill animation
updateToast(id, { progress, message? }) method for incremental progress updates
complete(id) method to signal completion and trigger auto-dismiss
Cancel button on each toast fires `arc-cancel` with operation ID
Persists until complete — no auto-dismiss timeout
Vertical stacking for multiple concurrent operations
Same positioning options as toast: top-right, bottom-right
Smooth enter/exit animations matching toast
`arc-complete` and `arc-cancel` events with operation ID in detail

Preview

Simulate Upload

Usage

This component requires JavaScript. No pure HTML/CSS version is available — use the Web Component directly or a framework wrapper.

<script type="module" src="@arclux/arc-ui"></script>

<arc-progress-toast id="progress" position="bottom-right"></arc-progress-toast>

<arc-button variant="primary" onclick="startUpload()">Upload File</arc-button>

<script>
  function startUpload() {
    const pt = document.getElementById('progress');
    const id = pt.show({ message: 'Uploading report.pdf...' });

    let progress = 0;
    const interval = setInterval(() => {
      progress += 10;
      if (progress >= 100) {
        clearInterval(interval);
        pt.complete(id);
      } else {
        pt.updateToast(id, { progress });
      }
    }, 500);
  }
</script>

import { ProgressToast, Button } from '@arclux/arc-ui-react';
import { useRef } from 'react';

export function UploadDemo() {
  const ptRef = useRef<HTMLElement>(null);

  const startUpload = () => {
    const pt = ptRef.current as any;
    if (!pt) return;
    const id = pt.show({ message: 'Uploading report.pdf...' });

    let progress = 0;
    const interval = setInterval(() => {
      progress += 10;
      if (progress >= 100) {
        clearInterval(interval);
        pt.complete(id);
      } else {
        pt.updateToast(id, { progress });
      }
    }, 500);
  };

  return (
    <>
      <ProgressToast ref={ptRef} position="bottom-right" />
      <Button variant="primary" onClick={startUpload}>Upload File</Button>
    </>
  );
}

<script setup>
import { ref } from 'vue';
import { Button, ProgressToast } from '@arclux/arc-ui-vue';

const pt = ref(null);
const startUpload = () => {
  const el = pt.value;
  if (!el) return;
  const id = el.show({ message: 'Uploading report.pdf...' });

  let progress = 0;
  const interval = setInterval(() => {
    progress += 10;
    if (progress >= 100) {
      clearInterval(interval);
      el.complete(id);
    } else {
      el.updateToast(id, { progress });
    }
  }, 500);
};
</script>

<template>
  <ProgressToast ref="pt" position="bottom-right" />
  <Button variant="primary" @click="startUpload">Upload File</Button>
</template>

<script>
  import { Button, ProgressToast } from '@arclux/arc-ui-svelte';

  let pt;
  const startUpload = () => {
    if (!pt) return;
    const id = pt.show({ message: 'Uploading report.pdf...' });

    let progress = 0;
    const interval = setInterval(() => {
      progress += 10;
      if (progress >= 100) {
        clearInterval(interval);
        pt.complete(id);
      } else {
        pt.updateToast(id, { progress });
      }
    }, 500);
  };
</script>

<ProgressToast bind:this={pt} position="bottom-right" />
<Button variant="primary" on:click={startUpload}>Upload File</Button>

import { Component, ViewChild, ElementRef } from '@angular/core';
import { Button, ProgressToast } from '@arclux/arc-ui-angular';

@Component({
  imports: [Button, ProgressToast],
  template: `
    <arc-progress-toast #pt position="bottom-right"></arc-progress-toast>
    <arc-button variant="primary" (click)="startUpload()">Upload File</arc-button>
  `,
})
export class UploadDemoComponent {
  @ViewChild('pt') pt!: ElementRef;

  startUpload() {
    const el = this.pt.nativeElement;
    const id = el.show({ message: 'Uploading report.pdf...' });

    let progress = 0;
    const interval = setInterval(() => {
      progress += 10;
      if (progress >= 100) {
        clearInterval(interval);
        el.complete(id);
      } else {
        el.updateToast(id, { progress });
      }
    }, 500);
  }
}

import { Button, ProgressToast } from '@arclux/arc-ui-solid';

export function UploadDemo() {
  let pt: HTMLElement | undefined;

  const startUpload = () => {
    const el = pt as any;
    if (!el) return;
    const id = el.show({ message: 'Uploading report.pdf...' });

    let progress = 0;
    const interval = setInterval(() => {
      progress += 10;
      if (progress >= 100) {
        clearInterval(interval);
        el.complete(id);
      } else {
        el.updateToast(id, { progress });
      }
    }, 500);
  };

  return (
    <>
      <ProgressToast ref={pt} position="bottom-right" />
      <Button variant="primary" onClick={startUpload}>Upload File</Button>
    </>
  );
}

import { Button, ProgressToast } from '@arclux/arc-ui-preact';
import { useRef } from 'preact/hooks';

export function UploadDemo() {
  const ptRef = useRef<HTMLElement>(null);

  const startUpload = () => {
    const pt = ptRef.current as any;
    if (!pt) return;
    const id = pt.show({ message: 'Uploading report.pdf...' });

    let progress = 0;
    const interval = setInterval(() => {
      progress += 10;
      if (progress >= 100) {
        clearInterval(interval);
        pt.complete(id);
      } else {
        pt.updateToast(id, { progress });
      }
    }, 500);
  };

  return (
    <>
      <ProgressToast ref={ptRef} position="bottom-right" />
      <Button variant="primary" onClick={startUpload}>Upload File</Button>
    </>
  );
}

API

position 'top-right' | 'bottom-right' ='bottom-right': Anchors the progress toast stack to a fixed corner of the viewport.

Events

arc-complete: Fired when a progress toast operation reaches 100%. Detail contains { id } with the operation identifier.
arc-cancel: Fired when the user clicks the cancel button on a progress toast. Detail contains { id } with the operation identifier.

Progress Toast

Overview

Guidelines

When to use

When not to use

Features

Preview

Usage

API

Events

See Also

Docs

Project

Arclight