Button
Triggers an action and communicates what happens when it is activated.
On this page
This docs is LLM-friendly and available as clean Markdown.
Usage
import { GlButton } from "gitlab-ui-react/button";<GlButton>Create issue</GlButton>Default
The default button uses the medium size, primary category, and default variant. Its HTML type defaults to button, so it does not submit a form accidentally.
import { GlButton } from "gitlab-ui-react/button";
export default function ButtonExample() {
return <GlButton>Button</GlButton>;
}
Categories and variants
The category controls emphasis, while the variant communicates intent. Prefer primary and tertiary categories in new interfaces; the secondary category remains available for compatibility.
import { GlButton } from "gitlab-ui-react/button";
export default function ButtonVariantsExample() {
return (
<div className="grid gap-3">
<div className="flex flex-wrap gap-3">
<GlButton>Default</GlButton>
<GlButton category="secondary">Default secondary</GlButton>
<GlButton category="tertiary">Default tertiary</GlButton>
</div>
<div className="flex flex-wrap gap-3">
<GlButton variant="confirm">Confirm</GlButton>
<GlButton category="secondary" variant="confirm">Confirm secondary</GlButton>
<GlButton category="tertiary" variant="confirm">Confirm tertiary</GlButton>
</div>
<div className="flex flex-wrap gap-3">
<GlButton variant="danger">Danger</GlButton>
<GlButton category="secondary" variant="danger">Danger secondary</GlButton>
<GlButton category="tertiary" variant="danger">Danger tertiary</GlButton>
</div>
</div>
);
}
Size and layout
Use the medium size in most contexts for the larger target. Use the small size in compact areas, and block when the action should fill its container, especially in narrow layouts.
import { GlButton } from "gitlab-ui-react/button";
export default function ButtonSizesExample() {
return (
<div className="grid gap-3">
<div className="flex items-center gap-3">
<GlButton size="small">Small button</GlButton>
<GlButton>Medium button</GlButton>
</div>
<GlButton block>Full-width button</GlButton>
</div>
);
}
Icons and counts
Use text or an icon when either can communicate the action on its own. Every icon-only button needs an aria-label. A count can include countSrText to give assistive technology the context that sighted users infer from the interface.
import { GlButton } from "gitlab-ui-react/button";
export default function ButtonContentExample() {
return (
<div className="flex flex-wrap items-center gap-3">
<GlButton icon="star-o">Star project</GlButton>
<GlButton aria-label="More actions" icon="ellipsis_h" />
<GlButton count={5} countSrText="open issues">Issues</GlButton>
</div>
);
}
States
Use loading while a native button action is in progress. A disabled button remains focusable and uses aria-disabled, so connect it to visible explanatory text with aria-describedby. For a toggle button, keep selected and aria-pressed in sync.
import { GlButton } from "gitlab-ui-react/button";
export default function ButtonStatesExample() {
return (
<div className="flex flex-wrap items-center gap-3">
<GlButton loading>Loading</GlButton>
<GlButton aria-pressed="true" selected>Selected</GlButton>
<GlButton disabled>Disabled</GlButton>
</div>
);
}
Accessibility
- Give every button a concise accessible name. Visible text usually provides it; icon-only buttons require
aria-label. - Keep keyboard focus order the same as visual order, and do not suppress the visible focus indicator.
- Explain why an action is unavailable. Prefer
aria-describedbywhen the explanation already appears on the page. - Pair
selectedwith the matchingaria-pressedvalue when the button behaves as a toggle. - Use
hrefonly for navigation. Withouthref,GlButtonrenders a semantic<button>.
API
These are the props used most often. GlButton also accepts supported Base UI button props and forwards DOM attributes to the rendered element.
| Prop | Description | Default |
|---|---|---|
category |
Sets the action hierarchy to primary, secondary, or tertiary. |
"primary" |
variant |
Communicates intent with default, confirm, danger, link, or reset styling. |
"default" |
size |
Sets the control to small or medium. |
"medium" |
block |
Expands the button to the width of its parent. | false |
icon |
Adds an icon from the GitLab SVG library. | — |
count |
Displays a non-negative numeric count after the label. | null |
countSrText |
Adds screen-reader context to the count. | — |
disabled |
Prevents activation while keeping the control focusable. | false |
loading |
Shows a spinner and prevents activation of a native button. | false |
selected |
Applies the selected appearance; pair it with aria-pressed. |
false |
href |
Renders an anchor styled as a button. | — |
type |
Sets the native button type to button, submit, or reset. |
"button" |
label |
Renders a non-interactive span styled as a button. |
false |
render |
Composes the behavior onto a custom React element. | — |