Looking for documentation on gluestack-ui v2 with NativeWind? Refer to this link.
This is an illustration of a Themed Button component with default configuration.
size
variant
action
isDisabled
isFocusVisible
<Button
size="md"
variant="solid"
action="primary"
isDisabled={false}
isFocusVisible={false}
>
<ButtonText>Add </ButtonText>
<ButtonIcon as={AddIcon} />
</Button>

API Reference

Import

To use this component in your project, include the following import statement in your file.
import {
Button,
ButtonText,
ButtonIcon,
ButtonSpinner,
ButtonGroup,
} from "@gluestack-ui/themed"

Anatomy

The structure provided below can help you identify and understand a button component's various parts.
export default () => (
<ButtonGroup>
<Button>
<ButtonText />
<ButtonSpinner />
<ButtonIcon />
</Button>
</ButtonGroup>
)

Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

Button

Contains all button related layout style props and actions. It inherits all the properties of React Native's Pressable component.
Prop
Type
Default
Description
isHovered
bool
false
To manually set hover to the button.
isPressed
bool
false
To manually set pressable state to the button.
isFocused
bool
false
To manually set focused state to the button.
isDisabled
bool
false
To manually set disable to the button.
Descendants Styling Props Props to style child components.
Sx Prop
Description
_text
Prop to style ButtonText Component
_icon
Prop to style ButtonIcon Component
_spinner
Prop to style ButtonSpinner Component

ButtonText

Contains all text related layout style props and actions. It inherits all the properties of React Native's Text component.

ButtonGroup

Contains all group related layout style props and actions. It inherits all the properties of React Native's View component.
Prop
Type
Default
Description
flexDirection
'row' | 'column' | 'row-reverse' | 'column-reverse'
'row'
Set the direction of Button group to vertical or horizontal
isDisabled
bool
false
When true, this will disable all the buttons in a ButtonGroup.
isAttached
bool
false
When attached, all buttons will be attached to each other.
reversed
bool
false
To reverse the order of components.
space
string
md
It sets the space between different buttons.
Descendants Styling Props Props to style child components.
Sx Prop
Description
_button
Prop to style Button Component

ButtonSpinner

Contains all spinner related layout style props and actions. It inherits all the properties of React Native's ActivityIndicator component.

ButtonIcon

Contains all Icon related layout style props and actions. It inherits all the properties of React Native's View component.

Features

  • Keyboard support for actions.
  • Support for hover, focus and active states.
  • Option to add your styles or use the default styles.

Accessibility

We have outlined the various features that ensure the Button component is accessible to all users, including those with disabilities. These features help ensure that your application is inclusive and meets accessibility standards.Adheres to the WAI-ARIA design pattern.

Keyboard

  • Tab: Moves focus to the next focusable element.
  • Shift + Tab: Moves focus to the previous focusable element.
  • Enter: Triggers the button's action.

Screen Reader

  • VoiceOver: When the button is focused, the screen reader will announce the button's label and its current state.

Focus Management

  • The onFocus and onBlur props to manage focus states and provide visual cues to users. This is especially important for users who rely on keyboard navigation.

Themed

The themed version of the component is a pre-styled version of the component, which allows you to quickly integrate the component into your project. The component's design and functionality are fully defined, allowing you to focus on the more important aspects of your project. To know more about Themed Library please visit this link.

Props

Button component is created using Pressable component from react-native. It extends all the props supported by React Native Pressable, utility props and the props mentioned below.

Button

Name
Value
Default
action
primary | secondary | positive | negative | default
primary
variant
link | outline | solid
solid
size
xs | sm | md | lg | xl
md
Note: These props are exclusively applicable when utilizing the default configuration of gluestack-ui/config. If you are using a custom theme, these props may not be available.

Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

Button with Loading State

A loading button is a type of button component that provides visual feedback to the user during an action that takes some time to complete. It typically displays an animated loading icon or spinner indicating the action is in progress.
<Button isDisabled={true} bg="$darkBlue600" p="$3">
<ButtonSpinner mr="$1" />
<ButtonText fontWeight="$medium" fontSize="$sm">
Please wait...
</ButtonText>
</Button>

Icon Button

