Button

A button component is a graphical user interface element that enables users to act by clicking or tapping. It can be customized in size, shape, color, and behavior to fit the design of the application or website.
Installation
API Reference
Spec Doc
This is an illustration of Button component.
size
variant
action
<Button size="md" variant="solid" action="primary">
<ButtonText>Hello World!</ButtonText>
</Button>

Installation

Step 1: Install the following dependencies:

npm i @gluestack-ui/button

Step 2: Copy and paste the following code into your project.

import React from "react"
import { createButton } from "@gluestack-ui/button"
import {
tva,
withStyleContextAndStates,
useStyleContext,
withStyleContext,
} from "@gluestack-ui/nativewind-utils"
import {
ActivityIndicator,
Pressable,
Text,
View,
Platform,
} from "react-native"
import { cssInterop } from "nativewind"
const UIButton = createButton({
// @ts-ignore
Root:
Platform.OS === "web"
? withStyleContext(Pressable)
: withStyleContextAndStates(Pressable),
Text,
Group: View,
Spinner: ActivityIndicator,
Icon: View,
})
cssInterop(UIButton, { className: "style" })
cssInterop(UIButton.Text, { className: "style" })
cssInterop(UIButton.Group, { className: "style" })
cssInterop(UIButton.Spinner, { className: "style" })
cssInterop(UIButton.Icon, { className: "style" })
const buttonStyle = tva({
base: "group/button rounded-lg bg-primary-500 flex-row items-center justify-center data-[focus=true]:outline-none data-[focus-visible=true]:ring-2 ",
variants: {
action: {
primary:
"bg-primary-500 hover:bg-primary-600 active:bg-primary-700 border-primary-300 hover:border-primary-400 active:border-primary-500 data-[focus-visible=true]:ring-primary-500",
secondary:
"bg-secondary-500 border-secondary-300 hover:bg-secondary-600 hover:border-secondary-400 active:bg-secondary-700 active:border-secondary-500 data-[focus-visible=true]:ring-secondary-500",
positive:
"bg-success-500 border-success-300 hover:bg-success-600 hover:border-success-400 active:bg-success-700 active:border-success-500 data-[focus-visible=true]:ring-success-500",
negative:
"bg-error-500 border-error-300 hover:bg-error-600 hover:border-error-400 active:bg-error-700 active:border-error-500 data-[focus-visible=true]:ring-error-500",
default: "bg-transparent hover:bg-background-50 active:bg-transparent",
},
variant: {
link: "px-0",
outline:
"bg-transparent border hover:bg-background-50 active:bg-transparent",
},
size: {
sm: "px-4 h-9",
md: "px-5 h-10",
lg: "px-6 h-11",
},
},
compoundVariants: [
{
action: "primary",
variant: "link",
class: "px-0 bg-transparent hover:bg-transparent active:bg-transparent",
},
{
action: "secondary",
variant: "link",
class: "px-0 bg-transparent hover:bg-transparent active:bg-transparent",
},
{
action: "positive",
variant: "link",
class: "px-0 bg-transparent hover:bg-transparent active:bg-transparent",
},
{
action: "negative",
variant: "link",
class: "px-0 bg-transparent hover:bg-transparent active:bg-transparent",
},
{
action: "primary",
variant: "outline",
class: "bg-transparent hover:bg-background-50 active:bg-transparent",
},
{
action: "secondary",
variant: "outline",
class: "bg-transparent hover:bg-background-50 active:bg-transparent",
},
{
action: "positive",
variant: "outline",
class: "bg-transparent hover:bg-background-50 active:bg-transparent",
},
{
action: "negative",
variant: "outline",
class: "bg-transparent hover:bg-background-50 active:bg-transparent",
},
],
})
const buttonTextStyle = tva({
base: "text-typography-0 font-semibold web:select-none",
parentVariants: {
action: {
primary:
"text-primary-600 group-hover/button:text-primary-600 group-active/button:text-primary-700",
secondary:
"text-secondary-600 group-hover/button:text-secondary-600 group-active/button:text-secondary-700",
positive:
"text-success-600 group-hover/button:text-success-600 group-active/button:text-success-700",
negative:
"text-error-600 group-hover/button:text-error-600 group-active/button:text-error-700",
},
variant: {
link: "group-hover/button:underline group-active/button:underline",
outline: "",
solid:
"text-typography-0 group-hover/button:text-typography-0 group-active/button:text-typography-0",
},
size: {
sm: "text-sm",
md: "text-base",
lg: "text-lg",
},
},
parentCompoundVariants: [
{
variant: "solid",
action: "primary",
class:
"text-typography-0 group-hover/button:text-typography-0 group-active/button:text-typography-0",
},
{
variant: "solid",
action: "secondary",
class:
"text-typography-0 group-hover/button:text-typography-0 group-active/button:text-typography-0",
},
{
variant: "solid",
action: "positive",
class:
"text-typography-0 group-hover/button:text-typography-0 group-active/button:text-typography-0",
},
{
variant: "solid",
action: "negative",
class:
"text-typography-0 group-hover/button:text-typography-0 group-active/button:text-typography-0",
},
],
})
const Button = React.forwardRef(
(
{
className,
variant = "solid",
size = "md",
action = "primary",
...props
}: any,
ref
) => {
return (
<UIButton
ref={ref}
className={buttonStyle({ variant, size, action, class: className })}
context={{ variant, size, action }}
/>
)
}
)
const ButtonText = React.forwardRef(
({ className, variant, size, action, ...props }: any, ref) => {
const {
variant: parentVariant,
size: parentSize,
action: parentAction,
} = useStyleContext()
return (
<UIButton.Text
ref={ref}
{...props}
className={buttonTextStyle({
parentVariants: {
variant: parentVariant,
size: parentSize,
action: parentAction,
},
variant,
size,
action,
class: className,
})}
/>
)
}
)
const ButtonSpinner = UIButton.Spinner
const ButtonIcon = ({ className, as: AsComp, ...props }: any) => {
if (AsComp) {
return <AsComp className={className} {...props} />
}
return <UIButton.Icon className={className} {...props} />
}
Button.displayName = "Button"
ButtonText.displayName = "ButtonText"
export { Button, ButtonText, ButtonSpinner, ButtonIcon }

Step 3: Update the import paths to match your project setup.

API Reference

To use this component in your project, include the following import statement in your file.
import {
Button,
ButtonText,
ButtonSpinner,
ButtonIcon,
ButtonGroup,
} from "@/components/ui/Button"
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.

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.

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.
Edit this page on GitHub