CSC Design System v4.0.0
VueFlavour Vue React Angular TypeScript
Flavour Vue React Angular TypeScript
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.

3.x documentation (archived, unsupported) →

Update the packages

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.

pnpm remove @cscfi/csc-ui-vue
pnpm add @cscfi/csc-ui@^4

Update registration & imports

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.

Before — 3.x
<template>
  <!-- v-control bridged Stencil's changeValue to v-model -->
  <c-text-field v-model="name" v-control label="Name" />
  <c-switch v-model="enabled" v-control>Notifications</c-switch>
</template>
After — 4.x
<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).

Before — 3.x
c-button {
  --c-button-background-color: #006efd;
  --c-button-border-radius: 4px;
}
After — 4.x
c-button::part(root) {
  background: var(--c-primary);
  border-radius: 4px;
}

How ::part() restyling works →

Theming & dark mode

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.

Before — 3.x
:root {
  /* Override individual ramp steps; light mode only. */
  --c-primary-500: #006efd;
  --c-primary-600: #005fd6;
}
After — 4.x
import { applyTheme } from '@cscfi/csc-ui';

// One step-500 seed per family; ramps and dark mode derive from it.
applyTheme({ primary: '#006efd' });

Full theming & dark-mode guide →

Component-specific changes

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.xKindIn 4.x
allCSS custom propertyPer-component CSS custom properties are gone. Restyle the component’s parts with ::part(); see Styling & customization.

c-accordion

3.xKindIn 4.x
valueAttributeAlso 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.
changeValueEventUse 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.xKindIn 4.x
collapsableAttributeInternal: c-accordion sets it from its mandatory.
expandedAttributeInternal: 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).
outlinedAttributeInternal: set outlined on c-accordion.
itemChangeEventInternal: it only wires the item to c-accordion, and stops there. Listen to c-accordion, whose change carries the expanded value.
headerSlotRenamed to heading (the glossary’s name, as the heading prop). A leftover slot="header" matches no slot, so its content disappears.

c-alert

3.xKindIn 4.x
titleSlotRenamed to heading, like the heading prop that sets plain text. A leftover slot="title" matches no slot, so its content disappears.

c-autocomplete

3.xKindIn 4.x
idAttributeA 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-lengthAttributeRemoved 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-messageAttributeRemoved 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-messageAttributeMoved to texts.noResults (the texts object, set as a property).
queryAttributeRemoved 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.
validAttributeRenamed 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.
validateAttributeRemoved: it was never wired to anything. Keep validation in your app and show its result with error-message.
validate-on-blurAttributeRemoved: it was never wired to anything. Keep validation in your app and show its result with error-message.
validationAttributeRenamed to error-message (errorMessage as a property). It has no default text: an invalid control without one keeps showing its hint.
changeQueryEventRemoved with the query API. For an async data source, set external and listen to change:query; the detail is the query.
changeValueEventUse change: it carries the new value as detail, as changeValue did. In a Vue template bind v-model or @change; in React, onChange.
resetMethodRemoved: it announced a value set from outside, which no value control does any more. Set value to null ([] with multiple).

c-backdrop

3.xKindIn 4.x
<c-backdrop>TagRemoved: it was internal in 3.x.

c-button

3.xKindIn 4.x
groupedAttributeRemoved: 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.
idAttributeA 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.
tabsAttributeRemoved: 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.
targetAttributeDefaults to '', as on a native <a>: an href opens in the same tab. Add target="_blank" where you relied on a new tab.
tabChangeEventInternal: it only wires the tab to c-tabs, and stops there. Listen to c-tabs, whose change carries the picked tab’s value.
tabFocusEventInternal: 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.xKindIn 4.x
checkedAttributechecked 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.
idAttributeA 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.
nameAttributeThe attribute works as in 3.x; the property is name (was hostName).
validAttributeRenamed 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.
validationAttributeRenamed to error-message (errorMessage as a property). It has no default text: an invalid control without one keeps showing its hint.
changeValueEventUse 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.xKindIn 4.x
dataAttributeRows 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-dataAttributeRenamed to external. Set item-count (itemCount) to the total number of rows, so the pager knows how many pages there are.
footerOptionsAttributeRemoved: the table’s pager has one look. Translate its texts through texts.
headersAttributeReplaced by columns: plain domain objects in data, and custom cells as render functions. See Component-specific changes.
hide-footerAttributeRemoved: the table paginates only while page-size (pageSize) is set. Leave it unset to show every row with no pager.
horizontal-scrollingAttributeRemoved: 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-textAttributeMoved to texts.loading (the texts object, set as a property).
no-data-textAttributeMoved to texts.noData (the texts object, set as a property). For richer content, use the empty slot.
paginationAttributeSplit 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.
selectableAttributeReplaced by selection="multiple".
selection-propertyAttributeReplaced 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-selectionAttributeReplaced by selection="single".
sort-byAttributeMerged 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-directionAttributeMerged 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.
expandEventReplaced 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.
paginateEventReplaced 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.
selectionEventReplaced by change:selected: its detail is the selected rows’ ids, strings from getRowId. The rows themselves are the selectedRows property.
sortEventReplaced by change:sort: its detail is { column, direction }, where 3.x sent { sortBy, direction }.
clearSelectionsMethodRemoved: set selected to [].
getDataMethodRemoved: 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.xKindIn 4.x
<c-dropdown>TagInternal. Use c-select, which renders its own panel.

