<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
<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>
<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>
<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>
<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>
<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>
<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>
<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
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
allowBranch | allow-branch | boolean | false | 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 |
clearable | clearable | boolean | false | Make the selected value clearable |
disabled | disabled | boolean | false | Disable the field |
errorMessage | error-message | string | '' | Error message shown in place of the hint while the field is invalid |
filter | — | | — | Custom search predicate; receives the item, the query and the item's ancestors. Functions have no attribute form — bind as a DOM property |
hideMessage | hide-message | boolean | false app default | Hide the message line — the hint and error messages under the field — and the room it keeps. |
hint | hint | string | '' | Hint text for the field |
invalid | invalid | boolean | false | Show the control as invalid: its `error-message`, when set, replaces the hint, and the control is marked `aria-invalid`. |
items | — | | () => [] | The tree to pick from. Arrays have no attribute form — bind as a DOM property (`:items.prop` in Vue) |
itemsPerPage | items-per-page | number | 6 app default | Items per page before the list scrolls |
label | label | string | '' | Element label |
labelOnTop | label-on-top | boolean | false 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 |
name | name | string | '' | The name the picked value submits under in a native `<form>` |
placeholder | placeholder | string | '' | Placeholder for the search input inside the panel |
required | required | boolean | false | Set the field as required |
returnObject | return-object | boolean | false | Emit the committed item with its path as a `CTreeSelectSelection` instead of its value |
shadow | shadow | boolean | false app default | Shadow variant |
size | size | CFieldSize | 'default' app default | Field height: the 52px default (the shared control height) or the 36px `small` box |
texts | — | | {} 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) |
value | value | | null | Selected value: the committed item's value, or the `CTreeSelectSelection` with `return-object`; `null` when nothing is selected |
hideDetails deprecated | hide-details | boolean | false 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
| Event | Detail | Description |
|---|---|---|
change | CTreeSelectValue | Fired 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:query | string | Fired whenever the query changes — on every keystroke in the search input, and with an empty string when the panel opens. Carries the query string. |
input | void | Native bubbling input event dispatched alongside every value change so a plain `v-model` stays in sync. Carries no detail. |
update:value | CTreeSelectValue | Fired alongside `change` with the same detail — the `v-model` contract. |
Methods
| Method | Signature | Description |
|---|---|---|
focus | (options?: FocusOptions): void | Focus 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.
| Part | Description |
|---|---|
panel | The top-layer popover container anchored below the field |
card | The elevated surface inside the panel holding the search row, the breadcrumb, the header and the list |
heading-row | The top row of the fullscreen panel (narrow viewports): the field label as heading and the close button |
heading | The field label naming the fullscreen panel |
close | The close button of the fullscreen panel |
search | The search-input row at the top of the panel |
breadcrumb | The breadcrumb navigation naming the browsed level's path |
crumb | One crumb in the breadcrumb: the root crumb, an ancestor, or the collapsed "…" crumb |
header | The header line under the breadcrumb: the level to choose and its step counter, or the match count and the "Browse instead" control |
list | The scrollable listbox: the level list while browsing, the results while searching |
option | One row in the list |
select-branch | The pinned select-branch row at the top of a level list inside a branch (`allow-branch`) |
code | An item's code column, in a row and in the closed field |
path | The ancestor path line under a search result's label |
match | A 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 |
info | The no-results row shown when nothing is listed |
message | The 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';