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

<c-tree-select>

A hierarchical value-selection component: a readonly value field that opens a panel for browsing a tree one level at a time, or searching it as a whole, to commit one item.

Usage

Items

The tree is the items property: an array of { value, name } entries where an entry with a non-empty children array is a branch and any other entry is a leaf. Values must be unique across the whole tree. An optional code — a classification number, say — is shown before the name in a muted column and is matched by the search. Arrays have no attribute form, so bind items as a DOM property (:items="…" in Vue; the React wrapper and property assignment do this naturally):

const items: CTreeSelectItem[] = [
  {
    value: '1',
    code: '1',
    name: 'Natural sciences',
    children: [
      {
        value: '111',
        code: '111',
        name: 'Mathematics',
        children: [{ value: '1111', code: '1111', name: 'Pure mathematics' }],
      },
    ],
  },
];

A disabled branch cannot be entered and a disabled leaf cannot be committed; both render as disabled rows, and the items below a disabled branch are listed disabled in search results.

The value is the committed item's value, or null when nothing is committed. With return-object the value is a fresh { value, name, code, path } object instead — path holds the item's ancestors root-first, each as { value, name, code } — never the items entry itself, and never its children. The closed field shows the committed item's path on a muted line above its code and name.

Browsing and searching

The panel lists one level at a time: the top-level items first, then the children of whichever branch is picked, with a breadcrumb above the list — the root crumb ("All") followed by one crumb per ancestor — for climbing back. The header names the level being chosen: give level-labels an array of names, top level first ("Main field", "Field", "Subfield"), and it reads "Choose Field"; a level without a name reads "Choose Level 2". While the tree is evenly deep — every leaf at the same level — the header also counts the levels ("Step 2 of 3"); in an unevenly deep tree the counter is left out, and a level made only of leaves says "Final level" instead. Reopening the panel returns to the committed item's level with its row selected, so its siblings are one click away.

Typing into the search input switches the panel to a flat list of matches from the whole tree, each with its path on a second line. The query is matched case-insensitively anywhere in the name or code of an item and of every ancestor above it, so a query matching a branch lists all of its leaves. Supply a filter predicate to change the matching — it receives the item, the query and the item's ancestors, and lists the item when it returns true. Because filter is a function, it must be bound as a DOM property. Deleting the query, or the "Browse instead" control in the header, returns to the level the user was browsing.

While a query is typed, the runs of each row's code, label and path that equal it are marked. The marks are the match part, the path line the path part and the code column the code part:

c-tree-select::part(match) {
  font-weight: 600;
}

From the keyboard, ArrowDown and ArrowUp move through the rows and Enter activates one: a branch descends, a leaf commits. ArrowRight descends into a highlighted branch and ArrowLeft — or Backspace with nothing left to delete — climbs one level. Escape closes the panel and returns focus to the field; Tab closes it and moves on.

Committing a branch

By default only a leaf can be committed; a branch always opens its children. Set allow-branch to let a branch be the value as well: every level below the root then starts with a pinned select-branch row ("Select Natural sciences") that commits the branch the user is in, and branches matching a query are listed as search results and commit directly. The pinned row is the select-branch part.

Texts

Every built-in string — the root crumb, the header texts, a branch row's child count, the select-branch row's label, the "Browse instead" control, the no-results row, the search input's placeholder and accessible label, the clear and toggle button labels — can be replaced for another language through the texts object, merged over the English defaults. Interpolated texts are functions, so the object must be bound as a DOM property; the placeholder prop still wins over texts.searchPlaceholder when both are set:

<c-tree-select
  :texts="{
    root: 'Kaikki',
    choose: (level) => `Valitse ${level}`,
    children: (count) => `${count} alakohtaa`,
  }"
/>

To translate every tree select at once, set texts app-wide with applyDefaults({ 'c-tree-select': { texts } }) (Customization → App-wide prop defaults); a per-instance texts still wins key by key.

Scrolling

The panel shows items-per-page full rows (six by default) and then a half-visible row instead of a scrollbar: the cut row is the cue that more items follow, and the wheel, touch and arrow keys scroll as usual. Set items-per-page="0" to let the list grow to the space the panel allows; it still ends on a half row when it overflows. To bring the native scrollbar back:

