Button

The Button component allows users to trigger actions. It supports various styles, sizes, loading states, and can be grouped with ButtonGroup.

Installation

$ cbui-cli install button

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

index.tsx

import { Button, ButtonGroup, ButtonGroupContext, useButtonGroup } from '@/crossbuildui/button';
// import Icon from 'react-native-vector-icons/MaterialCommunityIcons'; // If using icons

Button Component

Basic Usage

Provide children (text or ReactNode) and a color prop.

index.tsx

<Button color="primary">Primary Button</Button>
<Button color="secondary" style={{marginLeft: 8}}>Secondary Button</Button>

Variants

Buttons support multiple visual variant options: solid (default), faded, bordered, light, flat, ghost, shadow, and glass.

index.tsx

<View style={{flexDirection: 'row', flexWrap: 'wrap', gap: 8}}>
  <Button color="primary" variant="solid">Solid</Button>
  <Button color="primary" variant="faded">Faded</Button>
  <Button color="primary" variant="bordered">Bordered</Button>
  <Button color="primary" variant="light">Light</Button>
  <Button color="primary" variant="flat">Flat</Button>
  <Button color="primary" variant="ghost">Ghost</Button>
  <Button color="primary" variant="shadow">Shadow</Button>
  <Button color="primary" variant="glass">Glass</Button>
</View>

Sizes

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

index.tsx

<View style={{flexDirection: 'row', alignItems: 'center', gap: 8}}>
  <Button color="success" size="sm">Small</Button>
  <Button color="success" size="md">Medium (Default)</Button>
  <Button color="success" size="lg">Large</Button>
</View>

Radius

Control the border radius with none, sm, md (default), lg, or full.

index.tsx

<View style={{flexDirection: 'row', flexWrap: 'wrap', gap: 8}}>
  <Button color="warning" radius="none">None</Button>
  <Button color="warning" radius="sm">Small</Button>
  <Button color="warning" radius="md">Medium (Default)</Button>
  <Button color="warning" radius="lg">Large</Button>
  <Button color="warning" radius="full">Full</Button>
</View>

With Icons

Add icons using startContent or endContent. Use isIconOnly for buttons containing only an icon.

index.tsx

// Example using hypothetical Icon component
<View style={{flexDirection: 'row', alignItems: 'center', gap: 8}}>
  <Button color="danger" startContent={<Icon name="delete" size={18} />}>
    Delete
  </Button>
  <Button color="primary" endContent={<Icon name="send" size={18} />}>
    Send
  </Button>
  <Button color="secondary" isIconOnly>
    <Icon name="cog" size={20} />
  </Button>
</View>

Loading State

Set isLoading= to display a spinner. You can provide a custom spinner element.

index.tsx

<Button color="primary" isLoading>
  Loading...
</Button>

{/* Example with custom spinner */}
<Button
  color="secondary"
  isLoading
  spinner={<ActivityIndicator color="white" size="small" />}
  style={{marginTop: 8}}
>
  Processing
</Button> 

Full Width

Make the button span the full width of its parent with fullWidth=.

index.tsx

<Button color="default" fullWidth>
  Full Width Button
</Button>

Disabled State

Disable the button using the disabled prop.

index.tsx

<Button color="primary" disabled>
  Disabled Button
</Button>

Glass Variant

The glass variant applies a frosted glass effect to the button background using expo-blur. Customize it with glassIntensity (0-100) and glassTint ('light', 'dark', 'default'). Text and icon colors for this variant typically default to the theme's foreground color.

index.tsx

<View style={{flexDirection: 'row', flexWrap: 'wrap', gap: 8}}>
  <Button color="primary" variant="glass" glassIntensity={70} glassTint="light">
    Light Glass
  </Button>
  <Button color="secondary" variant="glass" glassIntensity={40} glassTint="dark" startContent={<Icon name="blur-on" size={18} color="white" />}>
    Dark Glass
  </Button>
  <Button variant="glass" isIconOnly>
    <Icon name="settings" size={20} />
  </Button>
</View>

<ButtonGroup color="success" variant="glass" glassIntensity={50} style={{marginTop: 10}}>
  <Button>Glass Group 1</Button>
  <Button>Glass Group 2</Button>
</ButtonGroup>

ButtonGroup Component

Basic Usage

Group multiple Button components. Props like color, variant, size, radius, and glass props (glassTint, glassIntensity) can be set on ButtonGroup to apply to all children.

index.tsx

<ButtonGroup color="primary" variant="solid">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
</ButtonGroup>

Attached Buttons

Use isAttached= to remove spacing between buttons and create a visually connected group. The radius prop on ButtonGroup will then apply to the outer corners of the group. Use isVertical for vertical stacking.

index.tsx

<ButtonGroup color="secondary" variant="bordered" isAttached radius="md">
  <Button>Left</Button>
  <Button>Middle</Button>
  <Button>Right</Button>
</ButtonGroup>

<ButtonGroup color="success" variant="faded" isAttached isVertical radius="lg" style={{marginTop: 10}}>
  <Button>Top</Button>
  <Button>Center</Button>
  <Button>Bottom</Button>
</ButtonGroup>

Individual Overrides

Props set on individual Button components within a ButtonGroup will override the group's settings.

index.tsx

<ButtonGroup color="warning" size="lg">
  <Button>Large Warn</Button>
  <Button color="danger" size="sm">Small Danger</Button>
  <Button>Large Warn</Button>
