Accordion

کامپوننت Accordion برای نمایش محتوای جمع‌شونده استفاده می‌شود؛ مثل سوالات متداول (FAQ) یا تنظیمات گروه‌بندی‌شده. کامپوننت compound است و از چهار بخش تشکیل شده که state را از طریق Context به اشتراک می‌گذارند.

Import

import { Accordion } from "fara-ui";

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

Basic Usage

<Accordion.Root>
  <Accordion.Item value="faq-1">
    <Accordion.Trigger value="faq-1">سوال اول</Accordion.Trigger>
    <Accordion.Panel value="faq-1">پاسخ سوال اول</Accordion.Panel>
  </Accordion.Item>
  <Accordion.Item value="faq-2">
    <Accordion.Trigger value="faq-2">سوال دوم</Accordion.Trigger>
    <Accordion.Panel value="faq-2">پاسخ سوال دوم</Accordion.Panel>
  </Accordion.Item>
</Accordion.Root>

Playground

کتابخانه‌ای از کامپوننت‌های React برای رابط‌های کاربری فارسی و RTL.

با دستور npm install fara-ui.

تمام مرورگرهای مدرن.

allowMultiple

<Accordion.Root>
  <Accordion.Item value="faq-1">
    <Accordion.Trigger value="faq-1">سوال اول</Accordion.Trigger>
    <Accordion.Panel value="faq-1">پاسخ سوال اول</Accordion.Panel>
  </Accordion.Item>
</Accordion.Root>

Structure

• Accordion.Root — ظرف اصلی؛ state باز/بسته را نگه می‌دارد
• Accordion.Item — گروه‌بندی یک آیتم (با value یکتا)
• Accordion.Trigger — دکمه‌ی سر آیتم
• Accordion.Panel — محتوای بازشونده

هر سه کامپوننت داخلی باید داخل Root استفاده شوند؛ در غیر این صورت خطای واضحی می‌گیری.

allowMultiple

• پیش‌فرض (false) — در هر لحظه فقط یک آیتم باز است؛ باز کردن آیتم جدید، قبلی را می‌بندد
• true — چند آیتم می‌توانند هم‌زمان باز باشند

Accordion در API فعلی state را داخلی مدیریت می‌کند و prop کنترل‌شده‌ای برای openItems ندارد. اگر می‌خواهی با state بیرونی کار کنی، می‌توانی با تغییر ساختار کامپوننت یا مدیریت رویدادهای سفارشی این رفتار را پیاده‌سازی کنی؛ defaultOpen فقط مقدار اولیه است و بعداً با تغییر prop به‌روزرسانی نمی‌شود.

Default Open Items

با defaultOpen آرایه‌ای از value های آیتم‌هایی که از ابتدا باز باشند:

<Accordion.Root defaultOpen={["faq-1"]}>

Accessibility

• دکمه‌ی Trigger با aria-expanded وضعیت باز/بسته را به screen reader ها اعلام می‌کند.
• آیتم‌ها با تگ <button> واقعی پیاده شده‌اند و با صفحه‌کلید قابل استفاده‌اند.
• برای هر Trigger متن واضح و منحصربه‌فرد بنویس؛ خود کامپوننت از aria-label جداگانه استفاده نمی‌کند.
• اگر محتوای Panel برای یک عنوان خاص است، ساختار عنوان و متن را در children خودت به‌صورت معنایی بنویس.

Data Attributes and Customize CSS

Accordion hookهای پایدار زیر را در DOM قرار می‌دهد:

Attribute	کاربرد
data-fara-accordion	ریشه‌ی Accordion
data-fara-accordion-item	هر آیتم
data-accordion-value	مقدار یکتای هر آیتم
data-fara-accordion-trigger	دکمه‌ی باز و بسته کردن
data-fara-accordion-icon	آیکون فلش داخل Trigger
data-fara-accordion-panel	پنل محتوا
data-fara-accordion-panel-inner	wrapper داخلی پنل
data-fara-accordion-panel-content	محتوای نهایی پنل
data-open	روی Trigger و Panel وقتی آیتم باز است

برای تغییر layout کل Accordion از className روی Accordion.Root استفاده کن:

<Accordion.Root className="faq-accordion" allowMultiple>
  {/* Item, Trigger و Panel */}
</Accordion.Root>

.faq-accordion {
  display: grid;
  gap: 8px;
}

[data-fara-accordion-trigger][data-open] {
  color: #2563eb;
}

[data-fara-accordion-icon] {
  transition: transform 160ms ease;
}

[data-fara-accordion-trigger][data-open] [data-fara-accordion-icon] {
  transform: rotate(180deg);
}

[data-fara-accordion-panel][data-open] {
  background: #f8fafc;
}

[data-fara-accordion-item][data-accordion-value="install"] {
  border-inline-start: 3px solid #2563eb;
}

className فقط روی Accordion.Root پشتیبانی می‌شود؛ Item، Trigger و Panel در API فعلی propهای سفارشی‌سازی جداگانه ندارند. برای state و بخش‌های داخلی از data-* استفاده کن.

Props — Accordion.Root

Prop	Type	Default	Description
children	ReactNode	-	آیتمهای آکاردئون (الزامی)
allowMultiple	boolean	false	اجازه‌ی باز بودن هم‌زمان چند آیتم
defaultOpen	string[]	[]	value های آیتم‌هایی که از ابتدا بازند
className	string	-	کلاس CSS اضافی برای سفارشی‌سازی

Props — Accordion.Item / Trigger / Panel

Prop	Type	Description
value	string	شناسه‌ی یکتای آیتم (الزامی در هر سه)
children	ReactNode	محتوا (الزامی)