c-tree-select::part(list) {
  scrollbar-width: auto;
}

Narrow viewports

On a viewport narrower than 760px the panel opens as a fullscreen panel instead of anchoring under the field: a heading row with the field's label and a close button, the search input beneath it, then the items filling the rest of the screen. The panel keeps covering the screen and the rows above the items stay in view while the on-screen keyboard is open; the close button and Escape both return focus to the field; the page behind the panel is inert until it closes, and the list has no half-row cut — the screen edge is the cue. The threshold is the viewport's width, never the field's, so a narrow field on a desktop keeps its anchored panel. The close button's label is the closePanel text, and the row's parts are heading-row, heading and close:

c-tree-select::part(heading-row) {
  border-bottom-color: var(--c-primary);
}

Lazily loaded trees

The component walks the items you give it and has no loading state of its own: there is no external mode and no per-branch fetch event yet. A tree that arrives in pieces can still be shown by re-assigning items with the fetched children filled in — the panel keeps its level and re-homes the highlight when the tree changes. A branch must already list its children to be enterable, so load at least one level ahead of the user.

Examples

Basic
Vue React Angular TypeScript
<template>
  <div>
    <c-tree-select
      v-model="field"
      :items
      :level-labels
      hint="Browse the levels or type to search"
      label="Field of science"
      placeholder="Search by name or code"
      clearable
    />

    <p>Value: {{ field ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import type { CTreeSelectItem } from '@cscfi/csc-ui';

import { ref } from 'vue';

const items: CTreeSelectItem[] = [
  {
    children: [
      {
        children: [
          { code: '1111', name: 'Pure mathematics', value: '1111' },
          { code: '1112', name: 'Applied mathematics', value: '1112' },
          { code: '1113', name: 'Statistics and probability', value: '1113' },
        ],
        code: '111',
        name: 'Mathematics',
        value: '111',
      },
      {
        children: [
          { code: '1131', name: 'Computer science', value: '1131' },
          { code: '1132', name: 'Information systems', value: '1132' },
          { code: '1133', name: 'Software engineering', value: '1133' },
        ],
        code: '113',
        name: 'Computer and information sciences',
        value: '113',
      },
      {
        children: [
          { code: '1141', name: 'Particle physics', value: '1141' },
          { code: '1142', name: 'Condensed matter physics', value: '1142' },
          { code: '1143', name: 'Astronomy and space science', value: '1143' },
        ],
        code: '114',
        name: 'Physical sciences',
        value: '114',
      },
    ],
    code: '1',
    name: 'Natural sciences',
    value: '1',
  },
  {
    children: [
      {
        children: [
          { code: '2131', name: 'Electronics', value: '2131' },
          {
            code: '2132',
            name: 'Automation and systems engineering',
            value: '2132',
          },
          { code: '2133', name: 'Telecommunications', value: '2133' },
        ],
        code: '213',
        name: 'Electronic, automation and communications engineering',
        value: '213',
      },
      {
        children: [
          { code: '2171', name: 'Biomedical engineering', value: '2171' },
          { code: '2172', name: 'Medical imaging', value: '2172' },
        ],
        code: '217',
        name: 'Medical engineering',
        value: '217',
      },
    ],
    code: '2',
    name: 'Engineering and technology',
    value: '2',
  },
  {
    children: [
      {
        children: [
          { code: '3111', name: 'Cell and molecular biology', value: '3111' },
          { code: '3112', name: 'Neurosciences', value: '3112' },
        ],
        code: '311',
        name: 'Biomedicine',
        value: '311',
      },
      {
        children: [
          { code: '3121', name: 'Internal medicine', value: '3121' },
          { code: '3122', name: 'Cancers', value: '3122' },
          { code: '3123', name: 'Gynaecology and paediatrics', value: '3123' },
        ],
        code: '312',
        name: 'Clinical medicine',
        value: '312',
      },
    ],
    code: '3',
    name: 'Medical and health sciences',
    value: '3',
  },
];

const levelLabels = ['main field', 'field', 'subfield'];

const field = ref<null | string>(null);
</script>
Custom filter
Vue React Angular TypeScript
<template>
  <div>
    <c-tree-select
      v-model="field"
      :filter
      :items
      :level-labels
      hint="Matches an item's own code prefix or name"
      label="Field of science"
      placeholder="Type a code prefix or a name"
      clearable
    />

    <p>Value: {{ field ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import type { CTreeSelectFilter, CTreeSelectItem } from '@cscfi/csc-ui';

import { ref } from 'vue';

const items: CTreeSelectItem[] = [
  {
    children: [
      {
        children: [
          { code: '1111', name: 'Pure mathematics', value: '1111' },
          { code: '1112', name: 'Applied mathematics', value: '1112' },
          { code: '1113', name: 'Statistics and probability', value: '1113' },
        ],
        code: '111',
        name: 'Mathematics',
        value: '111',
      },
      {
        children: [
          { code: '1131', name: 'Computer science', value: '1131' },
          { code: '1132', name: 'Information systems', value: '1132' },
          { code: '1133', name: 'Software engineering', value: '1133' },
        ],
        code: '113',
        name: 'Computer and information sciences',
        value: '113',
      },
      {
        children: [
          { code: '1141', name: 'Particle physics', value: '1141' },
          { code: '1142', name: 'Condensed matter physics', value: '1142' },
          { code: '1143', name: 'Astronomy and space science', value: '1143' },
        ],
        code: '114',
        name: 'Physical sciences',
        value: '114',
      },
    ],
    code: '1',
    name: 'Natural sciences',
    value: '1',
  },
  {
    children: [
      {
        children: [
          { code: '2131', name: 'Electronics', value: '2131' },
          {
            code: '2132',
            name: 'Automation and systems engineering',
            value: '2132',
          },
          { code: '2133', name: 'Telecommunications', value: '2133' },
        ],
        code: '213',
        name: 'Electronic, automation and communications engineering',
        value: '213',
      },
      {
        children: [
          { code: '2171', name: 'Biomedical engineering', value: '2171' },
          { code: '2172', name: 'Medical imaging', value: '2172' },
        ],
        code: '217',
        name: 'Medical engineering',
        value: '217',
      },
    ],
    code: '2',
    name: 'Engineering and technology',
    value: '2',
  },
  {
    children: [
      {
        children: [
          { code: '3111', name: 'Cell and molecular biology', value: '3111' },
          { code: '3112', name: 'Neurosciences', value: '3112' },
        ],
        code: '311',
        name: 'Biomedicine',
        value: '311',
      },
      {
        children: [
          { code: '3121', name: 'Internal medicine', value: '3121' },
          { code: '3122', name: 'Cancers', value: '3122' },
          { code: '3123', name: 'Gynaecology and paediatrics', value: '3123' },
        ],
        code: '312',
        name: 'Clinical medicine',
        value: '312',
      },
    ],
    code: '3',
    name: 'Medical and health sciences',
    value: '3',
  },
];

const levelLabels = ['main field', 'field', 'subfield'];

// The default search matches the query anywhere in the name or code of an
// item and of its ancestors. This one matches the item's own code by prefix
// and its own name anywhere — so "11" lists Mathematics and its subfields,
// but "Natural" lists only the main field itself.
const filter: CTreeSelectFilter = (item, query) => {
  const q = query.trim().toLowerCase();

  return !!item.code?.startsWith(q) || item.name.toLowerCase().includes(q);
};

const field = ref<null | string>(null);
</script>
Return object
Vue React Angular TypeScript
<template>
  <div>
    <c-tree-select
      v-model="field"
      :items
      :level-labels
      hint="The value is the item with its path"
      label="Field of science"
      clearable
      return-object
    />

    <pre>{{ JSON.stringify(field, null, 2) }}</pre>
  </div>
</template>

<script setup lang="ts">
import type { CTreeSelectItem, CTreeSelectSelection } from '@cscfi/csc-ui';

import { ref } from 'vue';

const items: CTreeSelectItem[] = [
  {
    children: [
      {
        children: [
          { code: '1111', name: 'Pure mathematics', value: '1111' },
          { code: '1112', name: 'Applied mathematics', value: '1112' },
          { code: '1113', name: 'Statistics and probability', value: '1113' },
        ],
        code: '111',
        name: 'Mathematics',
        value: '111',
      },
      {
        children: [
          { code: '1131', name: 'Computer science', value: '1131' },
          { code: '1132', name: 'Information systems', value: '1132' },
          { code: '1133', name: 'Software engineering', value: '1133' },
        ],
        code: '113',
        name: 'Computer and information sciences',
        value: '113',
      },
      {
        children: [
          { code: '1141', name: 'Particle physics', value: '1141' },
          { code: '1142', name: 'Condensed matter physics', value: '1142' },
          { code: '1143', name: 'Astronomy and space science', value: '1143' },
        ],
        code: '114',
        name: 'Physical sciences',
        value: '114',
      },
    ],
    code: '1',
    name: 'Natural sciences',
    value: '1',
  },
  {
    children: [
      {
        children: [
          { code: '2131', name: 'Electronics', value: '2131' },
          {
            code: '2132',
            name: 'Automation and systems engineering',
            value: '2132',
          },
          { code: '2133', name: 'Telecommunications', value: '2133' },
        ],
        code: '213',
        name: 'Electronic, automation and communications engineering',
        value: '213',
      },
      {
        children: [
          { code: '2171', name: 'Biomedical engineering', value: '2171' },
          { code: '2172', name: 'Medical imaging', value: '2172' },
        ],
        code: '217',
        name: 'Medical engineering',
        value: '217',
      },
    ],
    code: '2',
    name: 'Engineering and technology',
    value: '2',
  },
  {
    children: [
      {
        children: [
          { code: '3111', name: 'Cell and molecular biology', value: '3111' },
          { code: '3112', name: 'Neurosciences', value: '3112' },
        ],
        code: '311',
        name: 'Biomedicine',
        value: '311',
      },
      {
        children: [
          { code: '3121', name: 'Internal medicine', value: '3121' },
          { code: '3122', name: 'Cancers', value: '3122' },
          { code: '3123', name: 'Gynaecology and paediatrics', value: '3123' },
        ],
        code: '312',
        name: 'Clinical medicine',
        value: '312',
      },
    ],
    code: '3',
    name: 'Medical and health sciences',
    value: '3',
  },
];

const levelLabels = ['main field', 'field', 'subfield'];

const field = ref<CTreeSelectSelection | null>(null);
</script>
Select branch
Vue React Angular TypeScript
<template>
  <div>
    <c-tree-select
      v-model="field"
      :items
      :level-labels
      hint="A main field or a field can be picked as well"
      label="Field of science"
      allow-branch
      clearable
    />

    <p>Value: {{ field ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import type { CTreeSelectItem } from '@cscfi/csc-ui';

import { ref } from 'vue';

const items: CTreeSelectItem[] = [
  {
    children: [
      {
        children: [
          { code: '1111', name: 'Pure mathematics', value: '1111' },
          { code: '1112', name: 'Applied mathematics', value: '1112' },
          { code: '1113', name: 'Statistics and probability', value: '1113' },
        ],
        code: '111',
        name: 'Mathematics',
        value: '111',
      },
      {
        children: [
          { code: '1131', name: 'Computer science', value: '1131' },
          { code: '1132', name: 'Information systems', value: '1132' },
          { code: '1133', name: 'Software engineering', value: '1133' },
        ],
        code: '113',
        name: 'Computer and information sciences',
        value: '113',
      },
      {
        children: [
          { code: '1141', name: 'Particle physics', value: '1141' },
          { code: '1142', name: 'Condensed matter physics', value: '1142' },
          { code: '1143', name: 'Astronomy and space science', value: '1143' },
        ],
        code: '114',
        name: 'Physical sciences',
        value: '114',
      },
    ],
    code: '1',
    name: 'Natural sciences',
    value: '1',
  },
  {
    children: [
      {
        children: [
          { code: '2131', name: 'Electronics', value: '2131' },
          {
            code: '2132',
            name: 'Automation and systems engineering',
            value: '2132',
          },
          { code: '2133', name: 'Telecommunications', value: '2133' },
        ],
        code: '213',
        name: 'Electronic, automation and communications engineering',
        value: '213',
      },
      {
        children: [
          { code: '2171', name: 'Biomedical engineering', value: '2171' },
          { code: '2172', name: 'Medical imaging', value: '2172' },
        ],
        code: '217',
        name: 'Medical engineering',
        value: '217',
      },
    ],
    code: '2',
    name: 'Engineering and technology',
    value: '2',
  },
  {
    children: [
      {
        children: [
          { code: '3111', name: 'Cell and molecular biology', value: '3111' },
          { code: '3112', name: 'Neurosciences', value: '3112' },
        ],
        code: '311',
        name: 'Biomedicine',
        value: '311',
      },
      {
        children: [
          { code: '3121', name: 'Internal medicine', value: '3121' },
          { code: '3122', name: 'Cancers', value: '3122' },
          { code: '3123', name: 'Gynaecology and paediatrics', value: '3123' },
        ],
        code: '312',
        name: 'Clinical medicine',
        value: '312',
      },
    ],
    code: '3',
    name: 'Medical and health sciences',
    value: '3',
  },
];

const levelLabels = ['main field', 'field', 'subfield'];

const field = ref<null | string>(null);
</script>
Small
Vue React Angular TypeScript
<template>
  <div>
    <c-tree-select
      v-model="field"
      :items
      :level-labels
      label="Field of science"
      size="small"
      label-on-top
    />

    <p>Value: {{ field ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import type { CTreeSelectItem } from '@cscfi/csc-ui';

import { ref } from 'vue';

const items: CTreeSelectItem[] = [
  {
    children: [
      {
        children: [
          { code: '1111', name: 'Pure mathematics', value: '1111' },
          { code: '1112', name: 'Applied mathematics', value: '1112' },
          { code: '1113', name: 'Statistics and probability', value: '1113' },
        ],
        code: '111',
        name: 'Mathematics',
        value: '111',
      },
      {
        children: [
          { code: '1131', name: 'Computer science', value: '1131' },
          { code: '1132', name: 'Information systems', value: '1132' },
          { code: '1133', name: 'Software engineering', value: '1133' },
        ],
        code: '113',
        name: 'Computer and information sciences',
        value: '113',
      },
      {
        children: [
          { code: '1141', name: 'Particle physics', value: '1141' },
          { code: '1142', name: 'Condensed matter physics', value: '1142' },
          { code: '1143', name: 'Astronomy and space science', value: '1143' },
        ],
        code: '114',
        name: 'Physical sciences',
        value: '114',
      },
    ],
    code: '1',
    name: 'Natural sciences',
    value: '1',
  },
  {
    children: [
      {
        children: [
          { code: '2131', name: 'Electronics', value: '2131' },
          {
            code: '2132',
            name: 'Automation and systems engineering',
            value: '2132',
          },
          { code: '2133', name: 'Telecommunications', value: '2133' },
        ],
        code: '213',
        name: 'Electronic, automation and communications engineering',
        value: '213',
      },
      {
        children: [
          { code: '2171', name: 'Biomedical engineering', value: '2171' },
          { code: '2172', name: 'Medical imaging', value: '2172' },
        ],
        code: '217',
        name: 'Medical engineering',
        value: '217',
      },
    ],
    code: '2',
    name: 'Engineering and technology',
    value: '2',
  },
  {
    children: [
      {
        children: [
          { code: '3111', name: 'Cell and molecular biology', value: '3111' },
          { code: '3112', name: 'Neurosciences', value: '3112' },
        ],
        code: '311',
        name: 'Biomedicine',
        value: '311',
      },
      {
        children: [
          { code: '3121', name: 'Internal medicine', value: '3121' },
          { code: '3122', name: 'Cancers', value: '3122' },
          { code: '3123', name: 'Gynaecology and paediatrics', value: '3123' },
        ],
        code: '312',
        name: 'Clinical medicine',
        value: '312',
      },
    ],
    code: '3',
    name: 'Medical and health sciences',
    value: '3',
  },
];

const levelLabels = ['main field', 'field', 'subfield'];

const field = ref<null | string>(null);
</script>
Texts
Vue React Angular TypeScript
<template>
  <div>
    <c-tree-select
      v-model="field"
      :items
      :level-labels
      :texts
      hint="Selaa tasoja tai hae"
      label="Tieteenala"
      clearable
    />

    <p>Value: {{ field ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import type { CTreeSelectItem, CTreeSelectTexts } from '@cscfi/csc-ui';

import { ref } from 'vue';

const items: CTreeSelectItem[] = [
  {
    children: [
      {
        children: [
          { code: '1111', name: 'Puhdas matematiikka', value: '1111' },
          { code: '1112', name: 'Sovellettu matematiikka', value: '1112' },
        ],
        code: '111',
        name: 'Matematiikka',
        value: '111',
      },
      {
        children: [
          { code: '1131', name: 'Tietojenkäsittelytiede', value: '1131' },
          { code: '1132', name: 'Tietojärjestelmätiede', value: '1132' },
        ],
        code: '113',
        name: 'Tietojenkäsittely ja informaatiotieteet',
        value: '113',
      },
    ],
    code: '1',
    name: 'Luonnontieteet',
    value: '1',
  },
  {
    children: [
      {
        children: [
          { code: '2131', name: 'Elektroniikka', value: '2131' },
          { code: '2133', name: 'Tietoliikennetekniikka', value: '2133' },
        ],
        code: '213',
        name: 'Sähkö-, automaatio- ja tietoliikennetekniikka',
        value: '213',
      },
      {
        children: [
          { code: '2171', name: 'Biolääketieteen tekniikka', value: '2171' },
          {
            code: '2172',
            name: 'Lääketieteellinen kuvantaminen',
            value: '2172',
          },
        ],
        code: '217',
        name: 'Lääketieteen tekniikka',
        value: '217',
      },
    ],
    code: '2',
    name: 'Tekniikka',
    value: '2',
  },
];

const levelLabels = ['päätieteenala', 'tieteenala', 'alatieteenala'];

const texts: CTreeSelectTexts = {
  breadcrumb: 'Sijainti',
  browse: 'Selaa sen sijaan',
  children: (count) => `${count} alakohtaa`,
  choose: (level) => `Valitse ${level}`,
  clearSelection: 'Tyhjennä valinta',
  filterOptions: 'Suodata vaihtoehtoja',
  final: 'Viimeinen taso',
  level: (n) => `taso ${n}`,
  levelCounter: (n, total) => `Taso ${n}/${total}`,
  matches: (count) => `${count} osumaa`,
  noResults: 'Ei osumia',
  root: 'Kaikki',
  searchPlaceholder: 'Hae nimellä tai koodilla',
  selectBranch: (name) => `Valitse ${name}`,
  toggleOptions: 'Näytä vaihtoehdot',
};

const field = ref<null | string>(null);
</script>
Uneven depth
Vue React Angular TypeScript
<template>
  <div>
    <c-tree-select
      v-model="field"
      :items
      hint="Some units have sub-units, some do not"
      label="Unit"
      clearable
    />

    <p>Value: {{ field ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import type { CTreeSelectItem } from '@cscfi/csc-ui';

import { ref } from 'vue';

const items: CTreeSelectItem[] = [
  {
    children: [
      {
        children: [
          { name: 'High-performance computing', value: 'hpc' },
          { name: 'Cloud services', value: 'cloud' },
          { disabled: true, name: 'Quantum computing', value: 'quantum' },
        ],
        name: 'Computing',
        value: 'computing',
      },
      { name: 'Data management', value: 'data' },
    ],
    name: 'Research services',
    value: 'research',
  },
  {
    children: [
      { name: 'Training', value: 'training' },
      { name: 'Learning materials', value: 'materials' },
    ],
    name: 'Education',
    value: 'education',
  },
  {
    children: [{ name: 'Human resources', value: 'hr' }],
    disabled: true,
    name: 'Administration',
    value: 'administration',
  },
  { name: 'Communications', value: 'communications' },
];

const field = ref<null | string>(null);
</script>

API reference

<c-tree-select>

A hierarchical value-selection component: a readonly value field that opens a panel for browsing a tree one level at a time, or searching it as a whole, to commit one item.

Properties

PropertyAttributeTypeDefaultDescription
allowBranchallow-branchbooleanfalse Let a branch be committed as the value: a pinned select-branch row heads every level below the root, and matching branches are listed as search results
clearableclearablebooleanfalse Make the selected value clearable
disableddisabledbooleanfalse Disable the field
errorMessageerror-messagestring'' Error message shown in place of the hint while the field is invalid
filter—CTreeSelectFilter— Custom search predicate; receives the item, the query and the item's ancestors. Functions have no attribute form — bind as a DOM property
hideMessagehide-messagebooleanfalse app default Hide the message line — the hint and error messages under the field — and the room it keeps.
hinthintstring'' Hint text for the field
invalidinvalidbooleanfalse Show the control as invalid: its `error-message`, when set, replaces the hint, and the control is marked `aria-invalid`.
items—CTreeSelectItem[]() => [] The tree to pick from. Arrays have no attribute form — bind as a DOM property (`:items.prop` in Vue)
itemsPerPageitems-per-pagenumber6 app default Items per page before the list scrolls
labellabelstring'' Element label
labelOnToplabel-on-topbooleanfalse app default Label on top of the field
levelLabels—string[]— Names of the levels, top level first, shown in the panel header; a missing entry falls back to `texts.level(n)`. Arrays have no attribute form — bind as a DOM property
namenamestring'' The name the picked value submits under in a native `<form>`
placeholderplaceholderstring'' Placeholder for the search input inside the panel
requiredrequiredbooleanfalse Set the field as required
returnObjectreturn-objectbooleanfalse Emit the committed item with its path as a `CTreeSelectSelection` instead of its value
shadowshadowbooleanfalse app default Shadow variant
sizesizeCFieldSize'default' app default Field height: the 52px default (the shared control height) or the 36px `small` box
texts—CTreeSelectTexts{} app default UI text overrides (i18n), merged over the English defaults. Objects have no attribute form — bind as a DOM property (`:texts.prop` in Vue)
valuevalueCTreeSelectValuenull Selected value: the committed item's value, or the `CTreeSelectSelection` with `return-object`; `null` when nothing is selected
hideDetails deprecated hide-detailsbooleanfalse app default Deprecated. Use `hide-message`. Hide the hint and error messages

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.

Events

EventDetailDescription
changeCTreeSelectValueFired when the selection changes — an item is committed or the selection is cleared — carrying the new value: the item's value, the `CTreeSelectSelection` with `return-object`, or `null` when cleared.
change:querystringFired whenever the query changes — on every keystroke in the search input, and with an empty string when the panel opens. Carries the query string.
inputvoidNative bubbling input event dispatched alongside every value change so a plain `v-model` stays in sync. Carries no detail.
update:valueCTreeSelectValueFired alongside `change` with the same detail — the `v-model` contract.

Methods

MethodSignatureDescription
focus(options?: FocusOptions): voidFocus its combobox, as `focus()` does on a native control: the element renders no box of its own to take it.

CSS parts

Style from outside with c-tree-select::part(name) — parts are the library's only styling customization API.

PartDescription
panelThe top-layer popover container anchored below the field
cardThe elevated surface inside the panel holding the search row, the breadcrumb, the header and the list
heading-rowThe top row of the fullscreen panel (narrow viewports): the field label as heading and the close button
headingThe field label naming the fullscreen panel
closeThe close button of the fullscreen panel
searchThe search-input row at the top of the panel
breadcrumbThe breadcrumb navigation naming the browsed level's path
crumbOne crumb in the breadcrumb: the root crumb, an ancestor, or the collapsed "…" crumb
headerThe header line under the breadcrumb: the level to choose and its step counter, or the match count and the "Browse instead" control
listThe scrollable listbox: the level list while browsing, the results while searching
optionOne row in the list
select-branchThe pinned select-branch row at the top of a level list inside a branch (`allow-branch`)
codeAn item's code column, in a row and in the closed field
pathThe ancestor path line under a search result's label
matchA run of an item's code, label or path equal to the query, in a row; underlined in the primary colour, text inherits the row
infoThe no-results row shown when nothing is listed
messageThe hint / error message area below the field (always reserved unless `hide-message`)

Types

Importable from the package root: import type { … } from '@cscfi/csc-ui'

CTreeSelectFilter

Custom search predicate for `c-tree-select`. Receives the item, the query and the item's ancestors root-first; return `true` to list the item. The default matches the query case-insensitively anywhere in the `name` or `code` of the item or of any of its ancestors.

export type CTreeSelectFilter = (
  item: CTreeSelectItem,
  query: string,
  path: CTreeSelectItem[],
) => boolean;
CTreeSelectItem

One item of a `c-tree-select` tree. An item with a non-empty `children` array is a branch; any other item is a leaf. Values must be unique across the whole tree.

export interface CTreeSelectItem {
  /** Child items; present and non-empty for a branch. */
  children?: CTreeSelectItem[];

  /**
   * Short code shown before the name and matched by the search (a
   * classification number, say).
   */
  code?: string;

  /**
   * Disable the item: a disabled branch cannot be entered, a disabled leaf
   * cannot be committed.
   */
  disabled?: boolean;

  /** The item's label. */
  name: string;

  /** The item's value, unique across the tree. */
  value: number | string;
}
CTreeSelectSelection

The committed item as emitted with `return-object`: a fresh object — never the `items` entry itself — with its ancestors root-first and without `children`.

export interface CTreeSelectSelection {
  /** The committed item's code, when it has one. */
  code?: string;

  /** The committed item's label. */
  name: string;

  /** The committed item's ancestors, root-first. */
  path: Array<{ code?: string; name: string; value: number | string }>;

  /** The committed item's value. */
  value: number | string;
}
CTreeSelectTexts

UI texts of `c-tree-select`, shallow-merged over the English defaults. Static labels are strings; interpolated ones are functions.

export interface CTreeSelectTexts {
  /** Accessible label of the breadcrumb navigation in the panel. */
  breadcrumb?: string;

  /**
   * Label of the "Browse instead" control shown in the header while a query
   * is typed.
   */
  browse?: string;

  /** Meta text on a branch row; receives its number of children. */
  children?: (count: number) => string;

  /**
   * Header text in browse mode; receives the label of the level being
   * listed.
   */
  choose?: (levelLabel: string) => string;

  /** Accessible label of the clear button. */
  clearSelection?: string;

  /** Accessible label of the close button in the fullscreen panel (narrow viewports). */
  closePanel?: string;

  /** Accessible label of the search input inside the panel. */
  filterOptions?: string;

  /**
   * Header text of a level whose rows are all leaves in an unevenly deep
   * tree (an evenly deep tree shows the step counter instead).
   */
  final?: string;

  /**
   * Default label of level `n` (1 = the top level) when `level-labels` gives
   * none.
   */
  level?: (n: number) => string;

  /**
   * Header level counter shown while the tree is evenly deep (every leaf at
   * one level); receives the level and the number of levels.
   */
  levelCounter?: (n: number, total: number) => string;

  /** Header text in search mode; receives the number of matches. */
  matches?: (count: number) => string;

  /** Text of the row shown when nothing is listed. */
  noResults?: string;

  /** Label of the root crumb. */
  root?: string;

  /** Placeholder of the search input when the `placeholder` prop is empty. */
  searchPlaceholder?: string;

  /**
   * Label of the pinned select-branch row; receives the current branch's
   * name.
   */
  selectBranch?: (name: string) => string;

  /** Accessible label of the chevron button that opens and closes the panel. */
  toggleOptions?: string;
}
CTreeSelectValue

Selection value of `c-tree-select`: the committed item's value — or a with `return-object` — and `null` when cleared.

export type CTreeSelectValue = CTreeSelectSelection | null | number | string;
CFieldSize shared

Field height of the form controls built on `c-input`. `default` is the 44px field; `small` is the 36px field. Owned here because the value passes from the wrapping control (`c-select`) into `c-input`.

export type CFieldSize = 'default' | 'small';