</ButtonGroup>

Using ButtonGroup Context

For advanced scenarios, or if you need to create custom components that react to the ButtonGroup's properties, you can use the useButtonGroup hook. This hook provides access to the ButtonGroupContext, which includes properties like color, size, variant, isDisabled, isAttached, isVertical, and glass props.

Any component calling useButtonGroup must be a descendant of a ButtonGroup component.

MyCustomGroupComponent.tsx

import { Button, ButtonGroup, useButtonGroup } from '@/crossbuildui/button';
import { Text, View } from 'react-native';

const GroupInfoDisplay = () => {
  const context = useButtonGroup();

  if (!context) {
    // This should not happen if GroupInfoDisplay is used correctly within a ButtonGroup
    return <Text>Not within a ButtonGroup context.</Text>;
  }

  const { color, size, variant, isDisabled, isAttached, isVertical } = context;

  return (
    <View style={{ marginTop: 8, padding: 8, backgroundColor: '#f0f0f0', borderRadius: 4 }}>
      <Text>Group Context:</Text>
      <Text>- Color: {color || 'default'}</Text>
      <Text>- Size: {size || 'md'}</Text>
      <Text>- Variant: {variant || 'solid'}</Text>
      <Text>- Disabled: {isDisabled ? 'Yes' : 'No'}</Text>
      <Text>- Attached: {isAttached ? 'Yes' : 'No'}, Vertical: {isVertical ? 'Yes' : 'No'}</Text>
    </View>
  );
};
<ButtonGroup color="success" size="sm" isAttached><Button>First</Button><Button>Second</Button><GroupInfoDisplay /></ButtonGroup>

Props Overview

Button Props

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactNode`	-	Content of the button.
`variant`	`ButtonVariant`	`'solid'`	Visual style.
`color`	`ButtonColor`	`'default'`	Semantic color.
`size`	`ButtonSize`	`'md'`	Size of the button.
`radius`	`ButtonRadius`	`'md'`	Border radius.
`fullWidth`	`boolean`	`false`	Take full parent width.
`isLoading`	`boolean`	`false`	Loading state.
`spinner`	`ReactElement`	-	Custom spinner element.
`spinnerProps`	`ActivityIndicatorProps`	-	Props for default spinner.
`startContent`	`ReactElement`	-	Content before children.
`endContent`	`ReactElement`	-	Content after children.
`isIconOnly`	`boolean`	`false`	Style for icon-only button.
`style`	`StyleProp<ViewStyle>`	-	Custom style for the `Pressable`.
`textStyle`	`StyleProp<TextStyle>`	-	Custom style for text children.
`disabled`	`boolean`	`false`	Disable the button.
`onPress`	`PressableProps['onPress']`	-	Callback on press.
`glassTint`	`'default' \| 'light' \| 'dark'`	Theme-derived	Tint for the 'glass' variant blur effect.
`glassIntensity`	`number`	50	Intensity (0-100) for the 'glass' variant blur effect.
`...PressableProps`	various	-	Other props from React Native's Pressable.

ButtonGroup Props

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactElement<ButtonProps>[]`	-	Button components to group.
`variant`	`ButtonVariant`	-	Default variant for grouped buttons.
`color`	`ButtonColor`	-	Default color for grouped buttons.
`size`	`ButtonSize`	-	Default size for grouped buttons.
`radius`	`ButtonRadius`	-	Default radius for grouped buttons (applies to outer corners if attached).
`fullWidth`	`boolean`	`false`	Group takes full parent width.
`isVertical`	`boolean`	`false`	Stack buttons vertically.
`isAttached`	`boolean`	`false`	Attach buttons (no space, shared borders).
`glassTint`	`'default' \| 'light' \| 'dark'`	Theme-derived	Default tint for 'glass' variant on grouped buttons.
`glassIntensity`	`number`	50	Default intensity (0-100) for 'glass' variant.
`style`	`StyleProp<ViewStyle>`	-	Custom style for the group container.

Styling

Customize appearance using:

Button:
- style: Applied to the root Pressable component of the button.
- textStyle: Applied to the Text component if children is a string.
- For the glass variant, the background is rendered by BlurView from expo-blur, controlled by glassIntensity and glassTint. The style prop's backgroundColor will be overridden for this variant.
ButtonGroup:
- style: Applied to the root View container of the group.
- Individual buttons within a group can also have their own style prop, which will be merged with styles derived from the group (e.g., for attached borders).

index.tsx

<Button
  color="primary"
  variant="solid"
  style={{ marginVertical: 10, transform: [{ skewX: '-5deg' }] }} // Styles the outer Pressable
  textStyle={{ fontWeight: 'bold', letterSpacing: 1 }}
  startContent={<Icon name="star" size={18} />}
>
  Styled Button
</Button>

<ButtonGroup
  style={{ padding: 10, backgroundColor: '#f0f0f0', borderRadius: 12 }}
  isAttached
  radius="lg"
  color="default"
>
  <Button>Grouped Styled 1</Button>
  <Button style={{borderColor: 'purple', borderWidth: 1}}>Grouped Styled 2</Button>
</ButtonGroup>

Accessibility

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

accessibilityRole="button" is set by default.
accessibilityState includes disabled and busy (when isLoading is true).
Ensure meaningful text content or provide an accessibilityLabel for icon-only buttons.

Snippet Checkbox