Button

Trigger an action or event with customizable size, shape, color, and behavior.

Installation

API Reference

Important Note

This is the documentation for gluestack-ui v2 (beta). For @gluestack-ui/themed (stable) documentation, refer to gluestack-ui v1.

This is an illustration of Button component.

size

variant

action

<Button size="md" variant="solid" action="primary">
  <ButtonText>Hello World!</ButtonText>
</Button>

Installation

CLI

Manual

Run the following command:

npx gluestack-ui add button

Step 1: Install the following dependencies:

npm i @gluestack-ui/button

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

"use client"
import React, { useMemo } from "react"
import { createButton } from "@gluestack-ui/button"
import { Svg } from "react-native-svg"
import type { PressableProps } from "react-native"
import { tva } from "@gluestack-ui/nativewind-utils/tva"
import {
  withStyleContext,
  useStyleContext,
} from "@gluestack-ui/nativewind-utils/withStyleContext"
import { withStyleContextAndStates } from "@gluestack-ui/nativewind-utils/withStyleContextAndStates"
import { cssInterop } from "nativewind"
import { withStates } from "@gluestack-ui/nativewind-utils/withStates"
import {
  ActivityIndicator,
  Pressable,
  Text,
  View,
  Platform,
} from "react-native"
import type { VariantProps } from "@gluestack-ui/nativewind-utils"

const SCOPE = "BUTTON"
const ButtonWrapper = React.forwardRef<
  React.ElementRef<typeof Pressable>,
  PressableProps
>(({ ...props }, ref) => {
  return <Pressable {...props} ref={ref} />
})

type IPrimitiveIcon = React.ComponentPropsWithoutRef<typeof Svg> & {
  height?: number | string
  width?: number | string
  fill?: string
  color?: string
  size?: number | string
  stroke?: string
  as?: React.ElementType
  className?: string
  classNameColor?: string
}

const PrimitiveIcon = React.forwardRef<
  React.ElementRef<typeof Svg>,
  IPrimitiveIcon
>(
  (
    {
      height,
      width,
      fill,
      color,
      classNameColor,
      size,
      stroke,
      as: AsComp,
      ...props
    },
    ref
  ) => {
    color = color ?? classNameColor
    const sizeProps = useMemo(() => {
      if (size) return { size }
      if (height && width) return { height, width }
      if (height) return { height }
      if (width) return { width }
      return {}
    }, [size, height, width])

    let colorProps = {}
    if (fill) {
      colorProps = { ...colorProps, fill: fill }
    }
    if (stroke !== "currentColor") {
      colorProps = { ...colorProps, stroke: stroke }
    } else if (stroke === "currentColor" && color !== undefined) {
      colorProps = { ...colorProps, stroke: color }
    }

    if (AsComp) {
      return <AsComp ref={ref} {...props} {...sizeProps} {...colorProps} />
    }
    return (
      <Svg ref={ref} height={height} width={width} {...colorProps} {...props} />
    )
  }
)

const Root =
  Platform.OS === "web"
    ? withStyleContext(ButtonWrapper, SCOPE)
    : withStyleContextAndStates(ButtonWrapper, SCOPE)

const UIButton = createButton({
  Root: Root,
  Text,
  Group: View,
  Spinner: ActivityIndicator,
  Icon: withStates(PrimitiveIcon),
})

cssInterop(Root, { className: "style" })
cssInterop(UIButton.Text, { className: "style" })
cssInterop(UIButton.Group, { className: "style" })
cssInterop(UIButton.Spinner, {
  className: { target: "style", nativeStyleToProp: { color: true } },
})
//@ts-ignore
cssInterop(PrimitiveIcon, {
  className: {
    target: "style",
    nativeStyleToProp: {
      height: true,
      width: true,
      //@ts-ignore
      fill: true,
      color: "classNameColor",
      stroke: true,
    },
  },
})

