# Toggle


## Examples

### Default

```html
<m-toggle
      ?checked=${args.checked}
      ?disabled=${args.disabled}
      ?reversed=${args.reversed}
      label=${args.label}
      value=${args.value}
      error=${args.error}
      hint=${args.hint}
      description=${args.description}
      ?labelHidden=${args.labelHidden}
      name=${args.name}
    ></m-toggle>
```

### States

```html
<m-stack direction="vertical" spacing="m">
        <m-toggle label="Default toggle"></m-toggle>
        <m-toggle label="Checked toggle" checked></m-toggle>
        <m-toggle label="Disabled toggle" disabled></m-toggle>
        <m-toggle label="Disabled checked toggle" disabled checked></m-toggle>
        <m-toggle label="Reversed Toggle" reversed></m-toggle>
    </m-stack>
```

### WithError

```html
<m-stack direction="vertical" spacing="m">
      <m-toggle label="Default toggle with error" error="Error message"></m-toggle>
       <span slot="error">Error message</span>

      <m-toggle label="Checked toggle with error" checked error="Error message"></m-toggle>
        <span slot="error">Error message</span>
      </m-toggle>
      </m-stack>
```

### WithHint

```html
<m-toggle
        label="Toggle with hint"
        hint="This is a hint text"
      ></m-toggle>
```

### WithErrorAndHint

```html
<m-stack direction="vertical" spacing="m">
        <m-toggle
          label="Toggle with error and hint"
          error="Error message"
          hint="This is a hint text"
        ></m-toggle>
      </m-stack>
```

### LongLabel

```html
<m-stack direction="vertical" spacing="m">
        <m-toggle
          label="This is a very long toggle label that demonstrates how the component handles text wrapping and overflow when the label text extends beyond the typical single line length"
        ></m-toggle>
        <m-toggle
          label="This is a very long toggle label that demonstrates how the component handles text wrapping and overflow when the label text extends beyond the typical single line length"
          reversed
        ></m-toggle>
      </m-stack>
```

### LongTexts

```html
<m-stack direction="vertical" spacing="m">
        <m-toggle
          label="This is a very long toggle label that demonstrates how the component handles text wrapping and overflow when the label text extends beyond the typical single line length"
          hint="This is a very long hint text that provides additional context and guidance to the user about what this toggle does and how it affects the application's behavior when enabled or disabled"
          error="This is a very long error message that explains in detail what went wrong and provides specific guidance on how to resolve the issue that caused this validation error to occur"
        ></m-toggle>
        <m-toggle
          label="This is a very long toggle label that demonstrates how the component handles text wrapping and overflow when the label text extends beyond the typical single line length"
          hint="This is a very long hint text that provides additional context and guidance to the user about what this toggle does and how it affects the application's behavior when enabled or disabled"
          error="This is a very long error message that explains in detail what went wrong and provides specific guidance on how to resolve the issue that caused this validation error to occur"
          reversed
        ></m-toggle>
      </m-stack>
```

## Usage

**Use the Toggle to:**
- Enable or disable a setting with an immediate effect.
- Represent a binary choice (e.g., on/off, show/hide, enable/disable).
- Improve clarity when changes apply instantly without additional confirmation.
- Make a setting’s status clearly visible at a glance.

**Do not use the Toggle to:**
- Submit forms or trigger complex actions (use buttons instead).
- Choose between more than two options (use radio buttons or dropdowns instead).
- Require explicit confirmation before applying changes (use checkboxes or modals).
- Replace checkboxes for settings that require additional information or context.

## Other Considerations

- **Labeling:** Ensure toggles have clear, descriptive labels. Labels should explain what the toggle controls (e.g., "Enable Dark Mode").
- **Default State:** Default states should be based on user expectations. If a feature is optional, it should be off by default.
- **Grouping:** If multiple toggles are related, visually group them together to maintain clarity.

## Design Rationale
- **Immediate Feedback:** Unlike checkboxes, toggles indicate that changes take effect immediately, making them ideal for system or UI settings.
- **Recognition Over Recall:** A toggle’s visual representation (switching between states) helps users understand its purpose at a glance.
- **Consistency:** Standardizing toggles across the application ensures a familiar and predictable user experience.