# Toggle

Toggle component allows users to switch between two states typically representing on/off, enabled/disabled, or active/inactive settings. Toggles provide a quick and intuitive way to modify system or feature preferences with a single action.

## Component summary

- Category: Components
- Version: 3.0.18
- Behavior type: UX4G runtime-enhanced standard DOM
- Implementation model: standard HTML elements with UX4G classes
- Named React, Angular, or Vue component export: **No**
- Human visual preview: https://doc.ux4g.gov.in/web/?path=/story/ux4g-components-toggle--introduction

## Installation contract

- Consumer stylesheet: https://cdn.ux4g.gov.in/UX4G@3.0.18/index.css
- CDN runtime, in order: https://cdn.ux4g.gov.in/UX4G@3.0.18/ux4g.js, then https://cdn.ux4g.gov.in/UX4G@3.0.18/ux4g-custom.js
- npm: import `ux4g-web-components/styles.css` and `ux4g-web-components/design-system` once in the application entry file.
- Never use a named UI-component import such as `import { Button } from "ux4g-web-components"`. UX4G is class-based.
- Framework syntax rules: https://doc.ux4g.gov.in/web/llms/framework-syntax.md

## CSS source contract

Use https://cdn.ux4g.gov.in/UX4G@3.0.18/index.css in applications. The partial URLs below are evidence and debugging references; they are not standalone replacements for the complete bundle.

- Component partial: https://cdn.ux4g.gov.in/UX4G@3.0.18/components/switch.css
  - Repository source: `src/components/switch.css`
- Component partial: https://cdn.ux4g.gov.in/UX4G@3.0.18/components/list.css
  - Repository source: `src/components/list.css`

## DOM and attribute contract

- Elements used by canonical examples: `button`, `div`, `i`, `input`, `label`, `li`, `span`, `ul`
- Attributes used by canonical examples:
  - `aria-label`: `Toggle Label list toggle`, `Toggle option`, `Toggle options`
  - `checked`
  - `disabled`
  - `role`: `listbox`, `option`, `switch`
  - `type`: `button`, `checkbox`

## CSS class contract

Class categories are derived from the canonical markup and the shipped CSS partials. Plain structural state classes are included even when they do not start with `ux4g-`.

### Component classes used in canonical markup

`ux4g-list`, `ux4g-list-default`, `ux4g-list-item`, `ux4g-list-item-end`, `ux4g-list-item-row`, `ux4g-list-item-start`, `ux4g-list-m`, `ux4g-list-switch`, `ux4g-switch`, `ux4g-switch-content`, `ux4g-switch-control`, `ux4g-switch-desc-error`, `ux4g-switch-desc-helper`, `ux4g-switch-desc-icon`, `ux4g-switch-desc-icon-error`, `ux4g-switch-desc-icon-helper`, `ux4g-switch-desc-icon-success`, `ux4g-switch-desc-icon-warning`, `ux4g-switch-desc-success`, `ux4g-switch-desc-warning`, `ux4g-switch-description`, `ux4g-switch-icon`, `ux4g-switch-input`, `ux4g-switch-label`, `ux4g-switch-lg`, `ux4g-switch-md`, `ux4g-switch-sm`, `ux4g-switch-thumb`, `ux4g-switch-track`

### Structural and state classes used in canonical markup

`is-active`, `is-focused`, `is-hovered`

### Utility classes used in canonical markup

| Class | Exact utility CSS |
|---|---|
| `ux4g-icon` | https://cdn.ux4g.gov.in/UX4G@3.0.18/utilities/colors.utilities.css |

### Layout and foundation classes used in canonical markup

| Class | Source layer | Exact CSS |
|---|---|---|
| `ux4g-icon-outlined` | foundation | https://cdn.ux4g.gov.in/UX4G@3.0.18/foundations/icons.css |

### Additional classes supported by the resolved component CSS

`active`, `ux4g-check-icon`, `ux4g-checkbox`, `ux4g-d-flex`, `ux4g-list-action`, `ux4g-list-draggable`, `ux4g-list-error`, `ux4g-list-item-label`, `ux4g-list-item-label-support`, `ux4g-list-item-row-fixed`, `ux4g-list-item-rowm`, `ux4g-list-l`, `ux4g-list-s`, `ux4g-list-success`, `ux4g-list-warning`, `ux4g-list-xl`, `ux4g-radio`, `ux4g-switch-desc-icon-info`, `ux4g-switch-desc-info`, `ux4g-switch-reverse`, `ux4g-toggles`

### Unresolved classes requiring source review

