Button

Maintainer:
amje
GitHub
view
size
pin
selected
disabled
loading
startIcon
endIcon
onlyIcon
width
children
import {Button} from '@gravity-ui/uikit';

Buttons act as a trigger for certain actions. While this is their main purpose, in some very rare cases, they can be used as links to navigate to other pages.

Appearance

There are four Button types in terms of appearance: basic, outlined, flat, and contrast. The Button appearance is determined by the view property.

Basic

action: The most distinctive type of Button. It is used for the primary action on a screen that requires the most attention. We recommend using only one such button per page.

normal: Default type of Button designed for secondary actions or to maintain the importance of an action without drawing too much attention to it.

raised: Placed above the content as a floating element, usually with a fixed location.

<Button view="action" size="l">Action</Button>
<Button view="normal" size="l">Normal</Button>
<Button view="raised" size="l">Raised</Button>

Outlined

outlined: Used for secondary actions that require less attention. It can be used with or without a main button; in the former case, it must be an emphasized one.

outlined-action: Usually used as a link to another page or external resource.

This type also has semantic variations that can be used when additional semantics are needed: outlined-info, outlined-success, outlined-warning, and outlined-danger.

<Button view="outlined" size="l">Outlined</Button>
<Button view="outlined-action" size="l">Outlined Action</Button>
<Button view="outlined-info" size="l">Outlined Info</Button>
<Button view="outlined-success" size="l">Outlined Success</Button>
<Button view="outlined-warning" size="l">Outlined Warning</Button>
<Button view="outlined-danger" size="l">Outlined Danger</Button>
<Button view="outlined-utility" size="l">Outlined Utility</Button>

Flat

flat: Used for auxiliary actions that require the least attention. It is often used in a list of buttons or action icons (without text) in an editor.

flat-secondary: Less emphasized than the flat button. It is often used as a secondary button in dialog boxes and modal windows.

flat-action: Usually used as a link to another page or external resource.

It also has semantic variations that can be used where additional semantics are needed: outlined-info, outlined-success, outlined-warning, and outlined-danger.

<Button view="flat" size="l">Flat</Button>
<Button view="flat-secondary" size="l">Flat Secondary</Button>
<Button view="flat-action" size="l">Flat Action</Button>
<Button view="flat-info" size="l">Flat Info</Button>
<Button view="flat-success" size="l">Flat Success</Button>
<Button view="flat-warning" size="l">Flat Warning</Button>
<Button view="flat-danger" size="l">Flat Danger</Button>
<Button view="flat-utility" size="l">Flat Utility</Button>

Contrast

The normal-contrast, outline-contrast, and flat-contrast buttons highlight actions against complex background, e.g., in a banner, or against an inverse background.

<Button view="normal-contrast" size="l">Normal Contrast</Button>
<Button view="outlined-contrast" size="l">Outlined Contrast</Button>
<Button view="flat-contrast" size="l">Flat Contrast</Button>

Icons

To add an icon to a Button, use the Icon component, which is a special wrapper for SVGs.

No text:
<Button view="outlined" size="l">
    <Icon data={Gear} size={18} />
    Start
</Button>
<Button view="outlined" size="l">
    End
    <Icon data={Gear} size={18} />
</Button>
<Button view="outlined" size="l">
    <Icon data={Gear} size={18} />
    Both
    <Icon data={Gear} size={18} />
</Button>
<Button view="outlined" size="l">
    <Icon data={Gear} size={18} />
</Button>

States

A Button can have different states:

disabled: When the button is unavailable for some reason.

loading: When some asynchronous processes are running in the background.

selected: When the user can Enable and Disable the button.

<Button size="l" disabled>Disabled</Button>
<Button size="l" loading>Loading</Button>
<Button size="l" selected>Selected</Button>

Button automatically changes its appearance when corresponding aria-attributes (aria-haspopup, aria-expanded) are passed:

<Button aria-haspopup="menu" aria-expanded="true">Menu</Button>

Size

Use the size property to manage the Button size. The default size is m.

<Button size="xs">XS Size</Button>
<Button size="s">S Size</Button>
<Button size="m">M Size</Button>
<Button size="l">L Size</Button>
<Button size="xl">XL Size</Button>

Width

Use the width property to manage the way the Button behaves inside the container:

auto: Limits the maximum width of the Button by hiding the overflowing content with an ellipsis.

max: Matches the Button width to the width of the parent container, also hiding the overflowing content with an ellipsis.

Default

Auto

Max

<Button>Default</Button>
<Button width="auto">Auto</Button>
<Button width="max">Max</Button>

Pin

The pin property allows you to manage the shape of the start and end edges and is usually used for combining multiple buttons in a single unit. The pin property value consists of the start and end style names separated by a hyphen, e.g., round-brick. The edge styles are: round (default), circle, brick, and clear.

<div>
    <Button view="action" size="l" pin="round-clear">Create</Button>
    <Button view="action" size="l" pin="brick-round">...</Button>
</div>
<div>
    <Button view="normal" size="l" pin="circle-clear">Start</Button>
    <Button view="normal" size="l" pin="brick-brick" selected>Center</Button>
    <Button view="normal" size="l" pin="clear-circle">End</Button>
</div>
<div>
    <Button view="outlined" pin="brick-clear">1</Button>
    <Button view="outlined" pin="clear-clear">2</Button>
    <Button view="outlined" pin="clear-clear">3</Button>
    <Button view="outlined" pin="clear-brick">4</Button>
</div>

Properties

Button accepts any valid button or a element props in addition to these:

NameDescriptionTypeDefault
childrenButton content. You can use both text and the <Icon/> component.React.ReactNode
componentOverrides the root componentReact.ElementType
disabledToggles the disabled statebooleanfalse
hrefPass this to make the root component a linkstring
loadingToggles the loading statebooleanfalse
pinSets the Button edge stylestring"round-round"
qadata-qa HTML attribute, used for testingstring
selectedToggles the selected stateboolean
sizeSets theButton size"xs" "s" "m" "l" "xl""m"
viewSets the Button appearanceButtonView"normal"
widthControls how Button uses parent's space"auto" "max"

CSS API

NameDescription
--g-button-text-colorText color
--g-button-text-color-hoverText color on hover
--g-button-background-colorBackground color
--g-button-background-color-hoverBackground color on hover
--g-button-border-widthBorder width
--g-button-border-colorBorder color
--g-button-border-styleBorder style
--g-button-focus-outline-widthFocus outline width
--g-button-focus-outline-colorFocus outline color
--g-button-focus-outline-styleFocus outline style
--g-button-focus-outline-offsetFocus outline offset
--g-button-heightHeight (line height)
--g-button-paddingSide paddings
--g-button-border-radiusBorder radius
--g-button-font-sizeText font size
--g-button-icon-spaceIcon available space
--g-button-icon-offsetIcon offset