c-input

3.xKindIn 4.x
<c-input>TagInternal. Use the field for your value: c-text-field, c-number-field, c-select and so on.
3.xKindIn 4.x
weightAttributeRemoved (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.xKindIn 4.x
disabled-by-parentAttributeInternal: c-list sets it from its disabled. Disable the list, or the item itself.
targetAttributeDefaults 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.xKindIn 4.x
activeAttributeInternal: the c-list-item holding it sets it from its own active.

c-loader

3.xKindIn 4.x
contentdelayAttributeRenamed 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.xKindIn 4.x
content-classAttributeRemoved (ADR-0006): style the panel through c-menu::part(panel) and its list through c-menu::part(list).
customAttributeRemoved: the menu draws nothing around its trigger. The element you slot as slot="trigger" shows as it is, with no chevron or hover background.
flatAttributeRemoved: the menu draws nothing around its trigger. The element you slot as slot="trigger" shows as it is, with no chevron or hover background.
itemsAttributeAuthor the menu with slotted c-menu-item and c-menu-label elements. Activating a leaf item fires select.
items-per-pageAttributeRemoved: the list grows to 80% of the viewport height, then scrolls. Cap it lower with c-menu::part(list) { max-height: 20rem; }.
smallAttributeRemoved: the menu has one size.
defaultSlotThe 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.xKindIn 4.x
<c-menu-items>TagRemoved: it was the list c-menu rendered for its items. Style the list through c-menu::part(list).

c-message

3.xKindIn 4.x
input-idAttributeRemoved: it was never read.
validAttributeRenamed 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.
validationAttributeRenamed to error-message (errorMessage as a property). It has no default text: an invalid control without one keeps showing its hint.

c-modal

3.xKindIn 4.x
z-indexAttributeRemoved: 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.
changeValueEventUse change: it carries false when the modal dismisses itself. In a Vue template bind v-model or @change; in React, onChange.

c-option

3.xKindIn 4.x
selectedAttribute<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.xKindIn 4.x
autofocusAttributeThe attribute works as in 3.x; the property is autofocus (was hasAutofocus).
idAttributeA 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.
validAttributeRenamed 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.
validationAttributeRenamed to error-message (errorMessage as a property). It has no default text: an invalid control without one keeps showing its hint.
changeValueEventupdate: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.
resetMethodRemoved: it announced a value set from code. Set value to ''.

c-pagination

3.xKindIn 4.x
valueAttributeIts 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.
changeValueEventUse 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.xKindIn 4.x
--c-progress-bar-background-colorCSS custom propertyGone: recolour the progress track with ::part(track) { background-color }.
--c-progress-bar-border-widthCSS custom propertyGone: the frame around the bar is the progress track’s padding, ::part(track) { padding }.
--c-progress-bar-colorCSS custom propertyGone: recolour the bar with ::part(bar) { background-color }.
--c-progress-bar-heightCSS custom propertyGone: size the progress track with ::part(track) { height }; the bar fills it inside its frame.

c-radio

3.xKindIn 4.x
checkedAttributeRemoved: set the group’s value to the radio’s value.

c-radio-group

3.xKindIn 4.x
colorAttributeRemoved: it was never read. Recolour a radio through c-radio::part(indicator); its color tints the ring, the dot and the focus ring.
idAttributeA 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.
itemsAttributeRemoved: author the options as slotted <c-radio value="…">Label</c-radio> elements, with disabled on a radio that cannot be picked.
return-objectAttributeRemoved with items: the value is the picked radio’s value. Look your object up from it.
validAttributeRenamed 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.
validationAttributeRenamed to error-message (errorMessage as a property). It has no default text: an invalid control without one keeps showing its hint.
valueAttributeA 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).
changeValueEventUse 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.xKindIn 4.x
<c-ripple>TagRemoved: it was internal in 3.x.

c-row

3.xKindIn 4.x
<c-row>TagRemoved. Use your own flex container (display: flex plus gap).

c-select

3.xKindIn 4.x
idAttributeA 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.
validAttributeRenamed 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.
validateAttributeRemoved: it was never wired to anything. Keep validation in your app and show its result with error-message.
validate-on-blurAttributeRemoved: it was never wired to anything. Keep validation in your app and show its result with error-message.
validationAttributeRenamed to error-message (errorMessage as a property). It has no default text: an invalid control without one keeps showing its hint.
changeValueEventUse change: it carries the new value as detail, as changeValue did. In a Vue template bind v-model or @change; in React, onChange.
resetMethodRemoved: it announced a value set from outside, which no value control does any more. Set value to null ([] with multiple).

c-side-navigation