const buttonStyle = tva({
  base: "group/button rounded bg-primary-500 flex-row items-center justify-center data-[focus-visible=true]:web:outline-none data-[focus-visible=true]:web:ring-2 data-[disabled=true]:opacity-40",
  variants: {
    action: {
      primary:
        "bg-primary-500 data-[hover=true]:bg-primary-600 data-[active=true]:bg-primary-700 border-primary-300 data-[hover=true]:border-primary-400 data-[active=true]:border-primary-500 data-[focus-visible=true]:web:ring-indicator-info",
      secondary:
        "bg-secondary-500 border-secondary-300 data-[hover=true]:bg-secondary-600 data-[hover=true]:border-secondary-400 data-[active=true]:bg-secondary-700 data-[active=true]:border-secondary-500 data-[focus-visible=true]:web:ring-indicator-info",
      positive:
        "bg-success-500 border-success-300 data-[hover=true]:bg-success-600 data-[hover=true]:border-success-400 data-[active=true]:bg-success-700 data-[active=true]:border-success-500 data-[focus-visible=true]:web:ring-indicator-info",
      negative:
        "bg-error-500 border-error-300 data-[hover=true]:bg-error-600 data-[hover=true]:border-error-400 data-[active=true]:bg-error-700 data-[active=true]:border-error-500 data-[focus-visible=true]:web:ring-indicator-info",
      default:
        "bg-transparent data-[hover=true]:bg-background-50 data-[active=true]:bg-transparent",
    },
    variant: {
      link: "px-0",
      outline:
        "bg-transparent border data-[hover=true]:bg-background-50 data-[active=true]:bg-transparent",
      solid: "",
    },

    size: {
      xs: "px-3.5 h-8",
      sm: "px-4 h-9",
      md: "px-5 h-10",
      lg: "px-6 h-11",
      xl: "px-7 h-12",
    },
  },
  compoundVariants: [
    {
      action: "primary",
      variant: "link",
      class:
        "px-0 bg-transparent data-[hover=true]:bg-transparent data-[active=true]:bg-transparent",
    },
    {
      action: "secondary",
      variant: "link",
      class:
        "px-0 bg-transparent data-[hover=true]:bg-transparent data-[active=true]:bg-transparent",
    },
    {
      action: "positive",
      variant: "link",
      class:
        "px-0 bg-transparent data-[hover=true]:bg-transparent data-[active=true]:bg-transparent",
    },
    {
      action: "negative",
      variant: "link",
      class:
        "px-0 bg-transparent data-[hover=true]:bg-transparent data-[active=true]:bg-transparent",
    },
    {
      action: "primary",
      variant: "outline",
      class:
        "bg-transparent data-[hover=true]:bg-background-50 data-[active=true]:bg-transparent",
    },
    {
      action: "secondary",
      variant: "outline",
      class:
        "bg-transparent data-[hover=true]:bg-background-50 data-[active=true]:bg-transparent",
    },
    {
      action: "positive",
      variant: "outline",
      class:
        "bg-transparent data-[hover=true]:bg-background-50 data-[active=true]:bg-transparent",
    },
    {
      action: "negative",
      variant: "outline",
      class:
        "bg-transparent data-[hover=true]:bg-background-50 data-[active=true]:bg-transparent",
    },
  ],
})

const buttonTextStyle = tva({
  base: "text-typography-0 font-semibold web:select-none",
  parentVariants: {
    action: {
      primary:
        "text-primary-600 data-[hover=true]:text-primary-600 data-[active=true]:text-primary-700",
      secondary:
        "text-secondary-600 data-[hover=true]:text-secondary-600 data-[active=true]:text-secondary-700",
      positive:
        "text-success-600 data-[hover=true]:text-success-600 data-[active=true]:text-success-700",
      negative:
        "text-error-600 data-[hover=true]:text-error-600 data-[active=true]:text-error-700",
    },
    variant: {
      link: "data-[hover=true]:underline data-[active=true]:underline",
      outline: "",
      solid:
        "text-typography-0 data-[hover=true]:text-typography-0 data-[active=true]:text-typography-0",
    },
    size: {
      xs: "text-xs",
      sm: "text-sm",
      md: "text-base",
      lg: "text-lg",
      xl: "text-xl",
    },
  },
  parentCompoundVariants: [
    {
      variant: "solid",
      action: "primary",
      class:
        "text-typography-0 data-[hover=true]:text-typography-0 data-[active=true]:text-typography-0",
    },
    {
      variant: "solid",
      action: "secondary",
      class:
        "text-typography-0 data-[hover=true]:text-typography-0 data-[active=true]:text-typography-0",
    },
    {
      variant: "solid",
      action: "positive",
      class:
        "text-typography-0 data-[hover=true]:text-typography-0 data-[active=true]:text-typography-0",
    },
    {
      variant: "solid",
      action: "negative",
      class:
        "text-typography-0 data-[hover=true]:text-typography-0 data-[active=true]:text-typography-0",
    },
    {
      variant: "outline",
      action: "primary",
      class:
        "text-primary-500 data-[hover=true]:text-primary-500 data-[active=true]:text-primary-500",
    },
    {
      variant: "outline",
      action: "secondary",
      class:
        "text-primary-500 data-[hover=true]:text-primary-500 data-[active=true]:text-primary-500",
    },
    {
      variant: "outline",
      action: "positive",
      class:
        "text-primary-500 data-[hover=true]:text-primary-500 data-[active=true]:text-primary-500",
    },
    {
      variant: "outline",
      action: "negative",
      class:
        "text-primary-500 data-[hover=true]:text-primary-500 data-[active=true]:text-primary-500",
    },
  ],
})

