Button

Source

Theme Source

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:

Button: This is a single button that can be clicked to trigger an action or event.
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#

Embed not loading? Click here

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 Name	Required	Data Type	Default	Description
`size`	No	PearlTheme.components.Button["sizes"]	`"m"`	Defines the size of the button.
`variant`	No	PearlTheme.components.Button["variants"]	`"filled"`	Specifies the variant of the button.
`isLoading`	No	boolean	`false`	Indicates whether the button is in a loading state.
`isFullWidth`	No	boolean	`false`	Determines whether the button should span the entire width of the parent container.
`loadingText`	No	string	`null`	Specifies the text to display when the button is in a loading state.
`colorScheme`	No	PearlTheme["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.
`spinnerPlacement`	No	"start" \| "end"	`"start"`	Specifies the position of the loading spinner relative to the `loadingText`.
`leftIcon`	No	React.ReactElement	`null`	Defines the icon to display on the left side of the main text.
`rightIcon`	No	React.ReactElement	`null`	Defines 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:

Name	Required	Type	Default	Description
`size`	No	PearlTheme.components.Button["sizes"]	`"m"`	Determines the size of all the children buttons in the group.
`variant`	No	PearlTheme.components.Button["variants"]	`"filled"`	Determines the variant of all the children buttons in the group.
`spacing`	No	PearlTheme["spacing"]	`2`	Sets the spacing between the children buttons in the group.
`isDisabled`	No	boolean	`false`	If true, the button group is disabled.
`isAttached`	No	boolean	`false`	If true, the children buttons are flushed together.
`colorScheme`	No	PearlTheme.palette	`"primary"`	Sets the active color palette of all the children buttons in the group.