@asphalt-react/toggle-button/README.md

ToggleButton

# ToggleButton

![npm](https://img.shields.io/npm/dt/@asphalt-react/toggle-button?style=flat-square)
[![npm version](https://badge.fury.io/js/@asphalt-react%2Ftoggle-button.svg)](https://badge.fury.io/js/@asphalt-react%2Ftoggle-button)

A ToggleButton is a digital switch to turn an option on or off. Switching between the states — as a result of direct user action or a programmatic event. The caption should always reflect the current logical state of the button.

ToggleButtons can form a group by sticking to each other which enables creating composite components using ToggleButtons.

## Usage

```jsx
import { ToggleButton } from '@asphalt-react/toggle-button'

<ToggleButton on>mute</ToggleButton>
```

## Variants

ToggleButton comes in 3 variants -

* **Text only**: ToggleButton having text caption.
* **Icon only**: Icon as caption (which we also refer as Icon ToggleButton). For space constraint uses, Icon ToggleButton also has a compact form. The compact form also supports an option to put more emphasis on the icon instead of the button.
* **Text with icon**: Text with icon (left or right to the text) as caption.

## Sizes

ToggleButton supports 4 sizes:
\- extra small (xs)
\- small (s)
\- medium (m)
\- large (l)

## Group ToggleButtons

You can group two or more toggle buttons by sticking them together using `stickStart`, `stickEnd` & `stick` props.

Set `stickEnd` to `true` on start button and `stickStart` to `true` on the end button. If you are grouping more that two buttons use `stickEnd` & `stickStart` both on all the buttons in the middle.

Use `stick` prop optionally on the end button to enhance it's style in order to make default and second button look good together. `stick` renders the toggle button without left border.

```jsx
import { ToggleButton } from '@asphalt-react/toggle-button'

<div>
    <ToggleButton on stickEnd>left align</ToggleButton>
    <ToggleButton stickStart stick>right align</ToggleButton>
<div>
```

## When to use a ToggleButton?

### ToggleButton vs Checkbox

ToggleButtons are not an alternative to Checkboxes. They are not form controls and should not appear inside a form. ToggleButtons should only manipulate local UI states, i.e. they should not directly or indirectly initiate a remote API call to change database states.

### ToggleButton vs ToggleSwitch

Both of them provide options to toggle between states. Consider the following points to choose between them:

1. Prefer ToggleSwitches to toggle states on mobile; they support swipe gestures
2. ToggleButtons fit better in designs with space constraints
3. Use ToggleButtons to programmatically toggle the state. For example, you can bind a keyboard shortcut to a *mute* button in a video player.

## Accessibility

1. ToggleButtons accept most of the [button element's attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) such as `disabled` & `onClick` and supports [data-\* attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes).

2. ToggleButton is focusable and keyboard navigable; <kbd>tab</kbd> (or <kbd>shift</kbd>+<kbd>tab</kbd> when tabbing backwards).

3. <kbd>space</kbd> and <kbd>enter</kbd> toggles the state of ToggleButton.

4. ToggleButton has a role of “[button](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role)”.

5. ToggleButton uses `aria-pressed` to assist screen readers; the on/off state of ToggleButton determines its value.

6. ToggleButton accept the aria-\* attributes [button role](https://www.w3.org/TR/wai-aria-1.1/#button).

## Accessibility must-haves

Add `aria-label` or `aria-labelledby` in Icon ToggleButton to help assistive technologies.

[comment]: # "ToggleButton Props"

## Props

### children

React node for caption

| type | required | default |
| ---- | -------- | ------- |
| node | true     | N/A     |

### seamless

Renders a seamless variant

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### on

Sets the state of button

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### size

Sets the size of button. Possible values are `"xs", "s", "m", "l"` for extra small, small, medium & large respectively

| type | required | default |
| ---- | -------- | ------- |
| enum | false    | "m"     |

### link

Renders a link ToggleButton

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### as

Link element to render. Accepts an HTML element or a React component.

| type        | required | default |
| ----------- | -------- | ------- |
| elementType | false    | "a"     |

### asProps

Accepts props & attributes for the link element.

| type   | required | default |
| ------ | -------- | ------- |
| object | false    | {}      |

### icon

Renders an Icon ToggleButton.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### compact

Renders a ToggleButton with less spacing around.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### emphasize

Emphasizes the icon instead of background by coloring it.
Works only for Compact Icon ToggleButton

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### qualifier

Qualifiers are icons that enhance the caption. ToggleButton prepends the qualifier by default

Accepts SVG or SVG wrapped React component. Checkout `@asphalt-react/iconpack` for SVG wrapped React components.

> ⚠️ Do not use `qualifier` to render an Icon ToggleButton, use `icon` prop instead

| type    | required | default |
| ------- | -------- | ------- |
| element | false    | null    |

### qualifierEnd

Appends qualifier to the caption

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### stickStart

Adapts to let other buttons stick to its start

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### stickEnd

Adapts to let other buttons stick to its end

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### stick

Enhances the style of the supporting button.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### underline

Adds underline in link ToggleButton

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |