PrimaryCSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
CSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select
Migration guide
How to upgrade an app from @cscfi/csc-ui 3.x (the Stencil implementation) to the rewritten 4.x — same package name, new major version. The <c-*> tag names are unchanged; what changes is registration, two-way binding, customization, and theming. Pick your flavor with the switcher in the header.
Before you start
Version 4 is a complete rewrite of the library under the same package name: the tag names are stable — every <c-*> element keeps its name, so your existing markup mostly stays put. What changes is everything around the tags — how you register the library, how two-way binding and events work, how you customize and theme components.
3.x is unsupported since 4.0.0: 3.0.19 is its last release, and it gets no fixes. An app that cannot upgrade yet stays on it by pinning the major version (@cscfi/csc-ui@3, and @cscfi/csc-ui-react@3 for React); its documentation stays available as an archive.
This is an all-at-once upgrade. You cannot run 3.x and 4.x side by side: both register the same custom-element tags, and the second defineCustomElements() call throws a "already defined" error. Bump the whole dependency in one change rather than component by component.
@cscfi/csc-ui 4.x is ESM-only, so a bundler (Vite, webpack, etc.) is assumed.
Bump the core package to 4.x and remove the v-control directive package (@cscfi/csc-ui-vue, or @cscfi/csc-ui-vue2 on Vue 2) — the 4.x elements support plain v-model natively, so the directive is gone.
Drop applyPolyfills and the /loader subpath — 4.x exports defineCustomElements() directly and registers every element eagerly. Remove the v-control directive registration. Switch the CSS import to css/tokens.css.
Before — 3.x
import '@cscfi/csc-ui/css/theme.css';import { createApp } from 'vue';import { applyPolyfills, defineCustomElements } from '@cscfi/csc-ui/loader';import { vControl } from '@cscfi/csc-ui-vue';import App from './App.vue';const app = createApp(App);app.directive('control', vControl);applyPolyfills().then(() => defineCustomElements());app.mount('#app');
After — 4.x
import '@cscfi/csc-ui/css/tokens.css';import { createApp } from 'vue';import { defineCustomElements } from '@cscfi/csc-ui';import App from './App.vue';defineCustomElements();createApp(App).mount('#app');
Two-way binding & events
changeValue and every other camelCase event are gone (ADR-0075). Every value control reports through the same three events, with a native input's timing: input (no detail) and update:value (the value) on every value change, and change (the value) on every commit — Enter or leaving the field for typed text, each pick or toggle, each arrow-key step, the release that ends a drag. Where a changeValue handler ran on every keystroke or slider move, listen for update:value to keep that timing, or for change to act once per commit. The change event stays on the element: it does not bubble, so listen on each control.
The headline change for Vue. The v-control directive is gone — value components support plain v-model directly.
Use plain v-model (no argument): the elements ride the native input event, so v-model:value does not compile on a custom element and must not be used. A Vue template can never hear update:value — Vue skips every @update:* listener on an element — so a former @change-value handler becomes @change (commits, the value in $event.detail) or @input (every change, the value in $event.target.value). For other two-way state, bind :prop and listen to the lowercase @change:<prop> event (e.g. @change:open, @change:sort) — the old update:<prop> events were renamed for the same reason.
<template> <!-- plain v-model, no directive --> <c-text-field v-model="name" label="Name" /> <c-switch v-model="enabled">Notifications</c-switch> <!-- change: each commit, with the value as $event.detail --> <c-select :value="country" @change="save($event.detail)" /> <!-- input: every change; read the element's value --> <c-slider :value="volume" @input="preview($event.target.value)" /></template><script setup lang="ts">import { ref } from 'vue';const name = ref('');const enabled = ref(false);</script>
Other two-way state — :prop + @change:prop
<template> <!-- NOT v-model:open — bind the prop and listen to change:open --> <c-menu :open="open" @change:open="open = $event.detail"> <c-button slot="trigger">Menu</c-button> <c-menu-item>Profile</c-menu-item> </c-menu></template><script setup lang="ts">import { ref } from 'vue';const open = ref(false);</script>
Catch the old listeners — ESLint
// eslint.config.js (eslint-plugin-vue): a listener that can never fire// is an error, so none survives the upgrade unnoticed.const on = "VElement[rawName=/^c-/] > VStartTag > VAttribute[directive=true][key.name.name='on']";export default [ { files: ['**/*.vue'], rules: { 'vue/no-restricted-syntax': [ 'error', { message: 'Vue never attaches an @update:* listener to a custom element. Use v-model, @input with the element’s value, or @change.', selector: `${on}[key.argument.name=/^update:/]`, }, { message: 'csc-ui 4 removed this event. Use @change (commits) or @input (every change); a side navigation item fires @select.', selector: `${on}[key.argument.name=/^(change-?value|item-?change)$/i]`, }, ], }, },];
Styling & customization
Per-component CSS custom properties are gone. Variables like --c-button-background-color or --c-button-border-radius no longer exist; ::part() is now the sole customization API, and a component's curated part set is its customization contract.
The --c-font-family token is gone too. Components, and the content you slot into them, inherit your page's typeface, line height and font features, as native elements do. Set your font on body; to give one component another typeface, set font-family on its c-* element.
So are the Stencil-era colour tokens --c-text-dark, --c-text-light, --c-text-body, --c-text-system and --c-transparent: use the semantic roles, such as --c-on-surface and --c-on-surface-muted, which follow dark mode. c-icon's --c-icon-color hook is private now; recolour an icon through its own color prop or its ::part(root).
The flat, light-only ramp is replaced by a semantic-token layer with real dark-mode support. Components now follow the OS light/dark preference by default; set data-theme="light" or "dark" on <html> to pin a mode.
To re-brand, stop overriding individual --c-* ramp variables. Instead hand applyTheme one step-500 seed colour per family you want to override — the whole 50–950 ramp and both light and dark modes regenerate from it.
Most components keep their old props and events. The ones below changed enough to need attention when you upgrade.
c-data-table — headers → columns
// Before: headers[] describe the columns, and every data cell is wrapped.const headers = [ { key: 'name', value: 'Name' }, { key: 'id', value: 'ID', sortable: false },];const data = [{ id: { formattedValue: '#1', value: 1 }, name: { value: 'Ada' } }];// After: columns[] describe the columns, rows are plain objects, and a custom// cell is a render function (h is re-exported by the package).import { h, type CDataTableColumn } from '@cscfi/csc-ui';const columns: CDataTableColumn[] = [ { header: 'Name', key: 'name', sortable: true }, { cell: ({ value }) => h('code', `#${value}`), header: 'ID', key: 'id' },];const data = [{ id: 1, name: 'Ada' }];// A column sorts only with sortable: true, where 3.x sorted every column// that did not say sortable: false. columns holds functions, so set it as a// property (:columns in Vue, [columns] in Angular), never as an attribute.
c-data-table — pinned / hidden → expansion policy
// 3.x hid the columns that did not fit unless horizontal-scrolling was// set. 4.x scrolls sideways unless autohide is set, and each column's// expansion says where its cells go:// pinned: true (never hidden) -> expansion: 'never'// hidden: true (always hidden) -> expansion: 'always'// (default) -> expansion: 'auto'// pinned now pins a column to an edge while the table scrolls sideways:// pinned: 'left' or 'right'.
c-tab-buttons — standalone use moves to c-button-group
<!-- Before: c-tab-buttons doubled as a standalone segmented value picker. --><c-tab-buttons value="week" mandatory> <c-button value="day">Day</c-button> <c-button value="week">Week</c-button></c-tab-buttons><!-- After: same markup on the new c-button-group tag. c-tab-buttons now exists only as the tab-strip adapter inside <c-tabs> (where nothing changes for you). Differences on the new tag: - events are change / update:value / native input — there is no changeValue; deselecting emits null (was '') - new: label + required, and a multiple mode (array value) --><c-button-group value="week" mandatory> <c-button value="day">Day</c-button> <c-button value="week">Week</c-button></c-button-group>
Form controls — valid → invalid, validation → error-message
<!-- Before: every form control had validation (default 'Required field') shown while valid was false, plus inert validate / validate-on-blur. --><c-text-field label="Email" :valid="!error" validation="Email is required"></c-text-field><!-- After: valid is invalid (ADR-0076), so markup can set it: a bare invalid attribute, or a binding such as :invalid="!!error". A leftover :valid is ignored and the error never shows. The message is error-message (errorMessage in React / as a DOM property) on every field, c-checkbox, c-radio-group, c-otp-input and c-message. There is NO default text: an invalid control without an error-message keeps showing its hint, styled as a hint. validate and validate-on-blur are removed — they were never wired to anything; validation logic stays in your app. --><c-text-field label="Email" :invalid="!!error" error-message="Email is required"></c-text-field>
c-toolbar / c-page — the document scrolls
<!-- Before: c-toolbar was position: fixed and class="relative" put it in flow; c-page was the scroll container, sized to the viewport minus the 60px toolbar. --><c-main> <c-toolbar class="relative">…</c-toolbar> <c-page>…</c-page></c-main><!-- After: the document scrolls (ADR-0051). The toolbar is pinned with CSS sticky; the static prop (static in React) keeps it in flow instead. c-page has no height and does not scroll — drop c-page { height } overrides and scroll listeners on it; scroll-indicator tracks the document; smooth scrolling is html { scroll-behavior: smooth }. Inside c-main the desktop side navigation is pinned automatically and sized to the pinned height, with its bottom slot at the bottom edge (drop the autoheight class there; it stays for standalone use), and a new banner slot sits above the toolbar. --><c-main> <c-alert slot="banner" type="info">Maintenance on Saturday.</c-alert> <c-toolbar static>…</c-toolbar> <c-side-navigation>…</c-side-navigation> <c-page>…</c-page></c-main>
Other components
- c-autocomplete: no longer built on c-dropdown; it renders its own popover panel with an internal search input. Option/value events are unchanged, but the 3.x query API is not: the query prop, the changeQuery event and the minimum-query-length / minimum-query-length-message props are removed. For an async data source, set external and listen to change:query (detail: the query string) — see the c-autocomplete external example. A custom match is the filter prop; no-matching-items-message is now texts.noResults (the texts object prop, bound as a property). c-option-value is the option's label region again, in c-select too: a slotted option's label is name, else the c-option-value text, else the option's whole text, and the runs of a label equal to the query are marked as the match part (c-autocomplete::part(match)); the 3.x mark element had no part.- c-modal: not in the browser's top layer and no ::backdrop; its backdrop is its own element, coloured by the scrim token. Escape still closes every modal and dismissable still governs the backdrop click, as in 3.x; z-index is gone: open modals stack themselves, below toasts.- c-menu: authored declaratively with slotted c-menu-item / c-menu-label instead of a programmatic items array, and the trigger moves from the default slot to slot="trigger"; leaf activation fires a select event.- c-side-navigation: activating an item or sub-item no longer marks it as the current page. 3.x highlighted the clicked item even when the navigation never happened; set current on the current page's item from your router or the URL. A parent still expands and collapses itself.- c-toasts: a message's title is now heading (an untyped { title } loses its heading silently). c-toast is internal: c-toasts renders one per addToast() message, so style a toast through c-toasts::part(toast-root) and its other toast-* parts, and listen to close on c-toasts (detail: the message). addToast() returns the message's id, for removeToast(id).- c-swiper / c-swiper-tab: removed, no replacement.- c-row: removed — use your own flex container (display: flex plus gap).- c-spacer: removed — use margin-inline-start: auto on the element you want pushed to the far edge, or your own flex-grow filler. c-backdrop / c-ripple were internal-only and are not part of the public API.
Renamed attributes that still work
A few 3.x attributes have new names in 4.0, but the old names keep working until 5.0, so you can switch at your own pace. Your editor and TypeScript mark an old name as deprecated, and the API tables list it last. When an element carries both names, the new one wins.
Old name → new name
- c-button, c-icon-button: outlined, ghost, text → appearance="outlined", "ghost" or "text" (filled is the default)- c-button, c-icon-button: danger → variant="danger". variant also takes primary (the default), secondary, success, info and warning.- c-text-field, c-number-field, c-select, c-autocomplete, c-tree-select, c-date-picker, c-time-picker, c-color-picker, c-file-upload, c-checkbox, c-radio-group, c-otp-input: hide-details → hide-message (also as an applyDefaults() key). c-pagination and c-progress-bar keep hide-details.- c-spinner, c-loader: width → thickness- c-toasts: vertical + horizontal → position (bottom, bottom-start, bottom-end, top, top-start, top-end); absolute → contained- c-side-navigation-item: active → current on an item without sub-items, expanded on a parent. c-sub-navigation-item: active → current.- c-card: fullscreen → show-fullscreen- c-slider: labels → tick-labels
Types & IDE tooling
Public TypeScript types are now exported from the package root using the C<Component><Concept> convention — e.g. CButtonSize, CAlertType, CSelectItem. Import them from @cscfi/csc-ui instead of deep paths.
IDE integration data changed too: the library now ships a Custom Elements Manifest (custom-elements.json) plus web-types.json and VS Code custom-data files, replacing the old docs.json / vscode-data.json.
import type { CButtonSize, CSelectItem } from '@cscfi/csc-ui';
3.x API, name by name
Every 3.x tag, attribute, event, method, slot and CSS custom property that 4.x removed, renamed or changed the default or type of, and the ones whose behaviour changed under the same name. Attributes are listed by their 3.x attribute name.
Every component
3.x
Kind
In 4.x
all
CSS custom property
Per-component CSS custom properties are gone. Restyle the component’s parts with ::part(); see Styling & customization.
c-accordion
3.x
Kind
In 4.x
value
Attribute
Also takes null: every item collapsed. Setting value from code no longer fires an event (3.x fired changeValue): the value events report what the user does.
changeValue
Event
Use change: it carries the new value as detail, as changeValue did. In a Vue template bind v-model or @change; in React, onChange.
c-accordion-item
3.x
Kind
In 4.x
collapsable
Attribute
Internal: c-accordion sets it from its mandatory.
expanded
Attribute
Internal: c-accordion sets it from its value: expand items through the accordion’s value (or v-model), and style an expanded item with c-accordion-item:state(expanded).
outlined
Attribute
Internal: set outlined on c-accordion.
itemChange
Event
Internal: it only wires the item to c-accordion, and stops there. Listen to c-accordion, whose change carries the expanded value.
header
Slot
Renamed to heading (the glossary’s name, as the heading prop). A leftover slot="header" matches no slot, so its content disappears.
c-alert
3.x
Kind
In 4.x
title
Slot
Renamed to heading, like the heading prop that sets plain text. A leftover slot="title" matches no slot, so its content disappears.
c-autocomplete
3.x
Kind
In 4.x
id
Attribute
A plain id on the element itself, as on any element: it no longer reaches the inner control, whose own id lives in the component’s shadow root, out of reach of your page’s for and aria-* anyway. Name the control with its label.
minimum-query-length
Attribute
Removed with the query API. For an async data source, set external and listen to change:query, and decide in your handler when a query is long enough.
minimum-query-length-message
Attribute
Removed with the query API. For an async data source, set external and listen to change:query, and decide in your handler when a query is long enough.
no-matching-items-message
Attribute
Moved to texts.noResults (the texts object, set as a property).
query
Attribute
Removed with the query API. For an async data source, set external and listen to change:query, and decide in your handler when a query is long enough.
valid
Attribute
Renamed to invalid, with the opposite meaning (ADR-0076): :valid="!error" becomes :invalid="!!error", and markup sets a bare invalid attribute. A leftover valid is ignored, so the error never shows.
validate
Attribute
Removed: it was never wired to anything. Keep validation in your app and show its result with error-message.
validate-on-blur
Attribute
Removed: it was never wired to anything. Keep validation in your app and show its result with error-message.
validation
Attribute
Renamed to error-message (errorMessage as a property). It has no default text: an invalid control without one keeps showing its hint.
changeQuery
Event
Removed with the query API. For an async data source, set external and listen to change:query; the detail is the query.
changeValue
Event
Use change: it carries the new value as detail, as changeValue did. In a Vue template bind v-model or @change; in React, onChange.
reset
Method
Removed: it announced a value set from outside, which no value control does any more. Set value to null ([] with multiple).
c-backdrop
3.x
Kind
In 4.x
<c-backdrop>
Tag
Removed: it was internal in 3.x.
c-button
3.x
Kind
In 4.x
grouped
Attribute
Removed: c-tab-buttons set it on its buttons (it was private in 3.x). Group buttons in c-button-group, and tabs in c-tabs.
id
Attribute
A plain id on the element itself, as on any element: it no longer reaches the inner control, whose own id lives in the component’s shadow root, out of reach of your page’s for and aria-* anyway. Name the control with its label.
tabs
Attribute
Removed: c-tab-buttons set it on its buttons (it was private in 3.x). Group buttons in c-button-group, and tabs in c-tabs.
target
Attribute
Defaults to '', as on a native <a>: an href opens in the same tab. Add target="_blank" where you relied on a new tab.
tabChange
Event
Internal: it only wires the tab to c-tabs, and stops there. Listen to c-tabs, whose change carries the picked tab’s value.
tabFocus
Event
Internal: it only wires the tab to c-tabs, and stops there. Listen to c-tabs, whose change carries the picked tab’s value.
c-checkbox
3.x
Kind
In 4.x
checked
Attribute
checked is now the boolean view of value: setting it sets value to true-value or false-value, and it reads whether value equals true-value. A bound value wins over a checked attribute, where 3.x checked the box when either said so.
id
Attribute
A plain id on the element itself, as on any element: it no longer reaches the inner control, whose own id lives in the component’s shadow root, out of reach of your page’s for and aria-* anyway. Name the control with its label.
name
Attribute
The attribute works as in 3.x; the property is name (was hostName).
valid
Attribute
Renamed to invalid, with the opposite meaning (ADR-0076): :valid="!error" becomes :invalid="!!error", and markup sets a bare invalid attribute. A leftover valid is ignored, so the error never shows.
validation
Attribute
Renamed to error-message (errorMessage as a property). It has no default text: an invalid control without one keeps showing its hint.
changeValue
Event
Use change: it carries the new value as detail, as changeValue did. In a Vue template bind v-model or @change; in React, onChange.
c-data-table
3.x
Kind
In 4.x
data
Attribute
Rows are plain objects: { name: 'Ada' }, where 3.x wrapped each cell as { name: { value: 'Ada' } }. A cell’s formattedValue, component and children become the column’s cell render function, and align / justify the column’s align. See Component-specific changes.
external-data
Attribute
Renamed to external. Set item-count (itemCount) to the total number of rows, so the pager knows how many pages there are.
footerOptions
Attribute
Removed: the table’s pager has one look. Translate its texts through texts.
headers
Attribute
Replaced by columns: plain domain objects in data, and custom cells as render functions. See Component-specific changes.
hide-footer
Attribute
Removed: the table paginates only while page-size (pageSize) is set. Leave it unset to show every row with no pager.
horizontal-scrolling
Attribute
Removed: a table wider than its container now scrolls sideways by default. Set autohide for what 3.x did without this prop: move the columns that do not fit into an expandable row.
loading-text
Attribute
Moved to texts.loading (the texts object, set as a property).
no-data-text
Attribute
Moved to texts.noData (the texts object, set as a property). For richer content, use the empty slot.
pagination
Attribute
Split into props: page (was currentPage), page-size (pageSize, was itemsPerPage; the table paginates only while it is set), page-sizes (pageSizes) and, with external, item-count (itemCount). textOverrides moves to texts. The table computes startFrom and endTo itself, and has no totalVisible or locale.
selectable
Attribute
Replaced by selection="multiple".
selection-property
Attribute
Replaced by getRowId, a function returning a row’s id, set as a property: (row) => String(row.id). Without it, a row’s id is its index in data, as without selection-property.
single-selection
Attribute
Replaced by selection="single".
sort-by
Attribute
Merged with sort-direction into sort, one object set as a property: sort-by="name" sort-direction="desc" becomes { column: 'name', direction: 'desc' }. Unset, the rows keep their order, where 3.x sorted by the first column.
sort-direction
Attribute
Merged with sort-by into sort, one object set as a property: { column: 'name', direction: 'desc' }. Unset, the rows keep their order, where 3.x sorted ascending.
expand
Event
Replaced by change:expanded: its detail is the ids of every expanded row, where 3.x sent { active, row } for the row that toggled. Look the rows up in your data.
paginate
Event
Replaced by change:page (the page, counting from 1) and change:page-size (the page size). A new page size also fires change:page with 1.
selection
Event
Replaced by change:selected: its detail is the selected rows’ ids, strings from getRowId. The rows themselves are the selectedRows property.
sort
Event
Replaced by change:sort: its detail is { column, direction }, where 3.x sent { sortBy, direction }.
clearSelections
Method
Removed: set selected to [].
getData
Method
Removed: the table no longer hands back its sorted rows. Sort your own data from change:sort where you need that order; selectedRows holds the selected rows.
c-dropdown
3.x
Kind
In 4.x
<c-dropdown>
Tag
Internal. Use c-select, which renders its own panel.
c-input
3.x
Kind
In 4.x
<c-input>
Tag
Internal. Use the field for your value: c-text-field, c-number-field, c-select and so on.
c-link
3.x
Kind
In 4.x
weight
Attribute
Removed (ADR-0006): its inline style beat your stylesheet. Set the weight through the link’s part: c-link::part(root) { font-weight: 400; }.
c-list-item
3.x
Kind
In 4.x
disabled-by-parent
Attribute
Internal: c-list sets it from its disabled. Disable the list, or the item itself.
target
Attribute
Defaults to '', as on a native <a>: an href opens in the same tab. Add target="_blank" where you relied on a new tab.
c-list-item-title
3.x
Kind
In 4.x
active
Attribute
Internal: the c-list-item holding it sets it from its own active.
c-loader
3.x
Kind
In 4.x
contentdelay
Attribute
Renamed to content-delay (contentDelay), in milliseconds: contentdelay="1" becomes content-delay="1000". A leftover contentdelay is ignored, and the message shows without a delay.
c-menu
3.x
Kind
In 4.x
content-class
Attribute
Removed (ADR-0006): style the panel through c-menu::part(panel) and its list through c-menu::part(list).
custom
Attribute
Removed: the menu draws nothing around its trigger. The element you slot as slot="trigger" shows as it is, with no chevron or hover background.
flat
Attribute
Removed: the menu draws nothing around its trigger. The element you slot as slot="trigger" shows as it is, with no chevron or hover background.
items
Attribute
Author the menu with slotted c-menu-item and c-menu-label elements. Activating a leaf item fires select.
items-per-page
Attribute
Removed: the list grows to 80% of the viewport height, then scrolls. Cap it lower with c-menu::part(list) { max-height: 20rem; }.
small
Attribute
Removed: the menu has one size.
default
Slot
The default slot holds the menu’s items (c-menu-item, c-menu-label, c-divider). The trigger, 3.x’s default slot content, moves to slot="trigger": slot your own button there.
c-menu-items
3.x
Kind
In 4.x
<c-menu-items>
Tag
Removed: it was the list c-menu rendered for its items. Style the list through c-menu::part(list).
c-message
3.x
Kind
In 4.x
input-id
Attribute
Removed: it was never read.
valid
Attribute
Renamed to invalid, with the opposite meaning (ADR-0076): :valid="!error" becomes :invalid="!!error", and markup sets a bare invalid attribute. A leftover valid is ignored, so the error never shows.
validation
Attribute
Renamed to error-message (errorMessage as a property). It has no default text: an invalid control without one keeps showing its hint.
c-modal
3.x
Kind
In 4.x
z-index
Attribute
Removed: open modals stack themselves, above the page and below toasts, and a modal opened from another stacks over it. Keep your page’s own z-index values below 1000 so a modal covers them.
changeValue
Event
Use change: it carries false when the modal dismisses itself. In a Vue template bind v-model or @change; in React, onChange.
c-option
3.x
Kind
In 4.x
selected
Attribute
<c-option selected> sets the initial value silently: only while the value is empty, once, and with no event, so a bound v-model or React state does not learn it (3.x emitted changeValue). With a bound value, initialise the model instead.
c-otp-input
3.x
Kind
In 4.x
autofocus
Attribute
The attribute works as in 3.x; the property is autofocus (was hasAutofocus).
id
Attribute
A plain id on the element itself, as on any element: it no longer reaches the inner control, whose own id lives in the component’s shadow root, out of reach of your page’s for and aria-* anyway. Name the control with its label.
valid
Attribute
Renamed to invalid, with the opposite meaning (ADR-0076): :valid="!error" becomes :invalid="!!error", and markup sets a bare invalid attribute. A leftover valid is ignored, so the error never shows.
validation
Attribute
Renamed to error-message (errorMessage as a property). It has no default text: an invalid control without one keeps showing its hint.
changeValue
Event
update:value (onUpdateValue in React) carries the digits entered so far on every change, where changeValue carried null until the code was complete. completion still carries the complete code, and change carries the digits on Enter or when focus leaves them.
reset
Method
Removed: it announced a value set from code. Set value to ''.
c-pagination
3.x
Kind
In 4.x
value
Attribute
Its fields currentPage and itemsPerPage are page and pageSize, and textOverrides is the texts prop: itemsPerPageText → pageSize, prevPage → previousPage, nextPage, pageText({ start, end, count }) → range(start, end, count), pageOfText({ pageNumber, count }) → page(page, pageCount). The pagination never writes into your object: each pick emits a new one, with startFrom and endTo, and nothing is emitted at mount or when you set it.
changeValue
Event
Use change: it carries the new value as detail, as changeValue did. In a Vue template bind v-model or @change; in React, onChange.
c-progress-bar
3.x
Kind
In 4.x
--c-progress-bar-background-color
CSS custom property
Gone: recolour the progress track with ::part(track) { background-color }.
--c-progress-bar-border-width
CSS custom property
Gone: the frame around the bar is the progress track’s padding, ::part(track) { padding }.
--c-progress-bar-color
CSS custom property
Gone: recolour the bar with ::part(bar) { background-color }.
--c-progress-bar-height
CSS custom property
Gone: size the progress track with ::part(track) { height }; the bar fills it inside its frame.
c-radio
3.x
Kind
In 4.x
checked
Attribute
Removed: set the group’s value to the radio’s value.
c-radio-group
3.x
Kind
In 4.x
color
Attribute
Removed: it was never read. Recolour a radio through c-radio::part(indicator); its color tints the ring, the dot and the focus ring.
id
Attribute
A plain id on the element itself, as on any element: it no longer reaches the inner control, whose own id lives in the component’s shadow root, out of reach of your page’s for and aria-* anyway. Name the control with its label.
items
Attribute
Removed: author the options as slotted <c-radio value="…">Label</c-radio> elements, with disabled on a radio that cannot be picked.
return-object
Attribute
Removed with items: the value is the picked radio’s value. Look your object up from it.
valid
Attribute
Renamed to invalid, with the opposite meaning (ADR-0076): :valid="!error" becomes :invalid="!!error", and markup sets a bare invalid attribute. A leftover valid is ignored, so the error never shows.
validation
Attribute
Renamed to error-message (errorMessage as a property). It has no default text: an invalid control without one keeps showing its hint.
value
Attribute
A string, the picked radio’s value, or null with none picked. A number still picks the radio whose value matches it, but the events carry the string ('1', not 1).
changeValue
Event
Use change: it carries the new value as detail, as changeValue did. In a Vue template bind v-model or @change; in React, onChange.
c-ripple
3.x
Kind
In 4.x
<c-ripple>
Tag
Removed: it was internal in 3.x.
c-row
3.x
Kind
In 4.x
<c-row>
Tag
Removed. Use your own flex container (display: flex plus gap).
c-select
3.x
Kind
In 4.x
id
Attribute
A plain id on the element itself, as on any element: it no longer reaches the inner control, whose own id lives in the component’s shadow root, out of reach of your page’s for and aria-* anyway. Name the control with its label.
valid
Attribute
Renamed to invalid, with the opposite meaning (ADR-0076): :valid="!error" becomes :invalid="!!error", and markup sets a bare invalid attribute. A leftover valid is ignored, so the error never shows.
validate
Attribute
Removed: it was never wired to anything. Keep validation in your app and show its result with error-message.
validate-on-blur
Attribute
Removed: it was never wired to anything. Keep validation in your app and show its result with error-message.
validation
Attribute
Renamed to error-message (errorMessage as a property). It has no default text: an invalid control without one keeps showing its hint.
changeValue
Event
Use change: it carries the new value as detail, as changeValue did. In a Vue template bind v-model or @change; in React, onChange.
reset
Method
Removed: it announced a value set from outside, which no value control does any more. Set value to null ([] with multiple).
c-side-navigation
3.x
Kind
In 4.x
menu-visible
Attribute
Renamed to open. The drawer fires change:open with the new state whenever the user opens or closes it — the navigation button, the close button, the backdrop or an item.
styles
Attribute
Removed (ADR-0006): it wrote inline styles. Restyle the drawer through its parts, e.g. c-side-navigation::part(nav).
c-side-navigation-item
3.x
Kind
In 4.x
itemChange
Event
Renamed to select, as on c-menu: its detail is { value }, the item’s new value prop, instead of the originating DOM event. It bubbles, so one listener on c-side-navigation can handle every item; c-sub-navigation-item fires it too.
c-slider
3.x
Kind
In 4.x
aria-label
Attribute
The attribute works as in 3.x and names the range input; there is no property for it any more (it was ariaLabelInternal), so set the attribute.
id
Attribute
A plain id on the element itself, as on any element: it no longer reaches the inner control, whose own id lives in the component’s shadow root, out of reach of your page’s for and aria-* anyway. Name the control with its label.
max
Attribute
A number, and its events carry numbers. Attributes still work: max="8" reads as 8.
min
Attribute
A number, and its events carry numbers. Attributes still work: max="8" reads as 8.
name
Attribute
The attribute works as in 3.x; the property is name (was hostName).
segments
Attribute
A number, and its events carry numbers. Attributes still work: max="8" reads as 8.
step
Attribute
A number, and its events carry numbers. Attributes still work: max="8" reads as 8.
unit
Attribute
Defaults to no unit (it was %). Add unit="%" to show a percentage.
value
Attribute
A number, and its events carry numbers. Attributes still work: max="8" reads as 8.
changeValue
Event
update:value (onUpdateValue in React) carries the value on every move, as changeValue did; change carries it once on release, and on each arrow-key step. In a Vue template bind v-model, or @input reading the element’s value.
c-spacer
3.x
Kind
In 4.x
<c-spacer>
Tag
Removed. Give the element you want pushed to the far edge margin-inline-start: auto, or use your own flex-grow filler.
c-spinner
3.x
Kind
In 4.x
color
Attribute
Defaults to var(--c-primary), the theme’s primary colour, which follows dark mode. It was the palette step var(--c-primary-600).
c-step
3.x
Kind
In 4.x
complete
Attribute
Internal: c-steps sets it from its value, the current step’s number.
current
Attribute
Internal: c-steps sets it from its value, the current step’s number.
c-steps
3.x
Kind
In 4.x
value
Attribute
Typed number (the current step, counting from 1). An attribute still works: value="3" reads as 3.
changeValue
Event
Removed: 3.x declared it but never dispatched it.
c-sub-navigation-item
3.x
Kind
In 4.x
focusable
Attribute
Internal: the parent c-side-navigation-item takes the sub-items of a collapsed item out of the tab order.
c-swiper
3.x
Kind
In 4.x
<c-swiper>
Tag
Removed, with no replacement.
c-swiper-tab
3.x
Kind
In 4.x
<c-swiper-tab>
Tag
Removed with c-swiper, with no replacement.
c-switch
3.x
Kind
In 4.x
checked
Attribute
checked is now the boolean view of value: setting it sets value to true-value or false-value, and it reads whether value equals true-value. A bound value wins over a checked attribute, where 3.x checked the box when either said so.
disabled
Attribute
The attribute works as in 3.x; the property is disabled (was hostDisabled).
id
Attribute
A plain id on the element itself, as on any element: it no longer reaches the inner control, whose own id lives in the component’s shadow root, out of reach of your page’s for and aria-* anyway. Name the control with its label.
changeValue
Event
Use change: it carries the new value as detail, as changeValue did. In a Vue template bind v-model or @change; in React, onChange.
label
Slot
There never was a label slot: 3.x’s docs gave the default slot that name. The label text goes inside the element, as before, or in the new label prop.
c-tab
3.x
Kind
In 4.x
active
Attribute
Internal: c-tabs sets it from its value.
id
Attribute
A plain id on the tab, as on any element. c-tabs keeps it for aria-controls and generates one only for a tab without one.
position
Attribute
Removed: the browser counts the tabs of a c-tabs itself, for aria-posinset and aria-setsize.
setsize
Attribute
Removed: the browser counts the tabs of a c-tabs itself, for aria-posinset and aria-setsize.
tabChange
Event
Internal: it only wires the tab to c-tabs, and stops there. Listen to c-tabs, whose change carries the picked tab’s value.
tabFocus
Event
Internal: it only wires the tab to c-tabs, and stops there. Listen to c-tabs, whose change carries the picked tab’s value.
c-tab-buttons
3.x
Kind
In 4.x
disabled
Attribute
The attribute works as in 3.x; the property is disabled (was hostDisabled).
mandatory
Attribute
Standalone use moves to c-button-group (same markup); c-tab-buttons is now only the tab strip inside c-tabs. See Component-specific changes.
tabs
Attribute
Removed: c-tabs set it (it was private in 3.x). Inside c-tabs nothing changes; standalone use moves to c-button-group.
value
Attribute
Internal: c-tabs sets it from its own value. Standalone use moves to c-button-group; see Component-specific changes.
changeValue
Event
Standalone use moves to c-button-group, which fires change, update:value and input. Deselecting emits null (was '').
c-tab-item
3.x
Kind
In 4.x
active
Attribute
Internal: c-tabs sets it from its value.
contentChange
Event
Internal: it only tells c-tab-items to re-measure, and stops there. Nothing to listen to.
c-tab-items
3.x
Kind
In 4.x
disable-animation
Attribute
Internal: c-tabs sets it from its own disable-animation.
value
Attribute
Internal: c-tabs sets it from its own value.
c-tabs
3.x
Kind
In 4.x
value
Attribute
Setting value from code no longer fires an event (3.x fired changeValue): the value events report what the user does.
changeValue
Event
Use change: it carries the new value as detail, as changeValue did. In a Vue template bind v-model or @change; in React, onChange.
c-tag
3.x
Kind
In 4.x
block
Attribute
Removed. To make a tag fill its row, widen the element and let its box grow: c-tag { width: 100%; } c-tag::part(root) { flex-grow: 1; }.
fit
Attribute
Removed. To stretch a tag over the free space of its c-tags row, let the element and its box grow: c-tag, c-tag::part(root) { flex-grow: 1; }.
c-text-field
3.x
Kind
In 4.x
autocapitalize
Attribute
The attribute works as in 3.x; the property is autocapitalize (was automaticCapitalize), typed as the values the browser knows.
autocorrect
Attribute
Typed as the native values, on and off, so autocorrect="off" works as in 3.x. The property also takes true and false, like the platform’s autocorrect.
autofocus
Attribute
The attribute works as in 3.x; the property is autofocus (was automaticFocus).
id
Attribute
A plain id on the element itself, as on any element: it no longer reaches the inner control, whose own id lives in the component’s shadow root, out of reach of your page’s for and aria-* anyway. Name the control with its label.
type
Attribute
Typed as the types the field is built for: text, email, password, search, tel, url, number and date. The others have their own components: c-time-picker, c-color-picker, c-slider, c-file-upload, and c-date-picker for a month.
valid
Attribute
Renamed to invalid, with the opposite meaning (ADR-0076): :valid="!error" becomes :invalid="!!error", and markup sets a bare invalid attribute. A leftover valid is ignored, so the error never shows.
validate
Attribute
Removed: it was never wired to anything. Keep validation in your app and show its result with error-message.
validate-on-blur
Attribute
Removed: it was never wired to anything. Keep validation in your app and show its result with error-message.
validation
Attribute
Renamed to error-message (errorMessage as a property). It has no default text: an invalid control without one keeps showing its hint.
changeValue
Event
update:value (onUpdateValue in React) carries the text on every keystroke, as changeValue did; change carries it when it is committed (Enter, or leaving the field). In a Vue template bind v-model, or @input reading the element’s value.
c-text-field-open
3.x
Kind
In 4.x
<c-text-field-open>
Tag
Removed: use c-text-field with a slotted <input> — the page’s own input, which every password manager can fill and a native <form> submits: <c-text-field label="Password"><input autocomplete="current-password" name="password" type="password"></c-text-field>. The input’s own attributes apply.
c-toast
3.x
Kind
In 4.x
<c-toast>
Tag
Internal: c-toasts renders one per addToast() message. Style a toast through c-toasts::part(toast-root) and the other toast-* parts, listen to close on c-toasts (the detail is the message), and close one with removeToast(id), where closeToast() was.