Skip to main content

Button

The Button component in Pearl UI is a versatile and customizable element used to trigger various actions or events within your application. These actions could range from submitting a form, opening a dialog, canceling an action, or performing a delete operation. By default, the Button component renders the Pressable component.

Import#

Pearl UI provides two button-related components for different use cases:

  1. Button: This is a single button that can be clicked to trigger an action or event.
  2. ButtonGroup: This is a container for multiple Button components. It manages the state of its child buttons and allows you to apply shared styles to them.
import { Button, ButtonGroup } from "pearl-ui";

Usage#

<Button>I am a button</Button>

Button sizes#

The size prop allows you to adjust the size of the button. The value for this prop should be one of the keys available in PearlTheme.components.Button["sizes"], which are "xs", "s", "m", and "l" in the default component configuration.

<Button size="xs">Tiny Button</Button>
<Button size="s">Small Button</Button>
<Button size="m">Regular Button</Button>
<Button size="l">Large Button</Button>

Button variants#

The variant prop allows you to change the visual style of the button. The value for this prop should be one of the keys available in PearlTheme.components.Button["variants"], which are "solid", "outline", and "ghost" in the default component configuration.

<Button variant="solid">Solid Button</Button>
<Button variant="outline">Outline Button</Button>
<Button variant="ghost">Ghost Button</Button>

Button with Icon#

The Button component supports the addition of icons on either side of the button text. This can be achieved using the leftIcon and rightIcon props for left and right icons respectively.

info

The leftIcon and rightIcon prop values should be React elements, NOT strings.

import { Icon } from "pearl-ui";
<Button  leftIcon={<Icon iconFamily="AntDesign" iconName="heart" />}>  Button with left icon</Button>
<Button  variant="outline"  rightIcon={<Icon iconFamily="AntDesign" iconName="cloudupload" />}>  Button with right icon</Button>

Loading State of Button#

The isLoading prop can be used to display a loading state on the button. By default, Button will show a spinner and maintain the button's width. The loadingText prop can be used to display a spinner and the loading text. When a loadingText is present, the placement of the spinner element can be adjusted to either start or end using the spinnerPlacement prop. It is start by default.

<Button isLoading>Basic loading button</Button>
<Button isLoading loadingText="Loading">Button with loading text</Button>
<Button  isLoading  loadingText="Loading"  spinnerPlacement="end">  Button with spinner at the end</Button>

Customizing Button Color Scheme#

The colorScheme prop allows you to change the color palette of the button. This is a powerful feature as it changes all the use color values in a palette through a single prop. The value for this prop should be one of the keys available in PearlTheme.palette that contain a palette of colors represented as an object, which are "primary", "secondary", "neutral", etc in the default Pearl theme.

<Button colorScheme="primary">Primary Button</Button>
<Button colorScheme="secondary">Secondary Button</Button>

Grouping Buttons#

You can use the Stack or ButtonGroup component to group multiple buttons. When you use the ButtonGroup component, it allows you to:

  • Set the size, variant, and colorScheme of all buttons within it.
  • Add spacing between the buttons.
  • Flush the buttons together by removing the border radius of their children as needed.
<ButtonGroup variant="outline" spacing="6">  <Button>Save</Button>  <Button colorScheme="danger">Cancel</Button></ButtonGroup>

To flush the buttons, pass the isAttached prop.

<ButtonGroup size="sm" isAttached variant="outline">  <Button>Save</Button>  <Button    colorScheme="danger"    rightIcon={<Icon iconFamily="Ionicons" iconName="md-lock-closed" />}  >    Lock  </Button></ButtonGroup>

Overriding Styles#

The Button component supports a variety of style props which can be used to override the pre-defined variant style in the theme. Manual style props passed into the component have a higher precedence than the default component configuration.

// passing style prop m="8" overrides the default component config value of m="1"// passing style prop boxShadow="xl" adds a box shadow to the button<Button m="8" boxShadow="3xl" variant="outline" />

Example#

Accessibility#

  • Button has the role of button.
  • Button has the default accessibility label set as the text value passed into it. When the button is in a loading state, the accessibility label is set as "Loading". A custom label can be specified using the accessibilityLabel prop.
  • When the Button is disabled or loading, it is reflected as disabled and busy respectively in screen readers.
  • Similar to Pressable, Button expects an actionDescription prop to specify the intented outcome of interacting with the component eg. 'Closes modal', 'Go to the homepage', etc.

Button Component Properties#

Supported Style Properties#

The Button component is a composition of the Pressable component. Therefore, all properties related to the Pressable component can be passed to the Button component, in addition to the properties listed below.

Additional Properties#

Property NameRequiredData TypeDefaultDescription
sizeNoPearlTheme.components.Button["sizes"]"m"Defines the size of the button.
variantNoPearlTheme.components.Button["variants"]"filled"Specifies the variant of the button.
isLoadingNobooleanfalseIndicates whether the button is in a loading state.
isFullWidthNobooleanfalseDetermines whether the button should span the entire width of the parent container.
loadingTextNostringnullSpecifies the text to display when the button is in a loading state.
colorSchemeNoPearlTheme["palette"]"primary"Defines the active color palette of the button. The expected value is the key of a palette object eg primary, secondary, neutral, etc.
spinnerPlacementNo"start" | "end""start"Specifies the position of the loading spinner relative to the loadingText.
leftIconNoReact.ReactElementnullDefines the icon to display on the left side of the main text.
rightIconNoReact.ReactElementnullDefines the icon to display on the right side of the main text.

ButtonGroup Component Properties#

Supported Style Properties#

The ButtonGroup component is composed of the Stack component, which means you can pass all Stack properties to it.

Additional Properties#

Here is a list of additional properties that the ButtonGroup component supports:

NameRequiredTypeDefaultDescription
sizeNoPearlTheme.components.Button["sizes"]"m"Determines the size of all the children buttons in the group.
variantNoPearlTheme.components.Button["variants"]"filled"Determines the variant of all the children buttons in the group.
spacingNoPearlTheme["spacing"]2Sets the spacing between the children buttons in the group.
isDisabledNobooleanfalseIf true, the button group is disabled.
isAttachedNobooleanfalseIf true, the children buttons are flushed together.
colorSchemeNoPearlTheme.palette"primary"Sets the active color palette of all the children buttons in the group.