زر الاختيار (Radio)

يتيح لك زر الاختيار (Radio) تحديد خيار واحد فقط من مجموعة خيارات.

التثبيت

bash

npx @smicolon/cli add radio

قبل إضافة أي مكوّن، شغّل الأمر init مرة واحدة في مشروعك. التفاصيل في صفحة التثبيت.

معاينة

شحن عاديشحن سريعتوصيل في اليوم نفسهتوصيل بالبريد السريع في اليوم نفسه إلى عنوان سكني

الأنماط (variant)

يضع النمط (variant) layout زر الاختيار ونصّه داخل بطاقة بإطار، فتصبح البطاقة كلها قابلة للنقر. استخدمه عندما تحمل الخيارات وصفًا، واستخدم default للخيارات القصيرة في قائمة متقاربة.

شحن عاديشحن سريع

شحن عاديمن ثلاثة إلى خمسة أيام عملشحن سريعيصل غدًا قبل السادسة مساءً

الأحجام

شحن عاديشحن عاديشحن عادي

الحالات

تأتي حالتا التمرير (hover) والتركيز (focus) من CSS مباشرة. مرّر المؤشر فوق خيار، أو انتقل إليه بمفتاح Tab، لتراهما. تظهر حالة الاختيار في النقطة وحدها، ويبقى شكل البطاقة ثابتًا.

شحن عاديشحن سريعتوصيل في اليوم نفسهاستلام من المتجر

إتاحة الوصول (accessibility)

يعمل زر الاختيار مع لوحة المفاتيح تلقائيًا: تنتقل بين الخيارات بمفاتيح الأسهم، ويُرسَل الخيار المحدد مع النموذج دون شيفرة إضافية، لأنه مبني على عنصر <input type="radio"> الأصلي.
لتجميع عدة أزرار اختيار في مجموعة واحدة، أعطها قيمة name نفسها. عندها يمكنك تحديد خيار واحد فقط منها في كل مرة.
يقرأ قارئ الشاشة نص description بعد التسمية مباشرة، لأنه مرتبط بزر الاختيار عبر aria-describedby. أما الدائرة المرسومة فمخفية عن قارئ الشاشة، فيُعلن الخيار مرة واحدة فقط.
أضف aria-label لزر الاختيار الذي يظهر بلا label أو description، ليعرف قارئ الشاشة ما يمثله الخيار.
يتبع زر الاختيار اتجاه الصفحة المحدد في السمة (attribute) dir، فتظهر الدائرة دائمًا في بداية السطر.

الخصائص (props)

الخاصية	النوع	الافتراضي	الوصف
`variant`	`"default" \| "layout"`	`"default"`	عنصر بسيط أو بطاقة بإطار.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	حجم زر الاختيار.
`checked`	`boolean`	لا يوجد	يحدد الخيار، ويُستخدم مع `onChange`.
`disabled`	`boolean`	`false`	يعطّل الخيار ويُظهره باهتًا.
`label`	`string`	لا يوجد	نص التسمية.
`description`	`string`	لا يوجد	سطر ثانوي تحت التسمية.
`name`	`string`	لا يوجد	يجمع أزرار الاختيار في مجموعة واحدة.
`value`	`string`	لا يوجد	القيمة التي تُرسَل مع النموذج.
`onChange`	`(event) => void`	لا يوجد	تُستدعى عند تحديد الخيار.
`className`	`string`	لا يوجد	أصناف (class) إضافية للمكوّن.

الاستخدام

tsx

import { Radio } from "@/components/ui/radio"

// مجموعة خيارات تشترك في قيمة name
<Radio name="plan" value="standard" label="شحن عادي" />
<Radio name="plan" value="express" label="شحن سريع" />

// مع وصف
<Radio
  name="plan"
  value="courier"
  label="توصيل في اليوم نفسه"
  description="يصل قبل السادسة مساءً"
/>

// بطاقة بإطار
<Radio variant="layout" name="plan" value="express" label="شحن سريع" />

// التحكّم بالقيمة
<Radio
  name="plan"
  value="express"
  label="شحن سريع"
  checked={plan === "express"}
  onChange={(e) => setPlan(e.target.value)}
/>

شحن عاديمن ثلاثة إلى خمسة أيام عملشحن سريعيصل غدًا

الخيار المحدد: standard