ToggleButton

Import

import { ToggleButton } from 'heroui-native-pro';

Anatomy

<ToggleButton>
  <ToggleButton.Label>...</ToggleButton.Label>
</ToggleButton>

• ToggleButton: Root pressable wrapping HeroUI Native Button. Owns the controllable selection state, applies selected/unselected background styling, and integrates with ToggleButtonGroup via context (selection, size, disabled state). Exposes its state to descendants through useToggleButton.
• ToggleButton.Label: Text label inside the toggle. Wraps Button.Label and automatically applies selected/unselected text colors based on the parent toggle state.

Usage

Basic usage

Pass a string as children to render a label.

<ToggleButton>Like</ToggleButton>

Compound label

Use ToggleButton.Label for explicit control over the label element.

<ToggleButton>
  <ToggleButton.Label>Like</ToggleButton.Label>
</ToggleButton>

With icon

Compose icons alongside the label inside the toggle.

<ToggleButton>
  <HeartIcon />
  <ToggleButton.Label>Like</ToggleButton.Label>
</ToggleButton>

Variants

Switch the resting background style with the variant prop. Both variants share the same selected appearance.

<ToggleButton variant="default">...</ToggleButton>
<ToggleButton variant="ghost">...</ToggleButton>

Sizes

Control the button dimensions with the size prop.

<ToggleButton size="sm">...</ToggleButton>
<ToggleButton size="md">...</ToggleButton>
<ToggleButton size="lg">...</ToggleButton>

Icon only

Set isIconOnly to render a square button with no horizontal padding.

<ToggleButton isIconOnly accessibilityLabel="Like">
  <HeartIcon />
</ToggleButton>

Controlled

Use isSelected and onChange for controlled state, or defaultSelected for uncontrolled.

<ToggleButton isSelected={isSelected} onChange={setIsSelected}>
  ...
</ToggleButton>

Custom colors

Override the resting and selected background colors with unselectedColor and selectedColor. Pass resolved color strings (e.g. from useThemeColor).

<ToggleButton selectedColor={dangerSoftColor}>...</ToggleButton>

Disabled

Set isDisabled to dim the button and block presses.

<ToggleButton isDisabled>...</ToggleButton>
<ToggleButton isDisabled defaultSelected>...</ToggleButton>

Inside a group

Place toggles inside a ToggleButtonGroup and assign each an id. The group manages selection, size, and disabled state.

<ToggleButtonGroup selectionMode="multiple">
  <ToggleButton id="bold" isIconOnly>
    ...
  </ToggleButton>
  <ToggleButton id="italic" isIconOnly>
    ...
  </ToggleButton>
  <ToggleButton id="underline" isIconOnly>
    ...
  </ToggleButton>
</ToggleButtonGroup>

Reading state from descendants

Call useToggleButton from a descendant to react to the toggle state without prop drilling.

const HeartToggle = () => {
  const { isSelected } = useToggleButton();
  return <HeartIcon filled={isSelected} />;
};

<ToggleButton>
  <HeartToggle />
  <ToggleButton.Label>Like</ToggleButton.Label>
</ToggleButton>;

Example

import { useThemeColor } from 'heroui-native';
import { ToggleButton, useToggleButton } from 'heroui-native-pro';
import { View } from 'react-native';
import Svg, { Path } from 'react-native-svg';

const HeartIcon = ({ color, filled }: { color: string; filled: boolean }) => (
  <Svg width={18} height={18} viewBox="0 0 24 24" fill="none">
    <Path
      d="M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z"
      stroke={color}
      strokeWidth={2}
      strokeLinecap="round"
      strokeLinejoin="round"
      fill={filled ? color : 'none'}
    />
  </Svg>
);

const HeartToggleContent = () => {
  const { isSelected } = useToggleButton();
  const fg = useThemeColor('foreground') as string;
  const accentFg = useThemeColor('accent-soft-foreground') as string;
  const color = isSelected ? accentFg : fg;
  return (
    <>
      <HeartIcon filled={isSelected} color={color} />
      <ToggleButton.Label>{isSelected ? 'Liked' : 'Like'}</ToggleButton.Label>
    </>
  );
};

export default function ToggleButtonExample() {
  return (
    <View className="flex-row items-center gap-3">
      <ToggleButton>
        <HeartToggleContent />
      </ToggleButton>
      <ToggleButton variant="ghost">
        <HeartToggleContent />
      </ToggleButton>
    </View>
  );
}

API Reference

ToggleButton

ToggleButton extends every prop of HeroUI Native Button except variant (redefined as ToggleButtonVariant) and feedbackVariant (owned by ToggleButton).

The background prop forwards to the underlying core Button, which renders Button.Background behind the toggle surface for the default variant while unselected (selection paints its own accent-soft tint) when the active library theme registers default background content (e.g. glass).

ToggleButtonVariant

ToggleButton.Label

Hooks

useToggleButton

Hook to access the ToggleButton context. Must be used within a ToggleButton component.

import { useToggleButton } from 'heroui-native-pro';

const { isSelected, isDisabled, size, variant } = useToggleButton();

Returns: ToggleButtonContextValue