3.xKindIn 4.x
menu-visibleAttributeRenamed 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.
stylesAttributeRemoved (ADR-0006): it wrote inline styles. Restyle the drawer through its parts, e.g. c-side-navigation::part(nav).

c-side-navigation-item

3.xKindIn 4.x
itemChangeEventRenamed 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.xKindIn 4.x
aria-labelAttributeThe 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.
idAttributeA 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.
maxAttributeA number, and its events carry numbers. Attributes still work: max="8" reads as 8.
minAttributeA number, and its events carry numbers. Attributes still work: max="8" reads as 8.
nameAttributeThe attribute works as in 3.x; the property is name (was hostName).
segmentsAttributeA number, and its events carry numbers. Attributes still work: max="8" reads as 8.
stepAttributeA number, and its events carry numbers. Attributes still work: max="8" reads as 8.
unitAttributeDefaults to no unit (it was %). Add unit="%" to show a percentage.
valueAttributeA number, and its events carry numbers. Attributes still work: max="8" reads as 8.
changeValueEventupdate: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.xKindIn 4.x
<c-spacer>TagRemoved. Give the element you want pushed to the far edge margin-inline-start: auto, or use your own flex-grow filler.

c-spinner

3.xKindIn 4.x
colorAttributeDefaults 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.xKindIn 4.x
completeAttributeInternal: c-steps sets it from its value, the current step’s number.
currentAttributeInternal: c-steps sets it from its value, the current step’s number.

c-steps

3.xKindIn 4.x
valueAttributeTyped number (the current step, counting from 1). An attribute still works: value="3" reads as 3.
changeValueEventRemoved: 3.x declared it but never dispatched it.

c-sub-navigation-item

3.xKindIn 4.x
focusableAttributeInternal: the parent c-side-navigation-item takes the sub-items of a collapsed item out of the tab order.

c-swiper

3.xKindIn 4.x
<c-swiper>TagRemoved, with no replacement.

c-swiper-tab

3.xKindIn 4.x
<c-swiper-tab>TagRemoved with c-swiper, with no replacement.

c-switch

3.xKindIn 4.x
checkedAttributechecked 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.
disabledAttributeThe attribute works as in 3.x; the property is disabled (was hostDisabled).
idAttributeA 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.
changeValueEventUse change: it carries the new value as detail, as changeValue did. In a Vue template bind v-model or @change; in React, onChange.
labelSlotThere 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.xKindIn 4.x
activeAttributeInternal: c-tabs sets it from its value.
idAttributeA 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.
positionAttributeRemoved: the browser counts the tabs of a c-tabs itself, for aria-posinset and aria-setsize.
setsizeAttributeRemoved: the browser counts the tabs of a c-tabs itself, for aria-posinset and aria-setsize.
tabChangeEventInternal: it only wires the tab to c-tabs, and stops there. Listen to c-tabs, whose change carries the picked tab’s value.
tabFocusEventInternal: 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.xKindIn 4.x
disabledAttributeThe attribute works as in 3.x; the property is disabled (was hostDisabled).
mandatoryAttributeStandalone use moves to c-button-group (same markup); c-tab-buttons is now only the tab strip inside c-tabs. See Component-specific changes.
tabsAttributeRemoved: c-tabs set it (it was private in 3.x). Inside c-tabs nothing changes; standalone use moves to c-button-group.
valueAttributeInternal: c-tabs sets it from its own value. Standalone use moves to c-button-group; see Component-specific changes.
changeValueEventStandalone use moves to c-button-group, which fires change, update:value and input. Deselecting emits null (was '').

c-tab-item

3.xKindIn 4.x
activeAttributeInternal: c-tabs sets it from its value.
contentChangeEventInternal: it only tells c-tab-items to re-measure, and stops there. Nothing to listen to.

c-tab-items

3.xKindIn 4.x
disable-animationAttributeInternal: c-tabs sets it from its own disable-animation.
valueAttributeInternal: c-tabs sets it from its own value.

c-tabs

3.xKindIn 4.x
valueAttributeSetting value from code no longer fires an event (3.x fired changeValue): the value events report what the user does.
changeValueEventUse 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.xKindIn 4.x
blockAttributeRemoved. 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; }.
fitAttributeRemoved. 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.xKindIn 4.x
autocapitalizeAttributeThe attribute works as in 3.x; the property is autocapitalize (was automaticCapitalize), typed as the values the browser knows.
autocorrectAttributeTyped 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.
autofocusAttributeThe attribute works as in 3.x; the property is autofocus (was automaticFocus).
idAttributeA 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.
typeAttributeTyped 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.
validAttributeRenamed 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.
validateAttributeRemoved: it was never wired to anything. Keep validation in your app and show its result with error-message.
validate-on-blurAttributeRemoved: it was never wired to anything. Keep validation in your app and show its result with error-message.
validationAttributeRenamed to error-message (errorMessage as a property). It has no default text: an invalid control without one keeps showing its hint.
changeValueEventupdate: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.xKindIn 4.x
<c-text-field-open>TagRemoved: 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.xKindIn 4.x
<c-toast>TagInternal: 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.