ToggleButton

A button component with a toggle state, pressed or not pressed.

Component usage

Using the isPressed-property, you determine wether the button is “pressed” or not. The label of a toggle button should not change when its state changes.

For more info, see the MDN docs on the role Toggle Button.

import { ToggleButton } from "@caspeco/casper-ui-library";
import { useState } from "react";

export default function Demo() {
  const [pressed, setPressed] = useState(false);

  return (
    <ToggleButton isPressed={pressed} onClick={() => setPressed(!pressed)}>
      Toggle me
    </ToggleButton>
  );
}

⛶

Grouping Toggle buttons

Commonly, a toggle button is used alongside other buttons, and the isPressed-property is used to indicate which button is currently selected.

import { Stack, ToggleButton } from "@caspeco/casper-ui-library";
import { useState } from "react";

export default function Demo() {
  const [pressed, setPressed] = useState("left");

  return (
    <Stack direction="row">
      <ToggleButton isPressed={pressed === "left"} onClick={() => setPressed("left")}>
        Left
      </ToggleButton>
      <ToggleButton isPressed={pressed === "right"} onClick={() => setPressed("right")}>
        Right
      </ToggleButton>
    </Stack>
  );
}

⛶

Toggle button with sub text

The toggle button can be rendered with a sub text by adding the subText property and setting an aria-label. The aria-label attribute is required since the multi line elements inside the button will be set to aria-hidden by the component so the button will need the aria-label to be able to present what the content is.

subText only works with medium and large size buttons due to space restrictions at smaller sizes. When using responsive size values (arrays or objects like size={["sm", "md", "lg"]} or size={{ base: "sm", md: "md" }}), the subText will dynamically show or hide based on the active breakpoint - it shows when the current size is "md" or "lg" and hides when the size is "sm" or smaller.

If there is a width restriction on the button it will truncate the text with ellipsis.

import { Stack, ToggleButton } from "@caspeco/casper-ui-library";
import { useState } from "react";

export default function Demo() {
  const [pressed1, setPressed1] = useState(false);
  const [pressed2, setPressed2] = useState(false);
  const [pressed3, setPressed3] = useState(false);
  const [pressed4, setPressed4] = useState(false);
  const [pressed5, setPressed5] = useState(false);

  return (
    <Stack direction="column" gap="16px" width="200px">
      <ToggleButton
        size="lg"
        subText="Additional info"
        aria-label="Settings with additional info"
        isPressed={pressed1}
        onClick={() => setPressed1(!pressed1)}
      >
        Settings
      </ToggleButton>

      <ToggleButton
        subText="Very long additional information text that will be truncated with ellipsis"
        aria-label="Options with very long additional information text that will be truncated with ellipsis"
        isPressed={pressed2}
        onClick={() => setPressed2(!pressed2)}
      >
        Options
      </ToggleButton>

      <ToggleButton
        size="sm"
        subText="This won't render"
        aria-label="Small button with subText that doesn't render"
        isPressed={pressed3}
        onClick={() => setPressed3(!pressed3)}
      >
        Small
      </ToggleButton>

      <ToggleButton
        size={["sm", "md", "lg"]}
        subText="This will render depending on screen size"
        aria-label="Responsive button with subText that renders depending on screen size"
        isPressed={pressed4}
        onClick={() => setPressed4(!pressed4)}
      >
        Array responsive
      </ToggleButton>

      <ToggleButton
        size={{ base: "sm", md: "md", lg: "lg" }}
        subText="This will render depending on screen size"
        aria-label="Responsive button with subText that renders depending on screen size"
        isPressed={pressed5}
        onClick={() => setPressed5(!pressed5)}
      >
        Object responsive
      </ToggleButton>
    </Stack>
  );
}

⛶

Toggle button vs Checkbox vs Radio Card

A toggle button is not the same as a checkbox or a radio card. They visually all share some sort of “selected” state, but they are used for different purposes and are conveyed differently to screen reader users.

The choice between these will depend on the type of toggle you are creating, and whether or not the toggle will make sense to users when announced as a checkbox or as an actual button.