Vue primitives
The same primitives and hooks for Vue 3.5, from @fragiola/tree-vue, and how each React prop maps onto Vue props, slots, events and attributes.
@fragiola/tree-vue has every primitive of the React package, as a Vue 3.5 component, and every
hook as a composable, over the same core (re-exported whole). The behaviour, the ARIA, the
data-* attributes, data-tree-part and data-tree-path of every element are the same: the
React pages of this reference describe each part, and this page says how its React API is written
in Vue.
import {
createTreeModel,
Tree,
typedTree,
useTree,
useTreeState,
type TreeJson,
} from "@fragiola/tree-vue";
// each feature from its own entry
import { selection } from "@fragiola/tree-vue/selection";
import {
typedVirtualItems,
useTreeVirtualWindow,
VirtualItems,
virtualization,
} from "@fragiola/tree-vue/virtualization";Typing by your registry
A React part takes the registry and the features as type arguments
(<Tree.Root<Types, typeof features>>); a Vue template cannot pass them.
typedTree<Types, typeof features>() returns the same components, typed by both: an item in a
slot is then of your registry, item.data narrows on item.kind, Tree.Root takes a
TreeModel<Types, typeof features>, and a feature's list (v-model:selected-item-ids with
selection()) compiles only when the feature is installed (Features).
import { typedTree } from "@fragiola/tree-vue";
import { selection } from "@fragiola/tree-vue/selection";
export type Types = { items: { folder: undefined; file: { size: number } } };
export const features = [selection()] as const;
export const Tree = typedTree<Types, typeof features>();| export | description |
|---|---|
typedTree<T, F>() | the Tree components typed by the registry T and the features F, as a TypedTree<T, F> (the same objects as Tree); its Tree.Root takes RootProps<T, F> (RootBaseProps<T, F> and the features' lists) and emits RootEmits<F> |
Tree | the components, typed by AnyTypes: its Tree.Root takes a TreeModel of AnyTypes; give a typed model to typedTree<Types>().Root |
How React's props map
| React | Vue |
|---|---|
render={<li />} | as="li" (a tag or a component) |
render={(props, state) => …} | the render scoped slot, #render="{ props, state, children }": bind v-bind="props" on your element and render <component :is="children" /> inside it |
className, style | the class and style attributes, merged under the structural style (structural keys win: --tree-depth, the drop indicator's geometry) |
className={(state) => …}, style={(state) => …} | no function form: a data-* selector (data-[selected]:…), or the render slot's state |
onClick, onKeyDown, … | listeners (@click, @keydown), run after the primitive's own |
ref | a template ref on a part is its component instance; the element is its $el |
children functions (Tree.Items, Tree.Group) | the default scoped slot: v-slot="{ item }" |
expandedItemIds + onExpandedItemIdsChange | v-model:expanded-item-ids (or :expanded-item-ids with @update:expanded-item-ids) |
selectedItemIds + onSelectedItemIdsChange | v-model:selected-item-ids (with selection()) |
checkedItemIds + onCheckedItemIdsChange (checkboxes()) | v-model:checked-item-ids |
useTreeItemRename(item, { onRenameError }) (@fragiola/tree-react/rename) | the same composable and option, from @fragiola/tree-vue/rename; @input of your own runs next to its listener |
treeRef={tree} | :tree-ref="tree"; the handle is tree.value, in the template too (React: tree.current) |
defaultTree, expandOnClick, keyMap, … | the same props in kebab-case (default-tree, expand-on-click, key-map); a boolean prop takes a bare attribute (expand-on-click) |
<Tree.Items<Types>> and the other type arguments | typedTree<Types, typeof features>().Items |
<VirtualItems<Types>> | typedVirtualItems<Types>(), from @fragiola/tree-vue/virtualization |
Components
Every part is Tree.<Part>, with the props of its React page except render, className,
style, ref and children (see the table above). Each accepts as and the render slot.
| part | Vue props | slots | events |
|---|---|---|---|
Tree.Root | model, defaultTree, features, expandedItemIds, selectedItemIds, checkedItemIds, loadChildren, announce, keyMap, expandOnClick, treeRef | default | update:expandedItemIds, update:selectedItemIds, update:checkedItemIds |
Tree.Items | none | default { item } | none |
Tree.Item | item | default { state } | none |
Tree.ItemContent | none | default { state } | none |
Tree.Group | keepMounted | default { item } | none |
Tree.Toggle | none | default { state } | none |
Tree.LiveRegion | none | none | none |
DropIndicator (from @fragiola/tree-vue/drag-and-drop, and /foreign-drop, with DropIndicatorProps, DropIndicatorSlots and DropIndicatorState) takes no props of its own and a render slot. VirtualItems (from @fragiola/tree-vue/virtualization, with VirtualItemsProps and
VirtualItemsSlots) takes no prop and has a default slot { item, row } (row: its
VirtualRow); typedVirtualItems<Types>() is the same component typed by the registry.
Another model remounts the tree (a new engine), as a new model creates a new engine in React.
Keep the model out of Vue's reactivity: create it once (const model = createTreeModel(json) in
setup), never in ref() or reactive(), whose proxy would not be the model the engine knows.
Composables
The hooks of the React reference, as composables. Call them in setup.
| composable | returns |
|---|---|
useTree<T, F>() | { model, engine }, a UseTreeResult<T, F> (plain values: another model remounts the root) |
useTreeState(selector, options?) | a read-only ref of the selection, changed only when isEqual says it changed (UseTreeStateOptions: model, isEqual); it selects again when a reactive value the selector reads changes |
useTreeItem(item) | UseTreeItemResult: state (TreeItemState) and props (TreeItemElementProps: the ARIA, tabindex, data-*, onFocus, the structural style and the template ref), as computed refs; bind v-bind="props" on your element. item is a value, a ref or a getter |
useTreeItemRename(item, options?) | UseTreeItemRenameResult: state (TreeItemRenameState: renaming, invalid, error) and props (TreeItemRenameProps: the template ref, which writes the label and focuses and selects it, aria-invalid, data-invalid, onKeydown, onBlur, onInput), as computed refs; render your input with v-if="state.renaming" and bind v-bind="props". item is a value, a ref or a getter; UseTreeItemRenameOptions: onRenameError |
useTreeRef<T, F>() | a TreeRef<T, F>, whose read-only, reactive value is the root's TreeHandle (model, engine) while it is mounted, null otherwise. It is not a Vue ref, so a template does not unwrap it: :tree-ref="tree" passes it, and the template reads tree.value |
createTreeRef<T, F>() | the same tree ref, anywhere (a module, a test) |
useTreeVirtualWindow() (from @fragiola/tree-vue/virtualization) | a computed ref of the root's VirtualWindow (the rows a virtualized tree renders), null before it mounts and without the virtualization() feature |
A server render (Nuxt, renderToString) outputs the tree's markup, never subscribes to the model
and never runs a command on it: the engine, the controlled lists and the composables' subscriptions
start once the component mounts in the browser.
Types
Each part exports its props and its slots, named as in React, and its state and events where it
has them: RootProps, RootSlots, RootState, RootEmits, ItemsProps, ItemsSlots,
VirtualItemsProps, VirtualItemsSlots,
ItemProps, ItemSlots, ItemContentProps, ItemContentSlots, GroupProps, GroupSlots,
ToggleProps, ToggleSlots, DropIndicatorProps,
DropIndicatorSlots, DropIndicatorState, LiveRegionProps, LiveRegionSlots,
LiveRegionState, TreeItemState, TreeItemElementProps, UseTreeResult, UseTreeItemResult,
UseTreeStateOptions, TreeItemRenameState, TreeItemRenameProps, UseTreeItemRenameOptions,
UseTreeItemRenameResult, TreeHandle, TreeRef.
| type | description |
|---|---|
TreeComponent<Props, Slots, Emits> | a part's component type: its props, plus any fallthrough attribute, its scoped slots and its events |
TypedTree<T> | what typedTree<T>() returns: every part typed by T |
PrimitiveProps | what every part accepts: as |
AsProp | a tag name or a component |
RenderSlot<State> | the render slot every part accepts |
RenderSlotProps<State> | what it receives: props, state, children |
SlotFunction<Scope> | a scoped slot: its scope in, the nodes it renders out |
ElementRef | a function template ref, as useTreeItem's props.ref |
Examples
Every example of the gallery exists in Vue, with the same behaviour: pick Vue in the framework
switch to see its code. The file explorer shows the recursion with a
self-referencing component, controlled the v-model lists and
undo and redo an app store read through a shallowRef kept in step
with its subscribe.
Hooks
The hooks under the primitives - the root's model and engine, an item's state and props for your own markup, a selected value of the state, and tree refs.
Angular primitives
The same primitives and hooks for Angular 22, from @fragiola/tree-angular, and how each React prop maps onto directives, inputs, outputs and templates.