# TopClass UI

> React components for Next.js, RTL-first and server-first, built on Tailwind CSS v4 and Base UI.

## Docs

- [Install the package](https://topclassui.com/en/docs/installation): Two steps. Install the package, then add the components you need.
- [Add with the CLI](https://topclassui.com/en/docs/cli): Copy a component into your project and own the file.
- [CSS entry](https://topclassui.com/en/docs/css): Three import lines, in order, and no configuration file. That is the whole Tailwind setup.
- [Provider](https://topclassui.com/en/docs/provider): One provider at the root of your app, with direction and locale as props. It is required, and everything it does is listed on this page.
- [Your first component](https://topclassui.com/en/docs/first-component): A form that renders on the server and posts to a Server Action. No JavaScript for its markup.
- [Colors](https://topclassui.com/en/docs/colors): Color has three layers: a palette you never use directly, semantic tokens you always use, and the utility classes Tailwind generates from those tokens.
- [Icons](https://topclassui.com/en/docs/icons): 84 icons, inlined as SVG. Only the ones you render are loaded.
- [Theming](https://topclassui.com/en/docs/theming): Six knobs change the shape of every component at once. A mode changes the colors. Nothing else is themeable, by design.
- [Right to left](https://topclassui.com/en/docs/rtl): Every component mirrors in Arabic without a code change, because no component is allowed to say left or right.
- [Server first](https://topclassui.com/en/docs/server-first): A component ships JavaScript only when it has to listen for something. Most of them never do.
- [Accessibility](https://topclassui.com/en/docs/accessibility): WCAG 2.2 AA is the target. This page lists what a machine checks, what a person checks, and what is not yet covered.
- [Components](https://topclassui.com/en/docs/components): Every component in one consistent layout: the preview, the code, every state and how to install it.
- [Changelog](https://topclassui.com/en/changelog): Every release of TopClass UI, newest first, with what changed in it and how to move to it.

## Components

- [Accordion](https://topclassui.com/en/docs/components/accordion): Closed panels stay in the HTML, so find-in-page and crawlers reach them.
- [Alert](https://topclassui.com/en/docs/components/alert): Four tones, each with its own icon, so the message reads without relying on colour.
- [Avatar](https://topclassui.com/en/docs/components/avatar): Image, initials or an icon, on the same five sizes as every control so rows line up.
- [Avatar group](https://topclassui.com/en/docs/components/avatar-group): Overlapping avatars with a +N counter; max is clamped to a safe range.
- [Badge](https://topclassui.com/en/docs/components/badge): A status label in three variants across six tones, rendered on the server with no script.
- [Banner](https://topclassui.com/en/docs/components/banner): Full width above the header; it pushes the page down rather than covering anything.
- [Breadcrumb](https://topclassui.com/en/docs/components/breadcrumb): Real links with aria-current on the last crumb, and BreadcrumbList JSON-LD.
- [Button](https://topclassui.com/en/docs/components/button): Five variants across six tones, with no script; render turns it into a real link.
- [Card](https://topclassui.com/en/docs/components/card): A surface with a larger radius than a control, so it never reads as a button.
- [Checkbox](https://topclassui.com/en/docs/components/checkbox): Checked, unchecked or mixed; a hidden input sends the default before hydration.
- [Code block](https://topclassui.com/en/docs/components/code-block): Code in a box of its own, rendered on the server; the copy button is its only script.
- [Combobox](https://topclassui.com/en/docs/components/combobox): A text input that filters a listbox; it calls loadMore() for the next page, caches nothing.
- [Command palette](https://topclassui.com/en/docs/components/command): Searchable action palette that loads on first open, never in the initial bundle.
- [Date picker](https://topclassui.com/en/docs/components/date-picker): A lazy calendar popover that formats dates with the provider's locale and digits.
- [Dialog](https://topclassui.com/en/docs/components/dialog): A modal dialog whose body scrolls between a sticky header and footer, while the page behind it stays still.
- [Drawer](https://topclassui.com/en/docs/components/drawer): Dialog that slides from a logical edge, so it mirrors in RTL without a code change.
- [Dropdown menu](https://topclassui.com/en/docs/components/dropdown): Menu whose links render real anchors, so open-in-new-tab and middle-click work.
- [Empty state](https://topclassui.com/en/docs/components/empty-state): What a collection shows when there is nothing: an icon, a line and an action.
- [Field](https://topclassui.com/en/docs/components/field): The label, the hint and the error around any form control, tied to it by ids in the server HTML before any script runs.
- [File upload](https://topclassui.com/en/docs/components/file-upload): A drop zone that always has a browse button; the file list is a windowed collection.
- [Form](https://topclassui.com/en/docs/components/form): A plain form that posts with no script, and FormAction, whose action answers with errors that land on the matching fields.
- [Input](https://topclassui.com/en/docs/components/input): A native input that ships 0 KB. It will not compile without an id or an aria-label.
- [Kbd](https://topclassui.com/en/docs/components/kbd): A keycap for a key the reader presses, rendered on the server. A combination is sibling keys, with no group part and no plus.
- [Meter](https://topclassui.com/en/docs/components/meter): A reading inside a known range, such as disk space or a score: a neutral track with a bar in the tone, rendered on the server.
- [Navbar](https://topclassui.com/en/docs/components/navbar): A sticky header of server links that publishes its height as --tc-sticky-top.
- [Number field](https://topclassui.com/en/docs/components/number-field): A bounded number, typed or stepped, that a hidden input sends before hydration.
- [OTP field](https://topclassui.com/en/docs/components/otp-field): A one-time code, one character per cell; a paste fills every cell at once.
- [Pagination](https://topclassui.com/en/docs/components/pagination): Page numbers are real links, not click handlers; siblingCount is clamped.
- [Popover](https://topclassui.com/en/docs/components/popover): Anchored panel for links and controls; it flips and shrinks instead of overflowing.
- [Progress](https://topclassui.com/en/docs/components/progress): A neutral track with a bar in the tone, read as a progressbar from 0 to 100.
- [Radio group](https://topclassui.com/en/docs/components/radio-group): One choice out of a few, all shown; one Tab stop, the checked radio before hydration.
- [Rating](https://topclassui.com/en/docs/components/rating): Read-only stars are server HTML and ship no script. Only an editable rating hydrates, as a group of native radios.
- [Segmented control](https://topclassui.com/en/docs/components/segmented-control): A radio group drawn as one track; arrows select as they move, and reverse in RTL.
- [Select](https://topclassui.com/en/docs/components/select): One choice from a list of plain data. The popup stays inside the viewport and scrolls itself, seven rows tall by default.
- [Separator](https://topclassui.com/en/docs/components/separator): A hairline divider. It is decorative, so it is exempt from the 3:1 contrast rule.
- [Sidebar](https://topclassui.com/en/docs/components/sidebar): A rail of server-rendered links that collapses to a column of icons. Only the rail and its toggle run in the browser.
- [Skeleton](https://topclassui.com/en/docs/components/skeleton): The placeholder every component ships with, so a page keeps its shape.
- [Slider](https://topclassui.com/en/docs/components/slider): A value or a range; arrow keys and a press on the track reach every drag's result.
- [Spinner](https://topclassui.com/en/docs/components/spinner): A spinner is an icon: it takes the icon sizes and follows the text it sits in.
- [Stepper](https://topclassui.com/en/docs/components/stepper): A done step carries a tick, not just a colour, so it survives a greyscale screenshot.
- [Switch](https://topclassui.com/en/docs/components/switch): An on and off switch for a setting that takes effect at once. Its thumb travels the right way in right-to-left layouts.
- [Table](https://topclassui.com/en/docs/components/table): A real HTML table rendered on the server: sorting is a link per header, the first column can stick, and it ships no JavaScript.
- [Tabs](https://topclassui.com/en/docs/components/tabs): Panels render on the server and stay in the HTML, so inactive text is still indexed.
- [Tag](https://topclassui.com/en/docs/components/tag): A label chip for a topic, rendered on the server. Passing onRemove adds an x button, the only part that runs in the browser.
- [Textarea](https://topclassui.com/en/docs/components/textarea): Native textarea on the server; autosize and the live counter are the only client parts.
- [Timeline](https://topclassui.com/en/docs/components/timeline): A rail of dated events, each with a marker in its tone. It renders on the server and mirrors by itself in right-to-left layouts.
- [Toast](https://topclassui.com/en/docs/components/toast): A close button is always rendered, because swiping one away is a drag (WCAG 2.5.7).
- [Tooltip](https://topclassui.com/en/docs/components/tooltip): One or two lines of text on hover; a shared delay opens the next tooltip instantly.
- [Tree view](https://topclassui.com/en/docs/components/tree-view): Nodes that open and close, flattened into one windowed list: 10,000 stay fast.

## التوثيق بالعربية

- [تثبيت الحزمة](https://topclassui.com/ar/docs/installation): خطوتان فقط. ثبّت الحزمة، ثم أضف المكوّنات التي تحتاج إليها.
- [الإضافة عبر الطرفية](https://topclassui.com/ar/docs/cli): انسخ مكوّنًا إلى مشروعك وامتلك ملفه، فهو ملفك تعدّله كما تشاء.
- [مدخل CSS](https://topclassui.com/ar/docs/css): ثلاثة أسطر استيراد بترتيب ثابت، ولا ملف إعدادات. هذا كل ما يحتاجه إعداد Tailwind.
- [المزوّد](https://topclassui.com/ar/docs/provider): مزوّد واحد في جذر تطبيقك، مع الاتجاه والإعداد المحلي كخصائص. وجوده إلزامي، وكل ما يفعله مذكور في هذه الصفحة.
- [مكوّنك الأول](https://topclassui.com/ar/docs/first-component): نموذج يُعرض على الخادم ويُرسل إلى إجراء خادم. لا JavaScript لبنيته.
- [الألوان](https://topclassui.com/ar/docs/colors): للألوان ثلاث طبقات: لوحة ألوان لا تستخدمها مباشرة أبدًا، ورموز دلالية تستخدمها دائمًا، والأصناف المساعدة التي يولّدها Tailwind من تلك الرموز.
- [الأيقونات](https://topclassui.com/ar/docs/icons): 84 أيقونة مضمّنة في الصفحة بصيغة SVG. لا يُحمَّل منها إلا ما تعرضه فعلًا.
- [السمات](https://topclassui.com/ar/docs/theming): ستة مفاتيح ضبط تغيّر شكل كل المكوّنات دفعة واحدة، والوضع يغيّر الألوان. ولا شيء غير ذلك قابل للتخصيص، عن قصد.
- [من اليمين إلى اليسار](https://topclassui.com/ar/docs/rtl): كل مكوّن ينعكس في العربية دون أي تغيير في الشيفرة، لأنه لا يُسمح لأي مكوّن بأن يقول يسار أو يمين.
- [الخادم أولًا](https://topclassui.com/ar/docs/server-first): لا يشحن المكوّن شيفرة JavaScript إلا حين يحتاج إلى الاستماع إلى حدث ما. أما البقية فلا تضيف شيئًا.
- [إمكانية الوصول](https://topclassui.com/ar/docs/accessibility): الهدف هو WCAG 2.2 AA. تعرض هذه الصفحة ما تفحصه الآلة، وما يفحصه الإنسان، وما لم يُغطَّ بعد.
- [المكوّنات](https://topclassui.com/ar/docs/components): كل المكوّنات بتخطيط واحد: المعاينة والشيفرة وكل الحالات وطريقة التثبيت.
- [سجل التغييرات](https://topclassui.com/ar/changelog): كل إصدار من TopClass UI، الأحدث أولًا، مع ما تغيّر فيه وكيفية الانتقال إليه.

## المكوّنات بالعربية

- [الأكورديون](https://topclassui.com/ar/docs/components/accordion): أقسام يفتحها القارئ واحدًا تلو الآخر. اللوحات المغلقة تبقى في HTML، فيقرؤها الزاحف ويفتحها البحث في الصفحة.
- [تنبيه](https://topclassui.com/ar/docs/components/alert): أربع نبرات، لكلٍّ منها أيقونتها، فتُقرأ الرسالة دون الاعتماد على اللون.
- [صورة رمزية](https://topclassui.com/ar/docs/components/avatar): صورة أو أحرف أولى أو أيقونة، بالأحجام الخمسة نفسها لكل عنصر تحكم فتصطف الصفوف.
- [مجموعة صور رمزية](https://topclassui.com/ar/docs/components/avatar-group): صور رمزية متداخلة مع عدّاد +N؛ وتُحصر max في نطاق آمن.
- [شارة](https://topclassui.com/ar/docs/components/badge): تسمية حالة قصيرة بثلاثة أنماط عبر ست نبرات. تُعرض على الخادم ولا تُرسل أي JavaScript إلى المتصفح.
- [شريط إعلان](https://topclassui.com/ar/docs/components/banner): بعرض كامل فوق الترويسة؛ يدفع الصفحة إلى الأسفل بدل أن يغطي شيئًا.
- [مسار التنقل](https://topclassui.com/ar/docs/components/breadcrumb): موقع الصفحة في الموقع، بروابط حقيقية ودون JavaScript. والمسار نفسه يُكتب BreadcrumbList بصيغة JSON-LD.
- [زر](https://topclassui.com/ar/docs/components/button): خمسة أنماط عبر ست نبرات، يُعرض على الخادم بلا JavaScript. ومن خلال render يصبح رابطًا حقيقيًا بالشكل نفسه.
- [بطاقة](https://topclassui.com/ar/docs/components/card): سطح باستدارة أكبر من عنصر التحكم، فلا يبدو زرًا أبدًا.
- [مربع اختيار](https://topclassui.com/ar/docs/components/checkbox): محدد أو غير محدد أو مختلط؛ حقل مخفي يرسل القيمة الافتراضية قبل الترطيب.
- [كتلة شيفرة](https://topclassui.com/ar/docs/components/code-block): شيفرة في صندوق خاص بها، تُقرأ من اليسار إلى اليمين في أي صفحة. تُعرض على الخادم، وزر النسخ هو الشيفرة الوحيدة في المتصفح.
- [قائمة اختيار مع بحث](https://topclassui.com/ar/docs/components/combobox): حقل نص يصفّي قائمة؛ يستدعي loadMore() للصفحة التالية ولا يخزّن شيئًا.
- [لوحة الأوامر](https://topclassui.com/ar/docs/components/command): لوحة أوامر قابلة للبحث تُحمَّل عند أول فتح، ولا تدخل أبدًا في الحزمة الأولى.
- [منتقي التاريخ](https://topclassui.com/ar/docs/components/date-picker): تقويم منبثق يُحمَّل عند الحاجة، ويكتب التواريخ بلغة المزوّد وأرقامه.
- [مربع حوار](https://topclassui.com/ar/docs/components/dialog): مربع حوار يحجب الصفحة، يتمرّر متنه بين رأس وتذييل ثابتين، بينما تبقى الصفحة خلفه ساكنة.
- [درج](https://topclassui.com/ar/docs/components/drawer): مربع حوار ينزلق من حافة منطقية، فينعكس في الاتجاه من اليمين إلى اليسار دون تعديل في الشيفرة.
- [قائمة منسدلة](https://topclassui.com/ar/docs/components/dropdown): قائمة تُعرض عناصر روابطها روابطَ حقيقية، فيعمل الفتح في علامة تبويب جديدة والنقر بالزر الأوسط.
- [الحالة الفارغة](https://topclassui.com/ar/docs/components/empty-state): ما تعرضه القائمة أو الجدول أو البحث حين لا يوجد ما يُعرض: أيقونة وسطر وجملة وإجراء من عندك.
- [الحقل](https://topclassui.com/ar/docs/components/field): التسمية والتلميح والخطأ حول أي عنصر تحكم في النموذج، مربوطة به بالمعرّفات في HTML الخادم قبل تشغيل أي سكربت.
- [رفع الملفات](https://topclassui.com/ar/docs/components/file-upload): منطقة إفلات فيها زر تصفّح دائمًا، وقائمة الملفات فيها مجموعة معروضة على دفعات.
- [النموذج](https://topclassui.com/ar/docs/components/form): نموذج عادي يُرسَل بلا سكربت، وFormAction الذي يجيب إجراؤه بأخطاء تصل إلى الحقول المطابقة لها.
- [حقل نص](https://topclassui.com/ar/docs/components/input): حقل إدخال أصلي يشحن 0 KB، ولا يُبنى دون id أو aria-label.
- [مفتاح](https://topclassui.com/ar/docs/components/kbd): غطاء مفتاح لمفتاح يضغطه القارئ، يُعرض على الخادم. والتركيبة مفاتيح متجاورة، بلا جزء تجميع وبلا علامة زائد.
- [المقياس](https://topclassui.com/ar/docs/components/meter): قراءة داخل نطاق معروف، مثل مساحة القرص أو النتيجة: مسار محايد عليه شريط بلون النبرة، يُعرض على الخادم.
- [شريط التنقّل](https://topclassui.com/ar/docs/components/navbar): ترويسة مثبّتة روابطها HTML من الخادم، ويكتب جزء صغير واحد في المتصفح ارتفاعها في --tc-sticky-top.
- [حقل رقمي](https://topclassui.com/ar/docs/components/number-field): رقم ضمن حدود، يُكتب أو يُزاد خطوة خطوة، يرسله حقل مخفي قبل الترطيب.
- [حقل رمز التحقق](https://topclassui.com/ar/docs/components/otp-field): رمز لمرة واحدة، حرف في كل خانة؛ واللصق يملأ كل الخانات دفعة واحدة.
- [ترقيم الصفحات](https://topclassui.com/ar/docs/components/pagination): أرقام صفحات هي روابط حقيقية لا معالجات نقر، فتعمل دون JavaScript ويتبع الزاحف كل صفحة منها.
- [نافذة منبثقة](https://topclassui.com/ar/docs/components/popover): لوحة مثبّتة للروابط وعناصر التحكم؛ تنقلب وتتقلّص بدلًا من أن تفيض.
- [شريط التقدم](https://topclassui.com/ar/docs/components/progress): إلى أين وصلت المهمة: مسار محايد عليه شريط بلون النبرة، يقرؤه قارئ الشاشة شريطَ تقدم من 0 إلى 100.
- [مجموعة اختيار فردي](https://topclassui.com/ar/docs/components/radio-group): اختيار واحد من خيارات قليلة معروضة كلها؛ محطة Tab واحدة هي الزر المحدد قبل الترطيب.
- [التقييم](https://topclassui.com/ar/docs/components/rating): نجوم القراءة فقط هي HTML من الخادم ولا تشحن أي سكربت. وحده التقييم القابل للتعديل يترطّب، كمجموعة أزرار راديو أصلية.
- [تحكم مقسّم](https://topclassui.com/ar/docs/components/segmented-control): مجموعة أزرار راديو مرسومة كمسار واحد؛ الأسهم تختار أثناء التنقل، وتنعكس من اليمين إلى اليسار.
- [قائمة اختيار](https://topclassui.com/ar/docs/components/select): اختيار واحد من قائمة بيانات بسيطة. تبقى القائمة المنبثقة داخل الشاشة وتمرّر نفسها، بارتفاع سبعة صفوف افتراضيًا.
- [فاصل](https://topclassui.com/ar/docs/components/separator): خط فاصل رفيع. زخرفي، فهو مستثنى من قاعدة تباين 3:1.
- [الشريط الجانبي](https://topclassui.com/ar/docs/components/sidebar): شريط جانبي روابطه تُعرض على الخادم، وينطوي إلى عمود من الأيقونات. الشريط وزرّه وحدهما يعملان في المتصفح.
- [هيكل التحميل](https://topclassui.com/ar/docs/components/skeleton): العنصر النائب الذي يأتي مع كل مكوّن، فتحتفظ الصفحة بشكلها.
- [شريط تمرير](https://topclassui.com/ar/docs/components/slider): قيمة أو نطاق؛ مفاتيح الأسهم والضغط على المسار تصل إلى ما يصل إليه كل سحب.
- [مؤشر التحميل](https://topclassui.com/ar/docs/components/spinner): للانتظار مجهول المدة. مؤشر التحميل أيقونة، فيأخذ أحجام الأيقونات من 16 إلى 40 بكسل، ويمكنه أن يتبع النص الذي يجلس فيه.
- [مؤشر الخطوات](https://topclassui.com/ar/docs/components/stepper): أين يقف القارئ في مهمة من بضع خطوات. الخطوة المكتملة تحمل علامة صح لا لونًا فقط، فتبقى واضحة في لقطة شاشة رمادية.
- [مفتاح تبديل](https://topclassui.com/ar/docs/components/switch): مفتاح تشغيل وإطفاء لإعداد يسري فورًا. يتحرك مقبضه في الاتجاه الصحيح في التخطيطات من اليمين إلى اليسار.
- [جدول](https://topclassui.com/ar/docs/components/table): جدول HTML حقيقي يُعرض على الخادم: الترتيب رابط في كل عنوان عمود، والعمود الأول يمكن تثبيته، ولا يشحن أي JavaScript.
- [علامات التبويب](https://topclassui.com/ar/docs/components/tabs): عروض متعددة لشيء واحد، يظهر منها واحد في كل مرة. كل لوحة تُعرض على الخادم وتبقى في HTML، فيُفهرَس النص المخفي أيضًا.
- [وسم](https://topclassui.com/ar/docs/components/tag): شريحة تسمية لموضوع، تُعرض على الخادم. تمرير onRemove يضيف زر إزالة، وهو الجزء الوحيد الذي يعمل في المتصفح.
- [مربع نص متعدد الأسطر](https://topclassui.com/ar/docs/components/textarea): مربع نص أصلي على الخادم؛ التمدد التلقائي والعدّاد الحي هما الجزآن الوحيدان في المتصفح.
- [خط زمني](https://topclassui.com/ar/docs/components/timeline): مسار من الأحداث المؤرّخة، لكل حدث علامة بنبرته. يُعرض على الخادم وينعكس وحده في التخطيطات من اليمين إلى اليسار.
- [إشعار](https://topclassui.com/ar/docs/components/toast): زر الإغلاق حاضر دائمًا، لأن إبعاده بالسحب حركة جرّ (WCAG 2.5.7).
- [تلميح](https://topclassui.com/ar/docs/components/tooltip): سطر أو سطران من النص عند التمرير؛ ومهلة مشتركة تجعل التلميح التالي يفتح فورًا.
- [عرض شجري](https://topclassui.com/ar/docs/components/tree-view): عقد في مستويات تُفتح وتُغلق. الفروع المفتوحة تُسطَّح في قائمة واحدة تعرض ما يظهر فقط، فتبقى 10,000 عقدة سريعة.