Skip to content

OrigamTreeview ​

A recursive nested file/folder hierarchy component with expand/collapse, keyboard navigation, and single or multiple selection. Designed for file explorers, documentation sidebars, and any hierarchical data structure.

Usage ​

Basic file tree ​

vue
<origam-treeview
  :items="[
    {
      id: 'src',
      label: 'src',
      children: [
        { id: 'src/Btn.vue', label: 'Btn.vue', size: '12.4 KB' },
        { id: 'src/Card.vue', label: 'Card.vue', size: '8.1 KB' }
      ]
    },
    { id: 'README.md', label: 'README.md', size: '3.2 KB' }
  ]"
/>

Single selection with v-model ​

vue
<origam-treeview
  v-model="selectedId"
  :items="fileTree"
  select-mode="single"
  selectable-nodes="leaf"
/>

Multiple selection ​

vue
<origam-treeview
  v-model="selectedIds"
  :items="fileTree"
  select-mode="multiple"
  selectable-nodes="all"
/>

Expand on row click ​

vue
<origam-treeview
  :items="fileTree"
  :expand-on-click="true"
/>

Pre-expanded nodes ​

vue
<origam-treeview
  :items="fileTree"
  :expanded-value="['src', 'src/components']"
/>

Hide indent guide lines ​

vue
<origam-treeview
  :items="fileTree"
  :show-lines="false"
/>

Props — ITreeviewProps ​

PropTypeDefaultDescription
itemsITreeviewNode[]requiredRoot-level tree nodes
modelValuestring[] | string—Selected node id(s)
expandedValuestring[]—Initially expanded node ids
selectModeTTreeviewSelectMode'none'Selection mode: 'none', 'single', 'multiple'
selectableNodesTTreeviewSelectableNodes'leaf'Which nodes are selectable: 'leaf' (files only) or 'all'
showLinesbooleantrueShow vertical guide lines between nesting levels
expandOnClickbooleanfalseClicking anywhere on the row toggles expansion
colorTColor—Intent color applied via useColorEffect
densityTDensity'default'Row density
sizeTSize'default'Component size scale
ariaLabelstring—Accessible name for the root role="tree". Falls back to the localised default ('File tree' in English) when omitted
+ all ICommonsComponentPropsid, class, style

ITreeviewNode data shape ​

FieldTypeRequiredDescription
idstringYesUnique identifier used for expanded/selected tracking
labelstringYesDisplay name of the node
iconTIconNoCustom icon; defaults to folder/file emoji
sizestringNoPre-formatted file size string (e.g. "12.4 KB")
childrenITreeviewNode[]NoChild nodes — presence determines folder behaviour
disabledbooleanNoPrevents interaction with this node
expandablebooleanNoOverride auto-detection of folder status

Emits ​

EventPayloadDescription
update:modelValuestring[] | stringFired when selection changes
update:expandedValuestring[]Fired when expanded state changes
selectstringFired with the toggled node id
togglestring, booleanFired with node id and new expanded state

Keyboard navigation ​

KeyAction
ArrowDownMove focus to next visible row
ArrowUpMove focus to previous visible row
ArrowRightExpand collapsed folder, or move focus to first child if already expanded
ArrowLeftCollapse expanded folder, or move focus to parent node
Enter / SpaceSelect the focused node (if selectable), or toggle expansion for folders

Slots ​

SlotPropsDescription
node{ node, depth, isExpanded, isSelected }Override the default row markup for each node

Custom node slot example ​

vue
<origam-treeview :items="fileTree">
  <template #node="{ node, depth, isExpanded, isSelected }">
    <span :style="{ paddingInlineStart: `${depth * 16}px` }">
      {{ node.label }}
    </span>
  </template>
</origam-treeview>

Accessibility ​

  • Wrapper renders as <div role="tree" aria-multiselectable>.
  • Each row renders as [role="treeitem"] with aria-expanded, aria-selected, and aria-disabled.
  • Chevron and icons are aria-hidden="true".
  • Full keyboard navigation following the WAI-ARIA Treeview pattern.
  • Disabled nodes receive aria-disabled="true" and tabindex="-1".

Design tokens ​

CSS variableDefault sourceDescription
--origam-treeview---background-colorcolor.surface.defaultTree background
--origam-treeview---colorcolor.text.primaryDefault text color
--origam-treeview---indent-sizespace.4 (16px)Indentation per depth level
--origam-treeview---row-heightspace.8 (32px)Row minimum height
--origam-treeview---row-bg-hovercolor.surface.overlayRow hover background
--origam-treeview---row-bg-selectedcolor.action.primary.bgSubtleSelected row background
--origam-treeview---row-color-selectedcolor.action.primary.fgSubtleSelected row text color
--origam-treeview---row-color-disabledcolor.text.disabledDisabled node text color
--origam-treeview---chevron-sizespace.4 (16px)Chevron icon size
--origam-treeview---chevron-colorcolor.text.secondaryChevron color
--origam-treeview---label-font-sizefont.size.sm (0.75rem)Node label font size
--origam-treeview---size-font-sizefont.size.xs (0.625rem)File size badge font size
--origam-treeview---guide-colorcolor.border.subtleIndent guide line color
--origam-treeview---guide-thicknessborder.width.thin (1px)Indent guide line thickness