const buttonIconStyle = tva({
  base: "fill-none",
  parentVariants: {
    variant: {
      link: "data-[hover=true]:underline data-[active=true]:underline",
      outline: "",
      solid:
        "text-typography-0 data-[hover=true]:text-typography-0 data-[active=true]:text-typography-0",
    },
    size: {
      xs: "h-3.5 w-3.5",
      sm: "h-4 w-4",
      md: "h-[18px] w-[18px]",
      lg: "h-[18px] w-[18px]",
      xl: "h-5 w-5",
    },
    action: {
      primary:
        "text-primary-600 data-[hover=true]:text-primary-600 data-[active=true]:text-primary-700",
      secondary:
        "text-secondary-600 data-[hover=true]:text-secondary-600 data-[active=true]:text-secondary-700",
      positive:
        "text-success-600 data-[hover=true]:text-success-600 data-[active=true]:text-success-700",

      negative:
        "text-error-600 data-[hover=true]:text-error-600 data-[active=true]:text-error-700",
    },
  },
  parentCompoundVariants: [
    {
      variant: "solid",
      action: "primary",
      class:
        "text-typography-0 data-[hover=true]:text-typography-0 data-[active=true]:text-typography-0",
    },
    {
      variant: "solid",
      action: "secondary",
      class:
        "text-typography-0 data-[hover=true]:text-typography-0 data-[active=true]:text-typography-0",
    },
    {
      variant: "solid",
      action: "positive",
      class:
        "text-typography-0 data-[hover=true]:text-typography-0 data-[active=true]:text-typography-0",
    },
    {
      variant: "solid",
      action: "negative",
      class:
        "text-typography-0 data-[hover=true]:text-typography-0 data-[active=true]:text-typography-0",
    },
  ],
})

const buttonGroupStyle = tva({
  base: "",
  variants: {
    space: {
      xs: "gap-1",
      sm: "gap-2",
      md: "gap-3",
      lg: "gap-4",
      xl: "gap-5",
      "2xl": "gap-6",
      "3xl": "gap-7",
      "4xl": "gap-8",
    },
    isAttached: {
      true: "gap-0",
    },
  },
})

type IButtonProps = Omit<
  React.ComponentPropsWithoutRef<typeof UIButton>,
  "context"
> &
  VariantProps<typeof buttonStyle> & { className?: string }

const Button = React.forwardRef<
  React.ElementRef<typeof UIButton>,
  IButtonProps
>(
  (
    { className, variant = "solid", size = "md", action = "primary", ...props },
    ref
  ) => {
    return (
      <UIButton
        ref={ref}
        {...props}
        className={buttonStyle({ variant, size, action, class: className })}
        context={{ variant, size, action }}
      />
    )
  }
)

type IButtonTextProps = React.ComponentPropsWithoutRef<typeof UIButton.Text> &
  VariantProps<typeof buttonTextStyle> & { className?: string }

const ButtonText = React.forwardRef<
  React.ElementRef<typeof UIButton.Text>,
  IButtonTextProps
>(({ className, variant, size, action, ...props }, ref) => {
  const {
    variant: parentVariant,
    size: parentSize,
    action: parentAction,
  } = useStyleContext(SCOPE)

  return (
    <UIButton.Text
      ref={ref}
      {...props}
      className={buttonTextStyle({
        parentVariants: {
          variant: parentVariant,
          size: parentSize,
          action: parentAction,
        },
        variant,
        size,
        action,
        class: className,
      })}
    />
  )
})

const ButtonSpinner = UIButton.Spinner

type IButtonIcon = React.ComponentPropsWithoutRef<typeof UIButton.Icon> &
  VariantProps<typeof buttonIconStyle> & {
    className?: string | undefined
    as?: React.ElementType
  }

