Developer Docs

Quick reference guides with props tables, usage examples, and best practices for rapid development

Components

Form Components

Display Components

Feedback Components

Layout Components

Navigation Components

Components/Docs/ToggleGroup

ToggleGroup

Quick Examples

A group of toggle buttons where only one can be active at a time. Perfect for view modes, priorities, or mutually exclusive options with 2-5 choices.

Basic Toggle Group

With Icons

Three Options

Custom Styled (Gradient)

Text Alignment

🔧 Props

Prop	Type	Default	Description
options	Array	[]	Array of {value, label, icon?, tooltip?} objects
value	State<string> \| string	undefined	Currently selected value (reactive or static)
onchange	Function	undefined	Callback function (receives value and label)
class	string	""	Container classes (alias for containerClass)
containerClass	string	"inline-flex bg-white rounded-(--vwf-size) vwfsize-md vwfcolor-sky"	Outer container classes (use for vwfsize-, vwfcolor-)
buttonClass	string	""	Classes applied to ALL buttons
activeClass	string	"bg-(--vwf-color) shadow-sm"	Classes for active/selected button
inactiveClass	string	"bg-transparent text-smoke hover:text-tertiary hover:bg-cloud"	Classes for inactive buttons

💻 Basic Usage

Simple View Mode Toggle

Current view: grid

const viewMode = van.state('grid');

ToggleGroup({
  options: [
    { value: 'grid', label: 'Grid' },
    { value: 'list', label: 'List' }
  ],
  value: viewMode
})

With Icons and Labels

const notificationMethod = van.state('email');

ToggleGroup({
  options: [
    { value: 'email', label: 'Email', icon: 'oj-ux-ico-email' },
    { value: 'sms', label: 'SMS', icon: 'oj-ux-ico-cell-phone' },
    { value: 'push', label: 'Push', icon: 'oj-ux-ico-notification' }
  ],
  value: notificationMethod
})

Custom Styled with Gradient

const priority = van.state('medium');

ToggleGroup({
  options: [
    { value: 'low', label: 'Low' },
    { value: 'medium', label: 'Medium' },
    { value: 'high', label: 'High' }
  ],
  value: priority,
  containerClass: 'bg-gradient-to-r from-sky/10 to-earth/10 p-1 rounded-full',
  buttonClass: 'px-6 py-2 rounded-full text-sm',
  activeClass: 'bg-gradient-to-r from-sky to-earth text-white shadow-lg',
  inactiveClass: 'text-midnight hover:bg-white/50'
})

With Custom Change Handler

const theme = van.state('light');

ToggleGroup({
  options: [
    { value: 'light', label: 'Light', icon: 'oj-ux-ico-sun' },
    { value: 'dark', label: 'Dark', icon: 'oj-ux-ico-moon' },
    { value: 'auto', label: 'Auto', icon: 'oj-ux-ico-magic' }
  ],
  value: theme,
  onchange: (value, label) => {
    console.log('Theme changed to:', value, label);
    // Apply theme change logic here
    document.body.classList.toggle('dark', value === 'dark');
  }
})

⚡️ Best Practices

✓ Do This

✓Use for 2-5 mutually exclusive options

- Perfect for view modes, priorities, or settings where only one option can be active.

✓Add icons for visual recognition

- Icons help users quickly identify options, especially when labels are hidden on mobile.

✓Use containerClass for size and color

- Apply vwfsize-* and vwfcolor-* utilities to containerClass for consistent theming.

✓Provide clear, concise labels

- Use short labels (1-2 words) that clearly describe each option.

✓Keep options equal in length

- Similar length labels create better visual balance and alignment.

✗ Avoid This

✗Don't use for more than 5 options

- For 6+ options, use RadioButton or Select component instead.

✗Don't use for actions

- ToggleGroup is for settings/modes. Use Button for actions like "Save" or "Delete".

✗Don't use for multi-select

- ToggleGroup is mutually exclusive (one selection). Use Checkbox for multi-select.

✗Don't use ambiguous labels

- Avoid vague labels like "Option 1". Use descriptive names like "Grid View".

✗Don't mix very different label lengths

- Large length differences create awkward spacing. Keep labels similar in length.

✨ Key Features

⭑CSS Variable Sizing

- Uses --vwf-size for proportional sizing. All buttons scale together based on vwfsize-* utility.

⭑CSS Variable Coloring

- Uses --vwf-color for active button background. Set via vwfcolor-* utilities on containerClass.

⭑Accessible Button Pattern

- Built with semantic buttons and ARIA roles (radio group). Screen readers announce selection correctly.

⭑Automatic State Management

- Automatically updates van.state when options are clicked. No manual state management needed.

⭑Icon Support

- Optional icons using Oracle JET icon font (oj-ux-ico-*). Icons auto-hide on mobile with labels showing.

⭑Responsive Design

- Icons hide on small screens (< md breakpoint) when labels present. Ensures usability on mobile.

⭑Full Tailwind Override

- filterClassName enables complete customization of container, buttons, active/inactive states.

⭑Smooth Transitions

- All state changes animated with CSS transitions for polished user experience.

⭑Custom Styling Classes

- Separate classes for container, all buttons, active buttons, and inactive buttons for complete control.

⭑Tooltip Support

- Optional tooltip property for each option. Fallback to label if not provided.

Common Use Cases

📊 View Modes

Switch between grid, list, or table views in data displays.

ToggleGroup({
  options: [
    { value: 'grid', icon: 'oj-ux-ico-grid-view-large', label: 'Grid' },
    { value: 'list', icon: 'oj-ux-ico-list-rectangles', label: 'List' },
    { value: 'table', icon: 'oj-ux-ico-table', label: 'Table' }
  ],
  value: viewMode
})

📱 Notification Preferences

Choose notification delivery method (email, SMS, push).

ToggleGroup({
  options: [
    { value: 'email', icon: 'oj-ux-ico-email', label: 'Email' },
    { value: 'sms', icon: 'oj-ux-ico-cell-phone', label: 'SMS' },
    { value: 'push', icon: 'oj-ux-ico-notification', label: 'Push' }
  ],
  value: notificationMethod
})

⚖️ Priority Levels

Set priority for tasks, tickets, or messages.

ToggleGroup({
  options: [
    { value: 'low', label: 'Low' },
    { value: 'medium', label: 'Medium' },
    { value: 'high', label: 'High' }
  ],
  value: priority
})

🎨 Theme Selection

Switch between light, dark, or auto theme modes.

ToggleGroup({
  options: [
    { value: 'light', icon: 'oj-ux-ico-sun', label: 'Light' },
    { value: 'dark', icon: 'oj-ux-ico-moon', label: 'Dark' },
    { value: 'auto', icon: 'oj-ux-ico-magic', label: 'Auto' }
  ],
  value: theme
})

✏️ Text Alignment

Control text alignment in editors or formatting tools.

ToggleGroup({
  options: [
    { value: 'left', icon: 'oj-ux-ico-align-left', label: 'Left' },
    { value: 'center', icon: 'oj-ux-ico-align-center', label: 'Center' },
    { value: 'right', icon: 'oj-ux-ico-align-right', label: 'Right' }
  ],
  value: alignment
})

Explore More Components

Browse other component categories