<c-button>
Buttons trigger actions — submitting a form, opening a modal, confirming a choice. Use one filled button (the default `appearance`) per view for its main action; other actions use `appearance="outlined"`, `"ghost"` or `"text"`.
Usage
When to use
- Performing an action on the current page (save, send, confirm).
- Navigating with button semantics: set
hrefto render a real link styled as a button.
When not to use
- Inline navigation within text — use
c-link. - Toggling a persistent on/off state — use
c-switch.
Appearances
appearance sets how strongly a button reads: filled (the default) for the
main action, then outlined (an outline, no fill), ghost (a light tint)
and text (no fill or outline) for lower emphasis. inverted is for a fixed
dark or brand-coloured backdrop: it paints the inverse-* family, which looks
the same in both theme modes.
The outlined, ghost and text boolean attributes of 3.x still work until
5.0; appearance wins when both are set.
Variants
variant sets the button's colour, in every appearance: primary (the
default) and secondary, the brand colours; success, info and warning;
and danger for a destructive action, in the error colour. A colour is not an
emphasis level — make a less important action lighter with appearance, not
secondary.
<c-button variant="danger">Delete</c-button>
<c-button appearance="outlined" variant="success">Approve</c-button>
The filled success, info and warning buttons have a dark label, which stays readable (WCAG AA) on their lighter fills. Inverted, only the filled look shows the colour, as its label on the white button; the lighter appearances stay white.
An app can change the default colour of every c-button with
applyDefaults({ 'c-button': { variant: 'secondary' } }). The buttons the
library draws inside its own components keep primary, and so do the buttons
of c-tab-buttons, whose sliding indicator has one colour.
The danger attribute of earlier releases still works until 5.0; variant
wins when both are set.
Icon
A leading icon goes in the icon slot, before the label. The button sizes it
to match: 24px, or 20px on a small button. That covers a c-icon without
size and a plain <svg> or <img>; a c-icon with its own size keeps
it, for a glyph that looks too small or too large at the button's size.
<c-button>
<c-icon slot="icon" path="M19,13H13V19H11V13H5V11H11V5H13V11H19V13Z"></c-icon>
Add
</c-button>
In a form
type="submit" submits the button's <form> — the one around it, or the one
its form attribute names — validating it first, as form.requestSubmit()
does, and type="reset" resets it; the default button does nothing to the
form. A disabled or loading button, or one with an href, never submits,
and a disabled <fieldset> around the button disables it.
The fields beside it take part in the form as native controls do: each
submits its value under its name, form.reset() returns it to the value
its markup set, and a disabled <fieldset> disables it. Enter in a
single-line text field submits the form through its first submit button,
c-button included, so a loading button stops that submit too.
A form without novalidate is checked before it submits: a required field
left empty, a date or colour that is bad input, a number out of range, an
incomplete mask or a partly filled code stops the submit, and the browser
points at the field with its own message. The field's look follows only its
invalid prop, so an app that shows its own error messages adds novalidate
and checks the fields itself:
<form novalidate @submit.prevent="save">
<c-text-field v-model="name" label="Name" name="name" required />
<c-button type="submit">Save</c-button>
</form>
What each field submits under its name:
| Field | Submits |
|---|---|
| Text, number, code, colour, date and time fields | Its text, '' when empty; a number as a plain JS number (1234.5), never the grouped text |
A range date or time picker |
One ISO 8601 interval, 2026-11-01/2026-11-30, with a side left empty while it has none |
c-select, c-autocomplete, c-tree-select |
The picked value (an item's value), '' without one; one entry per pick with multiple |
c-checkbox, c-switch |
Its true-value while on (on for true), nothing while off |
c-radio-group, c-button-group |
The picked value, nothing without one; one entry per active button with multiple |
c-slider |
Its value |
c-file-upload takes no part: its upload function sends the files.
Slotted button
A password manager reads a form's submit button to tell what the form is
for, and cannot find the native button inside a c-button's shadow root:
Proton Pass, for one, then offers no password to generate on a sign-up form.
For the submit button of a form a password manager reads — sign up, log in,
change password — write the <button> yourself inside the c-button:
<c-button :loading="saving">
<button type="submit">Create account</button>
</c-button>
The button fills the c-button, which paints it with its appearance,
variant, size, ripple and loading spinner, and it stays in the page, where
every password manager finds it. Its own attributes apply — type,
disabled, name, value, form — and it submits its form natively. The
c-button's type, href, target and value are ignored, and so are
the icon and description slots (put an icon inside the button), each
with a console warning. loading cancels the button's clicks; set
disabled on the button, where assistive technology hears it.
Every other form keeps <c-button type="submit">.
Accessibility
The root part is a native <button> (or <a> when href is set), so
focus, keyboard activation and screen-reader semantics come from the
platform; with a slotted button, the page's own <button> is the control and
root only paints. When only an icon is slotted, provide an accessible name on the
host, e.g. aria-label="Close".
The element's focus() focuses that control, as on a native button, so a
page can move focus to it and a menu or popover returns focus to it.
Customization
Restyle via CSS parts from your own stylesheet:
c-button::part(root) {
border-radius: 9999px;
}
Examples
<template>
<div class="example-row">
<c-button>Default</c-button>
<c-button appearance="outlined">Outlined</c-button>
<c-button appearance="ghost">Ghost</c-button>
<c-button appearance="text">Text</c-button>
<c-button disabled>Disabled</c-button>
</div>
</template>
<template>
<div class="example-row">
<c-button size="small">Small</c-button>
<c-button>Default</c-button>
<c-button size="large">Large</c-button>
</div>
</template>
<template>
<div class="example-grid">
<div class="example-row">
<c-button>Primary</c-button>
<c-button variant="secondary">Secondary</c-button>
<c-button variant="success">Success</c-button>
<c-button variant="info">Info</c-button>
<c-button variant="warning">Warning</c-button>
<c-button variant="danger">Danger</c-button>
</div>
<div class="example-row">
<c-button appearance="outlined">Primary</c-button>
<c-button appearance="outlined" variant="secondary">Secondary</c-button>
<c-button appearance="outlined" variant="success">Success</c-button>
<c-button appearance="outlined" variant="info">Info</c-button>
<c-button appearance="outlined" variant="warning">Warning</c-button>
<c-button appearance="outlined" variant="danger">Danger</c-button>
</div>
<div class="example-row">
<c-button appearance="ghost">Primary</c-button>
<c-button appearance="ghost" variant="secondary">Secondary</c-button>
<c-button appearance="ghost" variant="success">Success</c-button>
<c-button appearance="ghost" variant="info">Info</c-button>
<c-button appearance="ghost" variant="warning">Warning</c-button>
<c-button appearance="ghost" variant="danger">Danger</c-button>
</div>
<div class="example-row">
<c-button appearance="text">Primary</c-button>
<c-button appearance="text" variant="secondary">Secondary</c-button>
<c-button appearance="text" variant="success">Success</c-button>
<c-button appearance="text" variant="info">Info</c-button>
<c-button appearance="text" variant="warning">Warning</c-button>
<c-button appearance="text" variant="danger">Danger</c-button>
</div>
</div>
</template>
API reference
<c-button>
Buttons trigger actions — submitting a form, opening a modal, confirming a choice. Use one filled button (the default `appearance`) per view for its main action; other actions use `appearance="outlined"`, `"ghost"` or `"text"`.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
active | active | boolean | — | Pressed (toggle) state — renders the selected look and sets `aria-pressed`. Leave unset for regular action buttons: only a true/false value marks the button as a toggle. Driven by `c-button-group` on its slotted buttons. |
appearance | appearance | CButtonAppearance | — | The button's look: `filled` (unless set) for the main action of a view; `outlined` (a primary outline, no fill), `ghost` (a light primary tint) or `text` (no fill or outline) for lower emphasis. |
disabled | disabled | boolean | false | Grey the button out and block clicks and keys, a link button (`href`) included. |
fit | fit | boolean | false | Stretch the button to the full width of its container. |
href | href | string | '' | URL to link to: the button renders as a real link (`<a>`) styled as a button. |
inverted | inverted | boolean | false | Inverted colours for a fixed dark or brand-coloured backdrop: the `inverse-*` family, the same in both theme modes. Combines with every appearance. |
loading | loading | boolean | false | Show a spinner in place of the label and ignore clicks and keys, e.g. while the action runs. |
noRadius | no-radius | boolean | false | Square corners instead of the rounded default. |
size | size | CButtonSize | 'default' | Size of the button: `small`, `default` (the control height, level with a form field) or `large` (the toolbar height). |
target | target | string | '' | Where the `href` opens, as on a native `<a>`: the same tab unless set — `_blank` for a new one. |
type | type | CButtonType | 'button' | Native `type` of the button: `button` unless set, `submit` or `reset`. Ignored when `href` is set. |
value | value | number | string | — | The button's value in a `c-button-group`; in `c-tab-buttons`, the `value` of the `c-tab-item` panel it shows. |
variant | variant | CButtonVariant | 'primary' app default | The button's colour, in every appearance: `primary` unless set (or changed app-wide), `secondary`, `success`, `info`, `warning`, or `danger` for a destructive action. |
danger deprecated | danger | boolean | false | Deprecated. Use `variant="danger"`. Danger look for a destructive action: the error colour. |
ghost deprecated | ghost | boolean | false | Deprecated. Use `appearance="ghost"`. Ghost appearance: primary text on a light primary tint, for lower emphasis. |
outlined deprecated | outlined | boolean | false | Deprecated. Use `appearance="outlined"`. Outlined appearance: a primary outline and text with no fill, for lower emphasis. |
text deprecated | text | boolean | false | Deprecated. Use `appearance="text"`. Text appearance: primary text with no fill or outline, the lightest look. |
app default marks a prop you can set for every instance at once with applyDefaults() — an explicit attribute or property on an instance still wins.
Methods
| Method | Signature | Description |
|---|---|---|
focus | (options?: FocusOptions): void | Focus its button — its link under `href`, or the slotted button — as `focus()` does on a native button: the element renders no box of its own to take it. |
Slots
| Slot | Description |
|---|---|
default | Button label content, or a slotted `<button>` (ADR-0085): the page's own native button, which a password manager reading the form's submit button finds. Its own `type`, `disabled`, `name`, `value` and `form` apply; the element paints its look. |
icon | Leading icon, vertically centered before the label. |
description | Secondary text rendered below the label. |
CSS parts
Style from outside with c-button::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The native `<button>` / `<a>` element carrying the visual styling. |
content | Layout wrapper for the label, icon and description. |
description | Wrapper of the `description` slot. |
Types
Importable from the package root: import type { … } from '@cscfi/csc-ui'
CButtonAppearance
How strongly a button reads: `filled` for the main action, then `outlined`, `ghost` and `text`, each lighter than the last.
export type CButtonAppearance = 'filled' | 'ghost' | 'outlined' | 'text';CButtonSize
Size of the button.
export type CButtonSize = 'default' | 'large' | 'small';CButtonType
Native `type` of the underlying `<button>` element. Ignored when `href` turns the component into a link.
export type CButtonType = 'button' | 'reset' | 'submit';CButtonVariant
The colour a button takes: `primary` (unless set) and `secondary`, the brand families, or a status colour — `success`, `info`, `warning` and `danger`, a destructive action in the error colour.
export type CButtonVariant =
| 'danger'
| 'info'
| 'primary'
| 'secondary'
| 'success'
| 'warning';