const ButtonIcon = React.forwardRef<
  React.ElementRef<typeof UIButton.Icon>,
  IButtonIcon
>(({ className, size, ...props }, ref) => {
  const {
    variant: parentVariant,
    size: parentSize,
    action: parentAction,
  } = useStyleContext(SCOPE)

  if (typeof size === "number") {
    return (
      <UIButton.Icon
        ref={ref}
        {...props}
        className={buttonIconStyle({ class: className })}
        size={size}
      />
    )
  } else if (
    (props.height !== undefined || props.width !== undefined) &&
    size === undefined
  ) {
    return (
      <UIButton.Icon
        ref={ref}
        {...props}
        className={buttonIconStyle({ class: className })}
      />
    )
  }
  return (
    <UIButton.Icon
      {...props}
      className={buttonIconStyle({
        parentVariants: {
          size: parentSize,
          variant: parentVariant,
          action: parentAction,
        },
        size,
        class: className,
      })}
      ref={ref}
    />
  )
})

type IButtonGroupProps = React.ComponentPropsWithoutRef<typeof UIButton.Group> &
  VariantProps<typeof buttonGroupStyle>

const ButtonGroup = React.forwardRef<
  React.ElementRef<typeof UIButton.Group>,
  IButtonGroupProps
>(({ className, space = "md", isAttached = false, ...props }, ref) => {
  return (
    <UIButton.Group
      className={buttonGroupStyle({ class: className, space, isAttached })}
      {...props}
      ref={ref}
    />
  )
})

Button.displayName = "Button"
ButtonText.displayName = "ButtonText"
ButtonSpinner.displayName = "ButtonSpinner"
ButtonIcon.displayName = "ButtonIcon"
ButtonGroup.displayName = "ButtonGroup"

export { Button, ButtonText, ButtonSpinner, ButtonIcon, ButtonGroup }

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.

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.

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

Important Note

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.

Data Attributes Table

Component receives states as props as boolean values, which are applied as data-* attributes. These attributes are then used to style the component via classNames, enabling state-based styling.

State	Data Attribute	Values
hover	data-hover	true \| false
active	data-active	true \| false
disabled	data-disabled	true \| false
focusVisible	data-focus-visible	true \| false

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 className="p-3">
  {/* colors is imported from tailwindcss/colors */}
  <ButtonSpinner color={colors.gray[400]} />
  <ButtonText className="font-medium text-sm ml-2">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 size="lg" className="rounded-full p-3.5">
  {/* EditIcon is imported from 'lucide-react-native' */}
  <ButtonIcon as={EditIcon} />
</Button>

Link 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 className="font-medium text-sm text-typography-900">
    Back to top
  </ButtonText>
  <ButtonIcon as={ArrowUpIcon} className="h-3 w-3 text-background-900 ml-1" />
</Button>

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} className="mr-2" />
    <ButtonText>Left Icon</ButtonText>
  </Button>
  <Button variant="solid" className="mt-2">
    <ButtonText>Right Icon</ButtonText>
    <ButtonIcon as={AddIcon} className="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 className="p-5 max-w-96 border border-background-300 rounded-lg">
    <VStack className="pb-4" space="xs">
      <Heading className="leading-[30px]">Set new password</Heading>
      <Text className="text-sm">
        Almost done. Enter your new password and you are all set.
      </Text>
    </VStack>
    <VStack space="xl" className="py-2">
      <Input>
        <InputField className="py-2" placeholder="New password" />
      </Input>
      <Input>
        <InputField className="py-2" placeholder="Confirm new password" />
      </Input>
    </VStack>
    <VStack space="lg" className="pt-4">
      <Button size="sm">
        <ButtonText>Submit</ButtonText>
      </Button>
      <Box className="flex flex-row">
        <Button variant="link" size="sm" className="p-0">
          {/* ArrowLeftIcon is imported from 'lucide-react-native' */}
          <ButtonIcon className="mr-1" size="md" as={ArrowLeftIcon} />
          <ButtonText>Back to login</ButtonText>
        </Button>
      </Box>
    </VStack>
  </Box>
</Center>

Button

Installation

Run the following command:

Step 1: Install the following dependencies:

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

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

API Reference

Component Props

Button

ButtonText

ButtonGroup

ButtonSpinner

ButtonIcon

Features

Accessibility

Keyboard

Screen Reader

Focus Management

Props

Button

Data Attributes Table

Examples

Button with Loading State

Icon Button

Link Button

Button With Icon

Button with Full Width