Toast

کامپوننت Toast برای نمایش پیام‌های موقت استفاده می‌شود؛ مثل تأیید ذخیره‌سازی یا گزارش خطا. برخلاف Alert که بخشی از صفحه است، Toast به‌صورت imperative (بدون state) از هر جای برنامه نمایش داده می‌شود و بعد از چند ثانیه خودش محو می‌شود.

Import

import { showToast, Toaster } from "fara-ui";

اگر هنوز FaraUI را نصب و راه‌اندازی نکرده‌ای، ابتدا صفحه‌ی شروع به کار را ببین.

Setup

یک بار <Toaster /> را در ریشه‌ی برنامه‌ات رندر کن (مثلاً کنار <App />):

// main.tsx
import { Toaster } from "fara-ui";

root.render(
  <>
    <App />
    <Toaster />
  </>,
);

Showing a Toast

بعد از آن، از هر جای برنامه — حتی خارج از کامپوننت‌ها مثل توابع API — کافیست showToast را صدا بزنی:

import { showToast } from "fara-ui";

function saveProfile(data) {
  await api.save(data);
  showToast("پروفایل ذخیره شد.", "success");
}

Live Demo

روی دکمه‌ها کلیک کن:

Variant

• info (پیش‌فرض) — پیام اطلاع‌رسانی
• success — عملیات موفق
• danger — خطا

Display Duration

پارامتر سوم showToast مدت نمایش به میلی‌ثانیه است (پیش‌فرض ۳۰۰۰). یک نوار پیشرفت در پایین هر Toast مدت باقی‌مانده را نشان می‌دهد و کاربر می‌تواند با دکمه‌ی ✕ آن را زودتر ببندد.

showToast("در حال پردازش...", "info", 5000);

با قرار گرفتن ماوس روی Toast، تایمر موقتاً متوقف می‌شود و بعد از خارج شدن دوباره ادامه پیدا می‌کند. کلیک روی دکمه‌ی بستن، آن را بدون انتظار برای پایان duration حذف می‌کند.

Position

با prop position محل container را مشخص کن:

<Toaster position="top-right" />

مقادیر مجاز عبارت‌اند از top-left، top-center، top-right، bottom-left، bottom-center و bottom-right؛ مقدار پیش‌فرض bottom-center است.

Accessibility and SSR

• دکمه‌ی بستن هر Toast aria-label="بستن" دارد.
• خود Toast در API فعلی role="status"، role="alert" یا aria-live ندارد. اگر پیام باید به‌صورت خودکار برای screen reader اعلام شود، یک live region در wrapper برنامه ایجاد کن یا کامپوننت را با semantics مناسب توسعه بده.
• Toaster با SSR و Next.js سازگار است؛ در رندر سرور خروجی تولید نمی‌کند و پس از hydration در مرورگر mount می‌شود. showToast را بعد از mount یا داخل event handler فراخوانی کن.

Data Attributes and Customize CSS

Toaster و Toastها hookهای زیر را تولید می‌کنند:

Attribute	کاربرد
data-fara-toaster	container پورتال
data-position	محل container
data-fara-toast	هر پیام
data-variant	نوع پیام: info، success یا danger
data-fara-toast-message	متن پیام
data-fara-toast-close	دکمه‌ی بستن
data-fara-toast-progress	نوار زمان باقی‌مانده

[data-fara-toaster][data-position="top-right"] {
  inset-block-start: 20px;
  inset-inline-end: 20px;
}

[data-fara-toast][data-variant="danger"] {
  border-inline-start: 4px solid #dc2626;
}

[data-fara-toast-progress] {
  height: 3px;
}

Toaster فقط position دارد و Toastهای داخلی className عمومی دریافت نمی‌کنند؛ برای سفارشی‌سازی از data attributes استفاده کن.

API

تابع / کامپوننت	امضا	Description
showToast	(message, variant?, duration?) => void	نمایش یک پیام جدید
Toaster	position?: ToastPosition	ظرف نمایش Toast ها — یک بار در ریشه رندر کن

interface ToastItem {
  id: string;
  message: string;
  variant: "info" | "success" | "danger";
  duration: number;
}

type ToastPosition =
  | "top-left"
  | "top-center"
  | "top-right"
  | "bottom-left"
  | "bottom-center"
  | "bottom-right";