`ux4g-list-switch-select`, `ux4g-switch-header`, `ux4g-switch-required`

## Documented variant groups

- Playground
- Toggle States Matrix
- Toggle Sizes
- Toggle Label Variants
- Toggle Description Variants
- Toggle List Interaction Patterns

## Framework adaptation

- The HTML below is canonical for HTML and Angular templates.
- In React/TSX, preserve the same elements, class values, ARIA attributes, data attributes, and DOM order; change only framework syntax such as `class` to `className` and `for` to `htmlFor`.
- Keep `aria-*` and `data-*` attributes hyphenated in React. Use JSX expressions only for dynamic state and event handlers.
- Do not replace the markup with an imported UX4G framework component. No such export exists.

## Code examples

The snippets below are extracted from the UX4G story source for Toggle. They are canonical HTML references; adapt only the framework syntax that your project requires.

### 1. Sizes - Sizes

HTML:
```html
<!-- Size: Large -->
<label class="ux4g-switch ux4g-switch-lg">
  <input checked class="ux4g-switch-input" type="checkbox" />
  <div class="ux4g-switch-control">
    <span class="ux4g-switch-track">
      <span class="ux4g-switch-thumb"></span>
    </span>
  </div>
  <div class="ux4g-switch-content">
    <span class="ux4g-switch-label">Toggle Large</span>
  </div>
</label>
<!-- Size: Medium -->
<label class="ux4g-switch ux4g-switch-md">
  <input checked class="ux4g-switch-input" type="checkbox" />
  <div class="ux4g-switch-control">
    <span class="ux4g-switch-track">
      <span class="ux4g-switch-thumb"></span>
    </span>
  </div>
  <div class="ux4g-switch-content">
    <span class="ux4g-switch-label">Toggle Medium</span>
  </div>
</label>
<!-- Size: Small -->
<label class="ux4g-switch ux4g-switch-sm">
  <input checked class="ux4g-switch-input" type="checkbox" />
  <div class="ux4g-switch-control">
    <span class="ux4g-switch-track">
      <span class="ux4g-switch-thumb"></span>
    </span>
  </div>
  <div class="ux4g-switch-content">
    <span class="ux4g-switch-label">Toggle Small</span>
  </div>
</label>
```

### 2. Label Variants - Label Variants

HTML:
```html
<!-- Variant: Full -->
<label class="ux4g-switch ux4g-switch-md">
  <input checked class="ux4g-switch-input" type="checkbox" />
  <div class="ux4g-switch-control">
    <span class="ux4g-switch-track">
      <span class="ux4g-switch-thumb"></span>
    </span>
  </div>
  <div class="ux4g-switch-content">
    <div class="ux4g-switch-header">
      <span class="ux4g-switch-label">Label</span>
      <span class="ux4g-switch-required">*</span>
      <span class="ux4g-switch-icon">
        <i class="ux4g-icon-outlined ux4g-switch-icon">token</i>
      </span>
    </div>
    <div class="ux4g-switch-description">
      <span class="ux4g-switch-desc-icon">
        <i class="ux4g-icon ux4g-switch-icon">info</i>
      </span>
      Description
    </div>
  </div>
</label>
<!-- Variant: Label + Required -->
<label class="ux4g-switch ux4g-switch-md">
  <input checked class="ux4g-switch-input" type="checkbox" />
  <div class="ux4g-switch-control">
    <span class="ux4g-switch-track">
      <span class="ux4g-switch-thumb"></span>
    </span>
  </div>
  <div class="ux4g-switch-content">
    <div class="ux4g-switch-header">
      <span class="ux4g-switch-label">Label</span>
      <span class="ux4g-switch-required">*</span>
    </div>
  </div>
</label>
<!-- Variant: Label Only -->
<label class="ux4g-switch ux4g-switch-md">
  <input checked class="ux4g-switch-input" type="checkbox" />
  <div class="ux4g-switch-control">
    <span class="ux4g-switch-track">
      <span class="ux4g-switch-thumb"></span>
    </span>
  </div>
  <div class="ux4g-switch-content">
    <div class="ux4g-switch-header">
      <span class="ux4g-switch-label">Label</span>
    </div>
  </div>
</label>
<!-- Variant: Control Only -->
<label class="ux4g-switch ux4g-switch-md">
  <input aria-label="Toggle option" checked class="ux4g-switch-input" type="checkbox" />
  <div class="ux4g-switch-control">
    <span class="ux4g-switch-track">
      <span class="ux4g-switch-thumb"></span>
    </span>
  </div>
</label>
```

### 3. Description Variants - Description Variants

