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.

import {Button} from '@gravity-ui/uikit';

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.

import {Button} from '@gravity-ui/uikit'


export default function () {
    return (
        <>
            <Button view="action" size="l">Action</Button>
            <Button view="normal" size="l">Normal</Button>
            <Button view="raised" size="l">Raised</Button>
        </>
    )
}

import {Button} from '@gravity-ui/uikit'

export default function () {
    return (
        <>
            <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.

import {Button} from '@gravity-ui/uikit';


export default function () {
    return (
        <>
            <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>
        </>
    );
}

import {Button} from '@gravity-ui/uikit';

export default function () {
    return (
        <>
            <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.

import {Button} from '@gravity-ui/uikit';


export default function () {
    return (
        <>
            <Button view="flat" size="l">Flat</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>
        </>
    );
}

import {Button} from '@gravity-ui/uikit';

export default function () {
    return (
        <>
            <Button view="flat" size="l">Flat</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.

import {Button} from '@gravity-ui/uikit'
import {type CSSProperties} from 'react';


const containerStyle: CSSProperties = {
    display: 'flex',
    gap: 16,
    backgroundColor: 'rgb(68, 38, 204)',
    padding: '20px',
    borderRadius: '8px'
}


export default function () {
    return (
        <div style={containerStyle}>
            <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>
        </div>
    )
}

import {Button} from '@gravity-ui/uikit'
import {type CSSProperties} from 'react';

const containerStyle: CSSProperties = {
    display: 'flex',
    gap: 16,
    backgroundColor: 'rgb(68, 38, 204)',
    padding: '20px',
    borderRadius: '8px'
}

export default function () {
    return (
        <div style={containerStyle}>
            <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>
        </div>
    )
}

Icons

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

import {Gear} from '@gravity-ui/icons';
import {Button, Icon} from '@gravity-ui/uikit';


export default function () {
    return (
        <>
            <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>
        </>
    );
}

import {Gear} from '@gravity-ui/icons';
import {Button, Icon} from '@gravity-ui/uikit';

export default function () {
    return (
        <>
            <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.

import {Button} from '@gravity-ui/uikit';


export default function () {
    return (
        <>
            <Button size="l" disabled>Disabled</Button>
            <Button size="l" loading>Loading</Button>
            <Button size="l" selected>Selected</Button>
        </>
    );
}

import {Button} from '@gravity-ui/uikit';

export default function () {
    return (
        <>
            <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:

import {Button} from '@gravity-ui/uikit';


export default function () {
    return (
        <>
            <Button aria-haspopup="menu" aria-expanded="true">Menu</Button>
        </>
    );
}

import {Button} from '@gravity-ui/uikit';

export default function () {
    return (
        <>
            <Button aria-haspopup="menu" aria-expanded="true">Menu</Button>
        </>
    );
}

Size

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

import {Button} from '@gravity-ui/uikit';


export default function () {
    return (
        <>
            <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>
        </>
    );
}

import {Button} from '@gravity-ui/uikit';

export default function () {
    return (
        <>
            <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

import {Button} from '@gravity-ui/uikit';
import {type CSSProperties} from 'react';


const containerStyle: CSSProperties = {
    width: 100,
    border: '2px dashed gray',
};


const titleStyle: CSSProperties = {
    textAlign: 'center',
};


export default function () {
    return (
        <>
            <div style={containerStyle}>
                <h4 style={titleStyle}>Default</h4>
                <p>
                    <Button>Text</Button>
                </p>
                <p>
                    <Button>Very Long Text</Button>
                </p>
            </div>
            <div style={containerStyle}>
                <h4 style={titleStyle}>Auto</h4>
                <p>
                    <Button width="auto">Text</Button>
                </p>
                <p>
                    <Button width="auto">Very Long Text</Button>
                </p>
            </div>
            <div style={containerStyle}>
                <h4 style={titleStyle}>Max</h4>
                <p>
                    <Button width="max">Text</Button>
                </p>
                <p>
                    <Button width="max">Very Long Text</Button>
                </p>
            </div>
        </>
    );
}

import {Button} from '@gravity-ui/uikit';
import {type CSSProperties} from 'react';

const containerStyle: CSSProperties = {
    width: 100,
    border: '2px dashed gray',
};

const titleStyle: CSSProperties = {
    textAlign: 'center',
};

export default function () {
    return (
        <>
            <div style={containerStyle}>
                <h4 style={titleStyle}>Default</h4>
                <p>
                    <Button>Text</Button>
                </p>
                <p>
                    <Button>Very Long Text</Button>
                </p>
            </div>
            <div style={containerStyle}>
                <h4 style={titleStyle}>Auto</h4>
                <p>
                    <Button width="auto">Text</Button>
                </p>
                <p>
                    <Button width="auto">Very Long Text</Button>
                </p>
            </div>
            <div style={containerStyle}>
                <h4 style={titleStyle}>Max</h4>
                <p>
                    <Button width="max">Text</Button>
                </p>
                <p>
                    <Button width="max">Very Long Text</Button>
                </p>
            </div>
        </>
    );
}

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.

import {Button} from '@gravity-ui/uikit';


export default function () {
    return (
        <>
            <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>
        </>
    );
}

import {Button} from '@gravity-ui/uikit';

export default function () {
    return (
        <>
            <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:

Name	Description	Type	Default
children	`Button` content. You can use both text and the `<Icon/>` component.	`React.ReactNode`
component	Overrides the root component	`React.ElementType`
disabled	Toggles the `disabled` state	`boolean`	`false`
href	Pass this to make the root component a link	`string`
loading	Toggles the `loading` state	`boolean`	`false`
pin	Sets the `Button` edge style	`string`	`"round-round"`
qa	`data-qa` HTML attribute, used for testing	`string`
selected	Toggles the `selected` state	`boolean`
size	Sets the`Button` size	`"xs"` `"s"` `"m"` `"l"` `"xl"`	`"m"`
view	Sets the `Button` appearance	`ButtonView`	`"normal"`
width	Controls how `Button` uses parent's space	`"auto"` `"max"`

CSS API

Name	Description
`--g-button-text-color`	Text color
`--g-button-text-color-hover`	Text color on hover
`--g-button-background-color`	Background color
`--g-button-background-color-hover`	Background color on hover
`--g-button-border-width`	Border width
`--g-button-border-color`	Border color
`--g-button-border-style`	Border style
`--g-button-focus-outline-width`	Focus outline width
`--g-button-focus-outline-color`	Focus outline color
`--g-button-focus-outline-style`	Focus outline style
`--g-button-focus-outline-offset`	Focus outline offset
`--g-button-height`	Height (line height)
`--g-button-padding`	Side paddings
`--g-button-border-radius`	Border radius
`--g-button-font-size`	Text font size
`--g-button-icon-space`	Icon available space
`--g-button-icon-offset`	Icon offset

Button

Appearance

Basic

Outlined

Flat

Contrast

Icons

States

Menu trigger

Size

Width

Default

Auto

Max

Pin

Properties

CSS API

Button

§Appearance

§Basic

§Outlined

§Flat

§Contrast

§Icons

§States

§Menu trigger

§Size

§Width

Default

Auto

Max

§Pin

§Properties

§CSS API

Appearance

Basic

Outlined

Flat

Contrast

Icons

States

Menu trigger

Size

Width

Pin

Properties

CSS API