Edit page

Button

Buttons allow users to take actions.

Basic Usage

To implement the Button component, you need to import it first:

import { Button } from '@react-ui-org/react-ui';

And use it:

See API for all available options.

General Guidelines

  • Use short yet comprehensible labels to make buttons fit small screens.

  • Since buttons are there to take actions, use a verb to make it obvious what your buttons do.

  • Don't overwhelm your UI with too many high-emphasis actions. There should always be one but chances are that having more of them is not necessary.

Priorities

There are three visual priorities of buttons to choose from, from highest to lowest:

  1. filled
  2. outline
  3. flat

All priorities come in supported component colors.

To complete the list, there is also a link priority which is reserved for special cases.

Filled

The default, high-emphasis priority should be used for primary actions of your app. Use it sparingly but remember there should always be one on a screen.

Default, unconfigured button comes in medium size, filled visual priority, and primary color variant.

Outline

Medium-emphasis buttons. They are designed to contain actions that are important but not primary in your app.

Flat

Flat buttons are designed for less pronounced actions to help maintain focus on the content.

Link button is more a workaround than a priority level. Use it for what needs to appear as navigation to users but where a button must be used due to technical reasons. Under normal circumstances, you should always use a link HTML element <a href="…"> for navigation.

⚠️ Avoid using link buttons for actions, choose flat or outline priority instead. This is because users expect navigation to happen when clicking on something what looks like a link.

Sizes

Aside from the default (medium) size, two additional sizes are available: small and large.

Block buttons span the full width of a parent:

Buttons with Icons

To improve clarity or to draw attention to the action, icons can be added before or after the button's label.

πŸ‘‰ Please note there are no icons pre-packed in React UI. Visit Icons to see how to include them.

Icon Buttons

For clear and simple actions, buttons can visually consist just of an icon. Label remains mandatory to keep the button accessible. Icon buttons can optionally enhance on desktop and display the label once there is enough room for it.

Buttons with Badges

A Badge can be added to buttons to provide additional information or to draw user's attention.

Icon Buttons with a Badge

Badges play nicely with icon buttons, too:

States

Disabled State

Disabled state makes the action unavailable.

Loading State

When an action triggers an asynchronous process on background, the button's loading state can be indicated by showing a loading icon. Buttons in loading state are automatically made disabled to prevent unwanted interaction.

πŸ‘‰ Visit the CSS Helpers section to see how the icon animation is made.

API

In addition to the options below, you can add any custom attributes that do not interfere with the API, and they will be passed to the button HTML element. This is useful mainly to improve component's accessibility.

Prop nameTypeDefaultRequiredDescription
afterLabelnodenullfalse

Element to be displayed after label, eg. an icon.

beforeLabelnodenullfalse

Element to be displayed before label, eg. an icon.

blockboolfalsefalse

If true, the button will span the full width of its parent.

clickHandlerfuncnullfalse

Function to call when the button is clicked.

color'primary' β”‚ 'secondary' β”‚ 'success' β”‚ 'warning' β”‚ 'danger' β”‚ 'help' β”‚ 'info' β”‚ 'note' β”‚ 'light' β”‚ 'dark''primary'false

Color variant to clarify importance and meaning of the button.

disabledboolfalsefalse

If true, the button will be disabled.

endCornernodenullfalse

Element to be displayed in the top right corner.

forwardedRefFunction β”‚ { "current": "any" }undefinedfalse

Reference forwarded to the button element.

groupedboolfalsefalse

Treat button differently when it’s inside ButtonGroup. Do not set manually!

idstringundefinedfalse

ID of the root HTML element.

labelstringβ€”true

Button label.

labelVisibility'all' β”‚ 'desktop' β”‚ 'none''all'false

Defines when the button label should be visible.

loadingIconnodenullfalse

Element to be displayed as a loading icon. When defined, it implies the button is in the loading state.

priority'filled' β”‚ 'outline' β”‚ 'flat' β”‚ 'link''filled'false

Visual priority to highlight or suppress the button.

size'small' β”‚ 'medium' β”‚ 'large''medium'false

Size of the button.

startCornernodenullfalse

Element to be displayed in the top left corner.

type'button' β”‚ 'submit''button'false

Set the HTML type attribute of the button element.

Theming

Common Theming Options

The following theme options are common to all priorities and color variants except the link priority (see below for more):

Custom PropertyDescription
--rui-Button__font-weightFont weight
--rui-Button__text-transformText transform, e.g. uppercase or small-caps
--rui-Button__letter-spacingSpacing between letters
--rui-Button__border-widthBorder width
--rui-Button__border-radiusCorner radius

Theming Priorities and Color Variants

It's possible to adjust the theme for specific priority, color variant, and state. Naming convention looks as follows:

--rui-Button--<PRIORITY>--<COLOR>--<INTERACTION STATE>__<PROPERTY>

Where:

  • <PRIORITY> is one of filled, outline, or flat (see Priorities and API),
  • <COLOR> is one of supported component colors (see color variants of each priority and API),
  • <INTERACTION STATE> is one of default, hover, active, or disabled (the last one being optional),
  • <PROPERTY> is one of:
    • color, border-color, background, or box-shadow for the filled priority,
    • color, border-color, or background for the outline priority,
    • color or background for the flat priority.

The link priority is treated a bit different because from the theming point of view it doesn't share anything with other priorities. However, it shares everything with common links and thus can be adjusted by editing corresponding design tokens:

Custom PropertyDescription
--rui-link-colorText color
--rui-link-decorationText decoration, e.g. underline
--rui-link-hover-colorText color on hover
--rui-link-hover-decorationText decoration on hover

Theming Sizes

Available sizes can be adjusted as follows:

--rui-Button--<SIZE>__<PROPERTY>

Where:

  • <SIZE> is one of small, medium, or large (see Sizes and API)
  • <PROPERTY> is one of height, padding-x, or font-size

Example Theme

Theming Disabled State

The disabled state offers a bit more of design flexibility compared to other interaction states. Firstly, there are a few common options for this state:

Custom PropertyDescription
--rui-Button--disabled__opacityOpacity of disabled buttons
--rui-Button--disabled__cursorCursor to show on hovering disabled buttons

Secondly, it can be further adjusted using priority and color variant specific options for the disabled state:

--rui-Button--<PRIORITY>--<COLOR>--disabled__<PROPERTY>

Undefined theming options are inherited from the default interaction state.

Example: