#Switch

A <Switch> is essentially a customized checkbox with a toggleable interface to switch between an enable and disabled state.

#Import

import { Switch, SwitchField } from 'bumbag'

#Usage

Check me

<Switch label="Check me" />

<Switch label="Check me" />

#Fields

You can also use the <SwitchField> component, which internally has a FieldWrapper to wrap form controls such as labels, hint text and validation text.

It accepts a combination of Switch props and FieldWrapper props.

Check below to subscribe

Check me

<SwitchField
  switchLabel="Check me"
  label="Check below to subscribe"
/>

<SwitchField
  switchLabel="Check me"
  label="Check below to subscribe"
/>

#Disabled

Make the switch disabled with the disabled prop.

Click me

<Switch disabled label="Click me" />
<Switch checked disabled label="Click me" />

<Switch disabled label="Click me" />
<Switch checked disabled label="Click me" />

#Colors

Add colors to your switch by using the palette prop.

Check me

<Switch defaultChecked palette="secondary" label="Check me" />
<Switch defaultChecked palette="success" label="Check me" />
<Switch defaultChecked palette="danger" label="Check me" />
<Switch defaultChecked palette="warning" label="Check me" />

<Switch defaultChecked palette="secondary" label="Check me" />
<Switch defaultChecked palette="success" label="Check me" />
<Switch defaultChecked palette="danger" label="Check me" />
<Switch defaultChecked palette="warning" label="Check me" />

#States

A switch can use different states (as per palette) such as danger, success and warning.

Click me

<Switch state="danger" label="Click me" />
<Switch state="success" label="Click me" />
<Switch state="warning" label="Click me" />
<Switch state="primary" label="Click me" />

<Switch state="danger" label="Click me" />
<Switch state="success" label="Click me" />
<Switch state="warning" label="Click me" />
<Switch state="primary" label="Click me" />

#Controlled Usage

The previous examples are examples of uncontrolled usage. To control the value yourself, use a combination of onChange and value.

Note: Do not use defaultValue with controlled inputs!

Click me

function Example() {
  const [checked, setChecked] = React.useState(true);

  return (
    <Switch
      label="Click me"
      checked={checked}
      onChange={e => setChecked(e.target.checked)}
    />
  );
}

function Example() {
  const [checked, setChecked] = React.useState(true);
  return (
    <Switch
      label="Click me"
      checked={checked}
      onChange={e => setChecked(e.target.checked)}
    />
  );
}

#Accessibility

The <Switch> component follows the WAI ARIA Checkbox Pattern.

#Rules

The switch must have a label prop to identify it's label. If a label prop is not provided, an aria-label or aria-labelledby prop can be specified.

#Patterns

The switch has a role of checkbox.
The switch has an accessible label specified via the label, aria-labelledby or aria-label prop.
When the switch has focus, pressing the Space key changes the state of the checkbox.

#References

WAI ARIA Checkbox Pattern

#Props

#Switch Props

autoFocus boolean

Automatically focus on the switch

checked boolean

inputProps InputHTMLAttributes<any>

defaultChecked boolean

Is the switch checked by default?

disabled boolean

Disables the switch

isRequired boolean

Makes the switch required and sets aria-invalid to true

label string

Switch label

palette

"default"
  | "primary"
  | "secondary"
  | "success"
  | "danger"
  | "warning"
  | (string & {})

name string

state

"default"
  | "primary"
  | "secondary"
  | "success"
  | "danger"
  | "warning"
  | (string & {})

State of the switch. Can be any color in the palette.

switchRef ((instance: any) => void) | RefObject<any>

value string | boolean

Initial value of the switch

onBlur (event: FocusEvent<HTMLInputElement>) => void

Function to invoke when focus is lost

onChange (event: FormEvent<HTMLInputElement>) => void

Function to invoke when switch has changed

onFocus (event: FocusEvent<HTMLInputElement>) => void

Function to invoke when switch is focused

#SwitchField Props

switchLabel string

Label for the switch

switchProps

Pick<BoxProps, "children"
  | "unstable_system"
  | "defaultChecked"
  | "defaultValue"
  | "suppressContentEditableWarning"
  | "suppressHydrationWarning"
  | "accessKey"
  | ... 772 more ...
  | "themeKey"> & LocalSwitchProps

Additional props for the Switch component

Inherits Switch props

autoFocus boolean

Automatically focus on the switch

checked boolean

inputProps InputHTMLAttributes<any>

defaultChecked boolean

Is the switch checked by default?

disabled boolean

Disables the switch

isRequired boolean

Makes the switch required and sets aria-invalid to true

label string

Switch label

palette

"default"
  | "primary"
  | "secondary"
  | "success"
  | "danger"
  | "warning"
  | (string & {})

name string

state

"default"
  | "primary"
  | "secondary"
  | "success"
  | "danger"
  | "warning"
  | (string & {})

State of the switch. Can be any color in the palette.

switchRef ((instance: any) => void) | RefObject<any>

value string | boolean

Initial value of the switch

onBlur (event: FocusEvent<HTMLInputElement>) => void

Function to invoke when focus is lost

onChange (event: FormEvent<HTMLInputElement>) => void

Function to invoke when switch has changed

onFocus (event: FocusEvent<HTMLInputElement>) => void

Function to invoke when switch is focused

Inherits FieldWrapper props

children

ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>
  | (({ elementProps }: { ...; }) => ReactNode)

description

string
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>

Sets the description text of the field wrapper.

hint

string
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>

Sets the bottom hint text of the field wrapper.

isOptional boolean

Sets the optional flag (and displays optional text) on the field wrapper.

labelType "label" | "legend"

Sets the label type on the field wrapper.

tooltip

string
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>

Sets the tooltip of the field wrapper. Can be either a string, or a React component.

tooltipTriggerComponent

ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>

Sets the tooltip trigger component.

validationText string

Sets the bottom validation text of the field wrapper.

Inherits Box props

use

string
  | (ComponentClass<any, any> & { useProps: any; })
  | (FunctionComponent<any> & { useProps: any; })

className string

alignX "left" | "right" | "center"

alignY "bottom" | "top" | "center"

altitude string

variant string

colorMode string

overrides

{
  useCSSVariables?: boolean;
  altitudes?: AltitudesThemeConfig;
  borders?: BordersThemeConfig;
  borderRadii?: BorderRadiiThemeConfig;
  ... 94 more ...;
  Template?: TemplateThemeConfig;
}

elementRef ((instance: any) => void) | RefObject<any>

themeKey string

#Theming

#Switch

Switch.styles.base

Click me

Switch.Icon.styles.base

Click me

Switch.Label.styles.base

Click me

Switch.HiddenInput.styles.base

Click me

#SwitchField

SwitchField.styles.base

Check below to subscribe

Click me