HTML:
```html
<!-- Description: Helper -->
<label class="ux4g-switch ux4g-switch-md">
  <input class="ux4g-switch-input" type="checkbox" />
  <div class="ux4g-switch-control">
    <span class="ux4g-switch-track">
      <span class="ux4g-switch-thumb"></span>
    </span>
  </div>
  <div class="ux4g-switch-content">
    <div class="ux4g-switch-header">
      <span class="ux4g-switch-label">Label</span>
    </div>
    <div class="ux4g-switch-description ux4g-switch-desc-helper">
      <span class="ux4g-switch-desc-icon ux4g-switch-desc-icon-helper">
        <i class="ux4g-icon ux4g-switch-icon">info</i>
      </span>
      Helper text
    </div>
  </div>
</label>
<!-- Description: Error -->
<label class="ux4g-switch ux4g-switch-md">
  <input class="ux4g-switch-input" type="checkbox" />
  <div class="ux4g-switch-control">
    <span class="ux4g-switch-track">
      <span class="ux4g-switch-thumb"></span>
    </span>
  </div>
  <div class="ux4g-switch-content">
    <div class="ux4g-switch-header">
      <span class="ux4g-switch-label">Label</span>
    </div>
    <div class="ux4g-switch-description ux4g-switch-desc-error">
      <span class="ux4g-switch-desc-icon ux4g-switch-desc-icon-error">
        <i class="ux4g-icon ux4g-switch-icon">error</i>
      </span>
      Error text
    </div>
  </div>
</label>
<!-- Description: Warning -->
<label class="ux4g-switch ux4g-switch-md">
  <input checked class="ux4g-switch-input" type="checkbox" />
  <div class="ux4g-switch-control">
    <span class="ux4g-switch-track">
      <span class="ux4g-switch-thumb"></span>
    </span>
  </div>
  <div class="ux4g-switch-content">
    <div class="ux4g-switch-header">
      <span class="ux4g-switch-label">Label</span>
    </div>
    <div class="ux4g-switch-description ux4g-switch-desc-warning">
      <span class="ux4g-switch-desc-icon ux4g-switch-desc-icon-warning">
        <i class="ux4g-icon ux4g-switch-icon">warning</i>
      </span>
      Warning text
    </div>
  </div>
</label>
<!-- Description: Success -->
<label class="ux4g-switch ux4g-switch-md">
  <input checked class="ux4g-switch-input" type="checkbox" />
  <div class="ux4g-switch-control">
    <span class="ux4g-switch-track">
      <span class="ux4g-switch-thumb"></span>
    </span>
  </div>
  <div class="ux4g-switch-content">
    <div class="ux4g-switch-header">
      <span class="ux4g-switch-label">Label</span>
    </div>
    <div class="ux4g-switch-description ux4g-switch-desc-success">
      <span class="ux4g-switch-desc-icon ux4g-switch-desc-icon-success">
        <i class="ux4g-icon ux4g-switch-icon">check_circle</i>
      </span>
      Success text
    </div>
  </div>
</label>
```

## JavaScript and state ownership

- Runtime classification: UX4G runtime-enhanced standard DOM
- Global CDN runtime files remain https://cdn.ux4g.gov.in/UX4G@3.0.18/ux4g.js and https://cdn.ux4g.gov.in/UX4G@3.0.18/ux4g-custom.js.

### UX4G provides

- CSS presentation and the behavior implemented by the globally loaded UX4G runtime files.

### Application provides

- Application data, business rules, dynamic values, and event handlers that are not explicitly implemented by the UX4G runtime.

## Responsive behavior

| CSS partial | Breakpoint/condition | Component classes affected |
|---|---|---|
| `switch.css` | `(max-width: 768px)` | `ux4g-switch-control`, `ux4g-switch-desc-icon`, `ux4g-switch-description`, `ux4g-switch-icon`, `ux4g-switch-input`, `ux4g-switch-label`, `ux4g-switch-md`, `ux4g-switch-thumb`, `ux4g-switch-track` |

## Accessibility contract

- Preserve native element semantics and every documented label, relationship, and state attribute.
- Ensure every interactive control has an accessible name and is keyboard operable.
- Use `type="button"` for non-submit buttons placed inside forms.
- Verify focus visibility, focus order, and WCAG 2.1 AA contrast in the consuming application.

## Common mistakes

- Do not use `import { Toggle } from "ux4g-web-components"`.
- Do not invent `ux4g-*` classes or omit a documented structural/state class because it lacks the prefix.
- Do not copy Storybook documentation-shell classes into application markup.