Tree

experimental

The Tree component presents a hierarchical list. Any item in the hierarchy may have child items, and items that have children may be expanded or collapsed to show or hide the children. Items with children can be cexpanded or collapsed and child items can be selected. The component uses the ARIA tree role and implements the W3C ARIA APG Tree View Pattern. Combine it with the Field component to access all functionalities.

Examples

Base

The component allows the user to select one or more items from a hierarchically organized collection. For example, a file system navigator that uses a tree view, each item displays a folder or file. Folder items can be expanded to reveal the contents of the folder, which may be files, folders, or both.

Accessibility Note:

A tree view is primarily navigated with arrow keys on the keyboard instead of the tab key. This form of navigation is more similar to native applications than to web applications. For this reason, consider alternative options to address the functionality you need before using a tree component. A tree component is at the most times not needed for typical site navigation that is styled to look like a tree with expandable sections.

Show code

Options

Instead of using the <o-tree-item> component directly inside the default slot, an options prop can be set, which can be used to define the options programmatically. It accepts several different formats of values:

An array of primitives ['A', 'B', 'C']
An object literal with key-value pairs { a: 'A', b: 'B', c: 'C' }
An array of objects with label and value properties
Grouped options by adding additional options to the option object.

Note

The options prop works the same as the Select input component options prop.

Show code

HTMLJS

html

<section>
    <o-tree :options="options" />
</section>

javascript

import type { OptionsGroupProp } from "@oruga-ui/oruga-next";

const options: OptionsGroupProp = [
    {
        label: "Documents",
        attrs: {
            icon: "folder",
        },
        options: [
            {
                label: "Work",
                value: "work",
                attrs: {
                    icon: "cog",
                    options: [
                        {
                            label: "Expenses.doc",
                            value: "expenses",
                            attrs: {
                                icon: "file",
                            },
                        },
                        {
                            label: "Resume.doc",
                            value: "resume",
                            attrs: {
                                icon: "file",
                            },
                        },
                    ],
                },
            },
            {
                label: "Home",
                value: "home",
                attrs: {
                    icon: "home",
                    options: [
                        {
                            label: "Invoices.txt",
                            value: "invoices",
                            attrs: {
                                icon: "file",
                            },
                        },
                    ],
                },
            },
        ],
    },
    {
        label: "Events",
        value: "events",
        attrs: {
            icon: "calendar",
        },
        options: [
            {
                label: "Meeting",
                value: "meeting",
                attrs: {
                    icon: "calendar-plus",
                },
            },
            {
                label: "Product Launch",
                value: "product-launch",
                attrs: {
                    icon: "calendar-plus",
                },
            },
            {
                label: "Report Review",
                value: "report-review",
                attrs: {
                    icon: "calendar-plus",
                },
            },
        ],
    },
    {
        label: "Movies",
        value: "movies",
        attrs: {
            icon: "star",
        },
        options: [
            {
                label: "Al Pacino",
                value: "al-pacion",
                attrs: {
                    icon: "star",
                    options: [
                        {
                            label: "Scarface",
                            value: "scarface",
                            attrs: {
                                icon: "video",
                            },
                        },
                        {
                            label: "Serpico",
                            value: "serpico",
                            attrs: {
                                icon: "video",
                            },
                        },
                    ],
                },
            },
            {
                label: "Robert De Niro",
                value: "robert-de-niro",
                attrs: {
                    icon: "star",
                    options: [
                        {
                            label: "Goodfellas",
                            value: "goodfellas",
                            attrs: {
                                icon: "video",
                            },
                        },
                        {
                            label: "Untouchables",
                            value: "untouchables",
                            attrs: {
                                icon: "video",
                            },
                        },
                    ],
                },
            },
        ],
    },
];

Selection

When setting the selectable property, users can select any item. The current selected item value is available in the modelValue property. In "multi-select" trees users are able to select more than one item.

Single

When a single-select tree receives focus, if none of the tree items are selected before the tree receives focus, focus is set on the first node. If a tree item is selected before the tree receives focus, focus is set on the selected tree item.

Show code

HTMLJS

html

