Developer Docs

✨ Quick Examples

Custom checkbox with SVG checkmark overlay using grid pattern. Supports custom colors, sizes, circular variant, and custom icons.

🔧 Props

💻 Usage

const terms = van.state(false);

Checkbox({
  id: 'basic-terms',
  label: 'I agree to the terms and conditions',
  checked: terms,
  required: true,
  onchange: e => terms.val = e.target.checked
})

const newsletter = van.state(false);

Checkbox(
  {
    id: 'custom-label',
    checked: newsletter,
    onchange: e => newsletter.val = e.target.checked
  },
  'Subscribe to ',
  span({ class: 'font-semibold text-sky' }, 'weekly newsletter'),
  ' for updates'
)

📏 Size Variants

Control checkbox size via containerClass with vwfsize-* utilities.

// Small
Checkbox({ containerClass: 'vwfsize-sm', checked: false }, 'Small')

// Default (no size class needed)
Checkbox({ checked: false }, 'Default size')

// Large
Checkbox({ containerClass: 'vwfsize-lg', checked: false }, 'Large')

// Extra Large
Checkbox({ containerClass: 'vwfsize-xl', checked: false }, 'Extra Large')

🎨 Color Customization

Control colors via containerClass with vwfcolor-* utilities.

Checkbox({ containerClass: 'vwfcolor-success', checked: true }, 'Success')
Checkbox({ containerClass: 'vwfcolor-warning', checked: true }, 'Warning')
Checkbox({ containerClass: 'vwfcolor-error', checked: true }, 'Error')
Checkbox({ containerClass: 'vwfcolor-earth', checked: true }, 'Earth')

⭕ Circular Checkbox

Create circular checkboxes by adding rounded-full to the class prop.

// Simple circular
Checkbox({
  class: 'rounded-full',
  checked: true
}, 'Circular checkbox')

// Large circular with custom label
Checkbox({
  containerClass: 'vwfsize-xl',
  class: 'rounded-full',
  labelClass: 'font-semibold',
  checked: false
}, 'Large circular checkbox')

⭐ Custom Icon Checkbox

Hide the default SVG checkmark and use Oracle JET icons, emoji, or any other svg as checkbox indicators.

// Star icon checkbox
Checkbox({
  class: 'oj-ux-ico-star-s vwfcolor-warning bg-peach border-none text-transparent bg-clip-text',
  svgClass: 'hidden',  // Hide default checkmark
  labelClass: 'text-warning',
  containerClass: 'text-xl leading-none',
  checked: true
}, 'Star checkbox')

// Heart icon checkbox
Checkbox({
  class: 'oj-ux-ico-heart-s text-transparent bg-clip-text',
  svgClass: 'hidden',
  checked: false
}, 'Heart checkbox')

🚫 Disabled State

Checkbox automatically styles disabled state with opacity reduction.

Checkbox({
  label: 'Disabled unchecked',
  checked: false,
  disabled: true
})

Checkbox({
  label: 'Disabled checked',
  checked: true,
  disabled: true
})

🏗️ Grid Overlay Pattern

Checkbox uses a grid layout to overlay the custom SVG checkmark on top of the native input. Both elements occupy the same grid cell.

• Container - flex items-center gap-3
• Wrapper - grid grid-cols-1
• Input - col-start-1 row-start-1
• SVG - col-start-1 row-start-1 pointer-events-none
• No absolute positioning needed - SVG scales automatically
• Checkmark always perfectly centered
• Maintains accessibility - native input receives events

⚡️ Best Practices

• Provide clear, concise labels - use short, descriptive text
• Use required prop for mandatory fields
• Use containerClass for size/color control (vwfsize-*, vwfcolor-*)
• Group related checkboxes with fieldset and legend
• Always provide an onchange handler to update state
• Don't rely only on color for meaning - use labels or icons
• Don't apply vwfsize-* to class prop - use containerClass instead

✨ Key Features

Checkbox component capabilities and design patterns.

• Grid overlay pattern - Custom SVG checkmark without absolute positioning
• CSS variable sizing - Scales proportionally using --vwf-size variable
• Animated checkmark - SVG path with opacity transition
• Circular variant - Add rounded-full to class prop
• Custom icon support - Hide SVG and use Oracle JET icons or emoji
• Disabled state styling - Automatic opacity reduction
• Required indicator - Red asterisk on label when required={true}
• Auto-generated IDs - Ensures proper label-checkbox association
• Full Tailwind override - Complete customization via filterClassName