Developer Docs

✨ Quick Examples

Radio buttons allow users to select a single option from a group of choices. Built with CSS variables (--vwf-color, --vwf-size) for consistent sizing and theming, with optional animated ping effect and icon replacement.

const selected = van.state('option1');

RadioButton({
  name: 'demo',
  value: 'option1',
  label: 'Option 1',
  checked: () => selected.val === 'option1',
  onchange: (e) => selected.val = e.target.value
})

🔧 Props

💻 Usage

const selected = van.state('opt2');

RadioButton({
  name: 'basics',
  value: 'opt1',
  label: 'First Option',
  checked: () => selected.val === 'opt1',
  onchange: (e) => selected.val = e.target.value
})

📏 Size Variants

Control size using vwfsize-* utilities on containerClass. Radio button size and spacing scale proportionally with --vwf-size CSS variable.

// Size control via containerClass
RadioButton({
  containerClass: 'vwfsize-lg',  // Large size
  name: 'sizes',
  value: 'lg',
  label: 'Large Radio'
})

🎨 Color Customization

Use vwfcolor-* utilities on containerClass or class prop to set theme colors. The radio button and dot automatically use the --vwf-color variable.

// Custom color via vwfcolor utility
RadioButton({
  containerClass: 'vwfsize-lg',
  class: 'vwfcolor-sunset border-sunset border-2',
  name: 'colors',
  value: 'sunset',
  label: 'Sunset'
})

✨ Animated Ping Effect

Add ping={true} prop to show an animated ring effect when the radio button is selected. Great for drawing attention to important selections.

RadioButton({
  ping: true,  // Animated ping ring
  containerClass: 'vwfsize-lg',
  name: 'priority',
  value: 'high',
  label: 'High Priority'
})

🔗 RadioGroup Helper

Use RadioGroup to manage multiple radio buttons with shared props. Simplifies creating radio button groups with consistent styling.

const selected = van.state('pro');

RadioGroup({
  name: 'plan',
  options: [
    { value: 'basic', text: 'Basic - $9/mo' },
    { value: 'pro', text: 'Pro - $19/mo' },
    { value: 'enterprise', text: 'Enterprise' }
  ],
  value: selected,  // Auto-managed state
  radioProps: {
    containerClass: 'vwfsize-sm xs:vwfsize-md',
    class: 'vwfcolor-sky'
  }
})

🔘 Button-Style Radios

Hide the radio input with class="hidden" and style the label to create button-like selections. Use group-has-[:checked] for checked state styling.

RadioGroup({
  name: 'time',
  options: [
    { value: 'morning', text: '🌅 Morning' },
    { value: 'afternoon', text: '☀️ Afternoon' }
  ],
  value: selectedTime,
  radioProps: {
    // Style the label like a button
    labelClass: 'px-6 py-3 rounded-xl border-2 border-sky ' +
                'group-has-[:checked]:bg-sky group-has-[:checked]:text-white',
    class: 'hidden'  // Hide the radio circle
  }
})

⭐ Custom Icon Replacement

Replace the default dot with a custom icon using the icon prop. The icon appears at the same position with opacity transition.

RadioButton({
  name: 'custom',
  value: 'check',
  label: 'With Check Icon',
  containerClass: 'vwfsize-xl',
  class: 'vwfcolor-success border-success border-2 before:bg-transparent',
  icon: span({ class: 'oj-ux-ico-check text-success text-2xl' })
})

🚫 Disabled State

Disabled radio buttons show reduced opacity and change cursor to not-allowed. Both checked and unchecked states can be disabled.

// Disabled radio button
RadioButton({
  name: 'group',
  value: 'disabled',
  label: 'Disabled Option',
  disabled: true,  // Reduces opacity, disables interaction
  checked: true    // Can be checked and disabled
})

⚡️ Best Practices

✨ Key Features