Edit page


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.


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.


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.


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


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


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 a breakpoint of your choice and display label once you know there is enough room for it.

📐 Try resizing your browser to see how label visibility changes.

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:


Disabled State

Disabled state makes the action unavailable.

Feedback State

When user's action triggers an asynchronous process on background, the button's feedback state (not to be mistaken with feedback colors) can be indicated by showing an icon. The icon replaces button's label while retaining original dimensions of the button. Buttons in feedback state are automatically disabled to prevent unwanted interaction.

Filled buttons in feedback state:

Outline buttons in feedback state:

Flat buttons in feedback state:

👉 Visit the CSS Helpers section to see how the icon animation is made.

Forwarding HTML Attributes

In addition to the options below in the component's API section, you can specify React synthetic events or any HTML attribute you like. All attributes that don't interfere with the API are forwarded to the native HTML <button>. This enables making the component interactive and helps to improve its accessibility.

👉 Refer to the MDN reference for the full list of supported attributes of the button element.

Forwarding ref

If you provide ref, it is forwarded to the native HTML <button> element.


Prop nameTypeDefaultRequiredDescription

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


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


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

Ignored if the component is rendered within ButtonGroup component as the value is inherited in such case.

color'primary' │ 'secondary' │ 'selected' │ 'success' │ 'warning' │ 'danger' │ 'help' │ 'info' │ 'note' │ 'light' │ 'dark''primary'false

Color variant to clarify importance and meaning of the button.


If true, the button will be disabled.

Ignored if the component is rendered within ButtonGroup component as the value is inherited in such case.


Element to be displayed in the top right corner.


Element to be displayed as a feedback icon on top of button label. When defined, it implies the button is in feedback state.


ID of the root HTML element.

Also serves as base for ids of nested elements:

  • <ID>__labelText

Button label.

labelVisibility'xs' │ 'sm' │ 'md' │ 'lg' │ 'xl' │ 'x2l' │ 'x3l' │ 'none''xs'false

Defines minimum breakpoint from which the button label will be visible.

priority'filled' │ 'outline' │ 'flat''filled'false

Visual priority to highlight or suppress the button.

Ignored if the component is rendered within ButtonGroup component as the value is inherited in such case.

size'small' │ 'medium' │ 'large''medium'false

Size of the button.

Ignored if the component is rendered within ButtonGroup component as the value is inherited in such case.


Element to be displayed in the top left corner.

type'button' │ 'submit''button'false

Set the HTML type attribute of the button element.


Common Theming Options

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:



  • <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.

Theming Sizes

Available sizes can be adjusted as follows:



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

👉 Button sizes are linked to box field sizes sizes so they align nicely when placed in row.

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:


Undefined theming options are inherited from the default interaction state.


Theming Feedback State

Similarly to disabled state, opacity and cursor can be set for buttons in feedback state.

Custom PropertyDescription
--rui-Button--feedback__opacityOpacity of buttons in feedback state
--rui-Button--feedback__cursorCursor to show on hovering buttons in feedback state