<section>
    <o-tree v-model="selected" selectable>
        <o-tree-item icon="folder" label="Documents" value="documents">
            <o-tree-item icon="cog" label="Work" value="work">
                <o-tree-item
                    icon="file"
                    label="Expenses.doc"
                    value="expanses" />
                <o-tree-item
                    icon="file"
                    label="Resume.doc"
                    value="resume" />
            </o-tree-item>

            <o-tree-item icon="home" label="Home" value="home">
                <o-tree-item
                    icon="file"
                    label="Invoices.txt"
                    value="invoices" />
            </o-tree-item>
        </o-tree-item>

        <o-tree-item icon="cog" label="Events" value="events">
            <o-tree-item
                icon="calendar-plus"
                label="Meeting"
                value="meeting" />
            <o-tree-item
                icon="calendar-plus"
                label="Product Launch"
                value="launch" />
            <o-tree-item
                icon="calendar-plus"
                label="Report Review"
                value="review" />
        </o-tree-item>

        <o-tree-item icon="star" label="Movies" value="movies">
            <o-tree-item icon="star" label="Al Pacino" value="al-paciono">
                <o-tree-item
                    icon="video"
                    label="Scarface"
                    value="scarface" />
                <o-tree-item icon="video" label="Serpico" value="serpico" />
            </o-tree-item>

            <o-tree-item
                icon="star"
                label="Robert De Niro"
                value="robert-deniro">
                <o-tree-item
                    icon="video"
                    label="Goodfellas"
                    value="goodfellas" />
                <o-tree-item
                    icon="video"
                    label="Untouchables"
                    value="untouchables" />
            </o-tree-item>
        </o-tree-item>
    </o-tree>

    <p><b> Selected:</b> {{ selected }}</p>
</section>

javascript

import { ref } from "vue";

const selected = ref<string>();

Multiple

You can enable multi-select with the multiple property. In multi-select trees, the selected state is always independent of the focus. For example, in a typical file system navigator, the user can move focus to select any number of files for an action, such as copy or move. The visual design should make it clear which items are selected and which item has focus. When a multi-select tree receives focus, if none of the tree items are selected before the tree receives focus, focus is set on the first tree item. If one or more tree items are selected before the tree receives focus, focus is set on the first selected node.

Show code

HTMLJS

html

<section>
    <o-tree v-model="selected" selectable multiple>
        <o-tree-item icon="folder" label="Documents" value="documents">
            <o-tree-item icon="cog" label="Work" value="work">
                <o-tree-item
                    icon="file"
                    label="Expenses.doc"
                    value="expanses" />
                <o-tree-item
                    icon="file"
                    label="Resume.doc"
                    value="resume" />
            </o-tree-item>

            <o-tree-item icon="home" label="Home" value="home">
                <o-tree-item
                    icon="file"
                    label="Invoices.txt"
                    value="invoices" />
            </o-tree-item>
        </o-tree-item>

        <o-tree-item icon="cog" label="Events" value="events">
            <o-tree-item
                icon="calendar-plus"
                label="Meeting"
                value="meeting" />
            <o-tree-item
                icon="calendar-plus"
                label="Product Launch"
                value="launch" />
            <o-tree-item
                icon="calendar-plus"
                label="Report Review"
                value="review" />
        </o-tree-item>

        <o-tree-item icon="star" label="Movies" value="movies">
            <o-tree-item icon="star" label="Al Pacino" value="al-paciono">
                <o-tree-item
                    icon="video"
                    label="Scarface"
                    value="scarface" />
                <o-tree-item icon="video" label="Serpico" value="serpico" />
            </o-tree-item>

            <o-tree-item
                icon="star"
                label="Robert De Niro"
                value="robert-deniro">
                <o-tree-item
                    icon="video"
                    label="Goodfellas"
                    value="goodfellas" />
                <o-tree-item
                    icon="video"
                    label="Untouchables"
                    value="untouchables" />
            </o-tree-item>
        </o-tree-item>
    </o-tree>

    <p><b> Selected:</b> {{ selected }}</p>
</section>

javascript

import { ref } from "vue";

const selected = ref<string[]>();

Scrollable

When having to many options, consider adding a max height using the scrollHeight property, which allows to cap the tree at a fixed max-height. This will render a long tree of options with a scrollbar. The component will emit a scroll-start or scroll-end event, when the top or bottom of the tree is reached.

Show code

Slot

The item label can be customised using the label slot.

Show code

Tree Component

A simple tree view, for any type of hierarchical list.

html

<o-tree></o-tree>

Props