A button with an icon integrates a visual symbol within the button component, enhancing its appearance and providing a recognizable and intuitive representation of its associated action or functionality.
<Button
borderRadius="$full"
size="lg"
p="$3.5"
bg="$indigo600"
borderColor="$indigo600"
>
{/* EditIcon is imported from 'lucide-react-native' */}
<ButtonIcon as={EditIcon} />
</Button>
A button with a link combines the interactive behavior of a button component with the ability to navigate to a specified URL, providing a clickable element for users to access external resources or internal pages.
<Button variant="link">
<ButtonText
fontWeight="$medium"
fontSize="$sm"
color="$textLight900"
$dark-color="$textDark300"
>
Back to top
</ButtonText>
<ButtonIcon
as={ArrowUpIcon}
h="$3"
w="$3"
color="$backgroundLight900"
ml="$1"
$dark-color="$backgroundDark300"
/>
</Button>

Button Group in a Card

A button group within a card component incorporates multiple button components, providing a cohesive and organized interface for selecting various actions or options within the context of the card.
<HStack
p="$12"
alignItems="center"
borderColor="$backgroundLight300"
borderWidth={1}
borderRadius="$lg"
$dark-borderColor="$backgroundDark700"
>
<Box maxWidth="$64" mr="$9">
<Heading mb="$1.5">Was this page helpful?</Heading>
<Text fontSize="$sm">
We use this feedback to improve the quality of our documentation.
</Text>
</Box>
<ButtonGroup space="md">
<Button variant="outline" py="$2.5" action="secondary">
<ButtonText fontSize="$sm" fontWeight="$medium">
No
</ButtonText>
</Button>
<Button
variant="solid"
bg="$success700"
borderColor="$success700"
$hover-bg="$success800"
$active-bg="$success700"
>
<ButtonText fontSize="$sm" fontWeight="$medium">
Yes
</ButtonText>
</Button>
</ButtonGroup>
</HStack>

Button With Icon

The icon component incorporates a button component, combining visual representation with interactive functionality for seamless user interaction.
<Box>
<Button>
<ButtonIcon as={InfoIcon} mr="$2" />
<ButtonText>Left Icon</ButtonText>
</Button>
<Button variant="solid" mt="$2">
<ButtonText>Right Icon</ButtonText>
<ButtonIcon as={AddIcon} ml="$2" />
</Button>
</Box>

Button with Full Width

The button with full width component utilizes a button component, expanding its width to occupy the entire available space, creating a visually prominent and easily accessible interface element.
<Center>
<Box
p="$5"
maxWidth="$96"
borderWidth="$1"
borderColor="$backgroundLight300"
borderRadius="$lg"
$dark-borderColor="$backgroundDark700"
>
<VStack space="xs" pb="$4">
<Heading lineHeight={30}>Set new password</Heading>
<Text fontSize="$sm">
Almost done. Enter your new password and you are all set.
</Text>
</VStack>
<VStack space="xl" py="$2">
<Input>
<InputField py="$2" placeholder="New password" />
</Input>
<Input>
<InputField py="$2" placeholder="Confirm new password" />
</Input>
</VStack>
<VStack space="lg" pt="$4">
<Button size="sm">
<ButtonText>Submit</ButtonText>
</Button>
<Box flexDirection="row">
<Button variant="link" p="$0" size="sm">
{/* ArrowLeftIcon is imported from 'lucide-react-native' */}
<Icon size="md" mr="$1" as={ArrowLeftIcon} />
<ButtonText>Back to login</ButtonText>
</Button>
</Box>
</VStack>
</Box>
</Center>

Custom Button

The custom button component leverages the functionality of a button component while offering additional customization options to tailor its appearance and behavior according to specific design requirements.
<ButtonGroup isAttached>
<Button
variant="outline"
size="xs"
borderColor="$backgroundLight300"
borderRightWidth="$0"
$dark-borderColor="$backgroundDark700"
>
<ButtonText color="$textLight900" $dark-color="$textDark300">
Export
</ButtonText>
</Button>
<Button
variant="outline"
size="xs"
borderColor="$backgroundLight300"
$dark-borderColor="$backgroundDark70"
>
<ButtonIcon
as={ThreeDotsIcon}
color="$textLight900"
$dark-color="$textDark300"
/>
</Button>
</ButtonGroup>

Unstyled

All the components in gluestack-ui are unstyled by default. To customize your UI using the extendedTheme, please refer to this link. The import names of components serve as keys to customize each component.

Spec Doc

Explore the comprehensive details of the Button in this document, including its implementation details, checklist, and potential future additions. Dive into the thought process behind the component and gain insights into its development journey.