Switch

The Switch component allows users to toggle a setting on or off. It supports various sizes, colors, custom icons, and can be controlled or uncontrolled.

Installation

$ cbui-cli install @crossbuildui/switch

Import

index.tsx
1import { Switch } from '@/crossbuildui/switch'; 2// import Icon from 'react-native-vector-icons/MaterialIcons'; // Or your preferred icon library for thumbIcon/content

Switch Component

Basic Usage

Provide children for the label. Use defaultSelected for initial uncontrolled state.

MyComponent.tsx
1<Switch defaultSelected>Enable Notifications</Switch>

Sizes

Adjust switch size with sm, md (default), or lg.

MyComponent.tsx
1<View style={{gap: 16, alignItems: 'flex-start'}}> 2 <Switch defaultSelected size="sm">Small Switch</Switch> 3 <Switch defaultSelected size="md">Medium Switch (Default)</Switch> 4 <Switch defaultSelected size="lg">Large Switch</Switch> 5</View>

Colors

Set the active color theme using the color prop. Supported colors include primary (default), secondary, success, warning, danger, and default.

MyComponent.tsx
1<View style={{gap: 16, alignItems: 'flex-start'}}> 2 <Switch defaultSelected color="primary">Primary</Switch> 3 <Switch defaultSelected color="secondary">Secondary</Switch> 4 <Switch defaultSelected color="success">Success</Switch> 5 <Switch defaultSelected color="warning">Warning</Switch> 6 <Switch defaultSelected color="danger">Danger</Switch> 7 <Switch defaultSelected color="default">Default</Switch> 8</View>

Thumb Icon

Provide a custom React element or a function returning one to the thumbIcon prop. The function receives {isSelected, isDisabled, color, iconSize}.

MyComponent.tsx
1<View style={{gap: 16, alignItems: 'flex-start'}}> 2 <Switch 3 defaultSelected 4 color="success" 5 thumbIcon={({isSelected, color, iconSize}) => 6 isSelected ? <Icon name="check" size={iconSize} color="white" /> : null 7 } 8 > 9 With Check Icon 10 </Switch> 11 <Switch 12 defaultSelected 13 color="danger" 14 thumbIcon={ 15 <Icon name="close" size={12} color="white" /> 16 } 17 > 18 With Close Icon (Static) 19 </Switch> 20 <Switch 21 defaultSelected 22 color="warning" 23 thumbIcon={({isSelected, iconSize}) => 24 isSelected ? <Icon name="lightbulb-on" size={iconSize} color="black" /> : <Icon name="lightbulb-off-outline" size={iconSize} color="black" /> 25 } 26 > 27 Dynamic Icon 28 </Switch> 29</View>

Start and End Content

Add elements before or after the switch label and visual toggle using startContent and endContent.

MyComponent.tsx
1<View style={{gap: 16, alignItems: 'flex-start'}}> 2 <Switch 3 defaultSelected 4 startContent={<Icon name="bell" size={20} color="gray" />} 5 > 6 Notifications 7 </Switch> 8 <Switch 9 defaultSelected 10 endContent={<Icon name="information-outline" size={20} color="blue" />} 11 > 12 Enable Feature 13 </Switch> 14 <Switch 15 defaultSelected 16 color="secondary" 17 startContent={<Icon name="bluetooth" size={20} />} 18 endContent={<Text style={{fontSize: 12, color: 'gray'}}>Nearby</Text>} 19 > 20 Bluetooth 21 </Switch> 22</View>

Controlled and Uncontrolled

Manage selection state externally using isSelected and onValueChange for a controlled component, or use defaultSelected for an uncontrolled component.

MyComponent.tsx
1function ControlledSwitch() { 2 const [isSelected, setIsSelected] = React.useState(true); 3 4 return ( 5 <View style={{gap: 8, alignItems: 'flex-start'}}> 6 <Switch 7 isSelected={isSelected} 8 onValueChange={setIsSelected} 9 > 10 Controlled Switch 11 </Switch> 12 <Text>Current State: {isSelected ? 'ON' : 'OFF'}</Text> 13 14 <Switch defaultSelected color="secondary"> 15 Uncontrolled (uses defaultSelected) 16 </Switch> 17 </View> 18 ); 19}

Disabled State

Use isDisabled to make the switch non-interactive.

MyComponent.tsx
1<Switch defaultSelected isDisabled>Disabled ON</Switch> 2<Switch isDisabled>Disabled OFF</Switch>

Disable Animation

Set disableAnimation= to turn off the toggle animations.

MyComponent.tsx
1<Switch defaultSelected disableAnimation> 2 Animation Disabled 3</Switch>

Props Overview

PROPTYPEDEFAULTDESCRIPTION
childrenReactNode-The label content for the switch.
valuestring-The value associated with the switch, used in forms.
size'sm' | 'md' | 'lg''md'Size of the switch.
colorSwitchThemeColor'primary'Active color theme.
thumbIconReactNode | (props: ThumbIconProps) => ReactNode-Icon within the thumb.
startContentReactNode-Content before the switch.
endContentReactNode-Content after the switch.
isSelectedboolean-Controlled selected state.
defaultSelectedbooleanfalseInitial selected state (uncontrolled).
isDisabledbooleanfalseDisable the switch.
disableAnimationbooleanfalseDisable toggle animations.
stylesPartial<SwitchStyleSlots>-Custom styles for switch slots.
styleStyleProp<ViewStyle>-Style for the outermost Pressable container.
onValueChange(isSelected: boolean) => void-Callback on selection change.
...PressablePropsvarious-Other props from React Native's Pressable.

Styling

Customize the Switch appearance using the style prop for the main wrapper or the styles prop for more granular control over internal slots:

  • style: Applied to the root Pressable component.
  • styles.base: Style for the root Pressable (merged with main style).
  • styles.contentWrapper: Style for the View that lays out startContent, label, switch visual, and endContent.
  • styles.label: Style for the label Text component.
  • styles.startContentWrapper: Style for the View wrapping startContent.
  • styles.endContentWrapper: Style for the View wrapping endContent.
  • styles.switchWrapper: Style for the View containing the track and thumb.
  • styles.track: Style for the switch track.
  • styles.thumb: Style for the switch thumb.
  • styles.thumbIconWrapper: Style for the View wrapping the thumbIcon.
MyComponent.tsx
1<Switch 2 defaultSelected 3 color="primary" 4 style={{ paddingVertical: 12, backgroundColor: '#e0e7ff', borderRadius: 8 }} // Base Pressable style 5 styles={{ 6 contentWrapper: { justifyContent: 'space-between', width: 200 }, 7 label: { color: 'purple', fontWeight: 'bold', fontStyle: 'italic' }, 8 switchWrapper: { marginRight: 10 }, // Push switch to the right 9 track: { backgroundColor: 'pink' }, // Overridden by animation when active 10 thumb: { borderWidth: 2, borderColor: 'darkblue', backgroundColor: 'lightblue' }, 11 thumbIconWrapper: { backgroundColor: 'transparent' } // Make thumb icon background transparent 12 }} 13 thumbIcon={<Icon name="star" size={12} color="gold" />} 14> 15 Custom Styled Switch 16</Switch>

Accessibility

The Switch component is built on Pressable and includes accessibility features:

  • accessibilityRole="switch" is set by default.
  • accessibilityState includes { checked: isSelected, disabled: isDisabled }.
  • An accessibilityLabel is automatically derived from string children, or the value prop if children is not a string. Provide a custom accessibilityLabel via pressableProps if needed for more complex children.
Slider Alert