Prop name	Description	Type	Values	Default
animation	Custom animation (transition name)	string	-	From config: `tree: { animation: "slide" }`
ariaLabel	Defines a string value that labels an interactive element.	string	-
ariaLabelledby	Identifier of the underlying input element.	string	-
checkable	Enable a checkbox on the item element	boolean	-	`false`
collapsable	If sub tree items are shown as a accordion	boolean	-	`true`
disabled	Tree will be disabled	boolean	-	`false`
emptyLabel	A label which is displayed when no options are visible	string	-	From config: `tree: { emptyLabel: undefined }`
iconPack	Icon pack to use	string	`mdi`, `fa`, `fas and any other custom icon pack`	From config: `tree: { iconPack: undefined }`
iconSize	Icon size	string	`small`, `medium`, `large`	From config: `tree: { iconSize: undefined }`
id	Same as native id. Also set the for label for o-field wrapper - default is an uuid.	string	-	`useId()`
v-model	The selected item value, use v-model to make it two-way binding	unknown	-
multiple	Allows multiple selections - converts the `modelValue` into an array	boolean	-
options	Tree items, unnecessary when default slot is used	OptionsPropWithGroups<unknown>	-
override	Override existing theme classes completely	boolean	-
scrollHeight	Height of the tree, a scrollbar is defined if height of list exceeds this value	number \| string	-	From config: `tree: { scrollHeight: undefined }`
selectable	Enables item selection	boolean	-	`false`
toggleIcon	The chevron icon to for the toggle element before each item	string	-	From config: `tree: { toggleIcon: undefined }`

Events

Event name	Properties	Description
update:model-value	value `unknown` - updated modelValue prop	modelValue prop two-way binding
select	value `unknown` - selected value	on select event - fired before update:modelValue
focus	event `Event` - native event	on tree focus event
blur	event `Event` - native event	on tree blur event
scroll-start		scrolling inside the tree reached the start
scroll-end		scrolling inside the tree reached the end

Slots

Name	Description	Bindings
header	Define an additional header
default	Define the tree items here
empty	Define the content to show if the list is empty
footer	Define an additional footer

TreeItem Component

A tree list item.

html

<o-tree-item></o-tree-item>

Props

Prop name	Description	Type	Values	Default
animation	Transition name to apply on tree list	string	-	From config: `tree: { animation: "slide" }`
ariaLabel	Defines a string value that labels an interactive element.	string	-
ariaLabelledby	Identifier of the underlying input element.	string	-
disabled	Tree item will be disabled	boolean	-	`false`
expanded	Tree item will be expanded	boolean	-	`false`
hidden	Define whether the item is visible or not	boolean	-	`false`
icon	Icon to be shown	string	-
iconPack	Icon pack to use	string	`mdi`, `fa`, `fas and any other custom icon pack`	From config: `tree: { iconPack: undefined }`
iconSize	Icon size	string	`small`, `medium`, `large`	From config: `tree: { iconSize: undefined }`
label	Tree item label	string	-
options	Subtree items, unnecessary when default slot is used	OptionsProp<unknown>	-
override	Override existing theme classes completely	boolean	-
subtreeId	HTML element Id of the sub tree ol list element	string	-	`useId()`
value	Item value (it will be used as the v-model of the wrapper component) - default is an uuid	unknown	-	`useId()`

Events

Event name	Properties	Description
click	value `unknown` - value prop data event `event` - native event	onclick event
open		on sub tree opened
close		on sub tree closed

Slots

Name	Description	Bindings
label	Override the label, default is label prop	expanded `boolean` - item is expanded selected `boolean` - item is selected disabled `boolean` - item is disabled
default	Define subtree items here

Class Inspector

➜ Want to know how does the Class Inspector work?

Class prop	Description	Props
rootClass	Class of the root element.
disabledClass	Clas of the root element when disabled.	`disabled`
selectableClass	Class of the root element when selectable.	`selectable`
multipleClass	Class of the root element when multiple.	`multiple`
headerClass	Class of the header slot wrapper element.
footerClass	Class of the footer slot wrapper element.
emptyClass	Class of the empty slot wrapper element.
listClass	Class of the tree list element.
▷ itemClass	Class of the tree item root element.
▷ itemSelectedClass	Class of the tree item root element when selected.
▷ itemFocusedClass	Class of the tree item root element when focused.
▷ itemClickableClass	Class of the tree item root element when clickable.
▷ itemDisabledClass	Class of the tree item root element when disabled.	`disabled`
▷ itemLabelClass	Class of the tree item label element element.
▷ itemSubtreeClass	Class of the tree item subtree element.

Sass Variables

Current theme ➜ Oruga

The theme does not have any custom variables for this component.

Current theme ➜ Bulma

The theme does not have any custom variables for this component.

Current theme ➜ Bootstrap

The theme does not have any custom variables for this component.

Tree ​

Examples ​

Base

Options

Selection

Single

Multiple

Scrollable

Slot

Tree Component ​

Props ​

Events ​

Slots ​

TreeItem Component ​

Props ​

Events ​

Slots ​

Class Inspector ​

Class prop

Description

Props

Suffixes

Sass Variables ​

Tree

Examples

Tree Component

Props

Events

Slots

TreeItem Component

Props

Events

Slots

Class Inspector

Sass Variables