vue-tree

Overview

vue-tree is a Vue component that implements a TreeView control. Its aim is to provide common tree options in a way that is easy to use and easy to customize.

Features include:

• Works in modern browsers using the precompiled scripts, or can be included in your babel/webpack chain.
• Expandable nodes
• Checkboxes
• Radio buttons
• Node selection
• Addition and removal of nodes
• Slots for node content
• Skinning
• Asynchronous loading of nodes
• Follows ARIA guidelines for treeview accessibility
• Drag and drop (single nodes, works between trees)

For future plans, see the project’s Issues page.

Installation

Install the component with your favorite package manager:

yarn add @grapoza/vue-tree

or

npm install --save @grapoza/vue-tree

Usage

If you’re using it in a .vue file:

<template>
    <tree-view  id="my-tree" :initial-model="dataModel"></tree-view>
  </template>
  
  <script>
  import TreeView from "@grapoza/vue-tree"
  
  export default {
    components: {
      TreeView
    },
    data() {
      return {
        dataModel: [
          {id: "numberOrString", label: "Root Node", children: [
            {id: 1, label: "Child Node"},
            {id: "node2", label: "Second Child"}]
          }]
      }
    }
  }
  </script>

Or, import it into your application:

import TreeView from "@grapoza/vue-tree"
  Vue.use(TreeView)

Then add the component:

<tree-view id="my-tree" :initial-model="dataModel"></tree-view>

export default {
    data() {
      return {
        dataModel: [
          { id: "numberOrString", label: "Root Node", children: [
            { id: 1, label: "Child Node" },
            { id: "node2", label: "Second Child" }]
          }]
      }
    }
  }

Demos

To see it in action, try out the demos.

Tree Props

Selection Mode

The selectionMode property defines how nodes should be selected within the treeview. Allowed values are null, single, selectionFollowsFocus, and multiple. Only nodes with the selectable model property set to true can be selected.

• If null (the default) then selection does not occur.
• If single then one node is selected at a time when the user clicks the node or using the selection keyboard binding (Enter by default).
• If selectionFollowsFocus then selection follows the focusable node within the treeview.
• if mulitple then multiple nodes can be selected when the user clicks each node or using the selection keyboard binding on each node.

When clicking on a node, it is only selected if the click target was not interactive (e.g., clicking a checkbox or expander won’t select the node, but clicking a label will).

Model Data

Model data can be loaded either synchronously through the initialModel property or asynchronously through the loadNodesAsync property. If both are specified then the data from initialModel is overwritten when the loadNodesAsync function returns data.

The data passed to the treeview’s initialModel prop or returned from loadNodesAsync should be an array of nodes, where each node should have:

• Required: A property with a value that will be used as the node’s ID (by default the node looks for a property named id)
• Required: A property with a value that will be used as the node’s label (by default the node looks for a property named label)
• Optional: A property containing any subnodes (by default the node looks for a property named children)
• Optional: A treeNodeSpec property that contains any data about the node’s capabilities and its initial state
• Optional: Any other data you want on your node

The treeNodeSpec of the objects in the data model passed to the treeview’s initialModel property will be updated by the treeview nodes themselves on creation to include missing properties.

{
    id: "node0",
    label: "A checkbox node",
    children: [],
    treeNodeSpec: {
      title: "This will be the value of the node text/label's 'title' attribute.",
      expandable: true,
      selectable: false,
      focusable: true,
      input: {
        type: 'checkbox'
      },
      state: {
        expanded: true,
        selected: false,
        input: {
          value: false,
          disabled: false
        }
      }
    }
  },
  {
    otherIdProp: "node1",
    textProp: "A radio button node",
    subThings: [],
    extraIrrelevantData: "February",
    treeNodeSpec: {
      idProperty: "otherIdProp", // Customize what model props are checked for the id, label, and children
      labelProperty: "textProp",
      childrenProperty: "subThings",
      expandable: true,
      selectable: false,
      input: {
        type: 'radio',
        name: 'rbGroup1',   // Used as the name attribute for the radio button
        value: 'thisValue', // Used as the value attribute for the radio button
        isInitialRadioGroupValue: true // Indicates this should be the initially selected value for the group
      },
      state: {
        expanded: true,
        selected: false
        // No input.value here; to let complex radio button groupings work, state value is
        // bound to an internal tree-level property. input.disabled, however, is valid here for radio buttons.
      },
      addChildCallback: () => Promise.resolve({ id: '1', label: 'label' })
    }
  }

The properties below can be specified for each node. Note that id, label, and children are the default properties nodes look for to get data, but the names of the properties can be overridden using the treeNodeSpec.

The treeNodeSpec property contains any data about the node’s capabilities and its initial state. This keeps the tree-specific data separate from the data of the model itself. This makes it more convenient to drop data into the treeview as-is, potentially with a modelDefaults specified on the treeview to define common values used in the treeNodeSpec of every node.

* If input.type is not supplied, input is forced to null.

** If input.value is not supplied, it defaults to the node’s label value replaced with the regular expression /[\s&<>"'\/]/g, ''

Default Data

If specified, the modelDefaults property of the treeview will be merged with node model’s treeNodeSpec data such that any data not explicitly specified for the node will be set to the value from modelDefaults. This is useful for situations where all (or most) nodes will use the same values. For instance, in a treeview that is all enabled, collapsed, unchecked checkboxes the user could use a modelDefaults of

{
    expandable: true,
    selectable: true,
    input: {
      type: 'checkbox',
    },
    state: {
      expanded: false,
      selected: false,
      input: {
        value: false,
        disabled: false
      }
    }
  }

Public Methods

Events

CSS Classes

The display of the treeview can be customized via CSS using the following classes. Class names are organized in a hierarchy, so a containing node’s class is the prefix of its child classes.

Customizing the TreeView

Customizations Property

It’s often helpful to be able to make adjustments to the markup or styles for the tree. You can provide an object to the modelDefaults.customizations property of the tree to set a customization affecting all nodes, or to the treeNodeSpec.customizations property of a single node. Node-specific customizations will override modelDefault customizations.

A customizations object may have the following properties:

Skins

If adding classes isn’t enough, the entire default styles of the TreeView can be overridden using the skinClass property of the TreeView. When this property is set, the TreeView’s default class of grtv-default-skin is replaced with your own class name, causing all of the built-in style selectors to not match the tree. Instead, you can create your own stylesheet or modify a copy of the default styles to achieve complete control over the tree styling.

Slots

Sometimes the entire content of a node (e.g., the checkbox or text) needs customization beyond what is available through classes. In this case, some slots are available in the TreeView to allow this customization.

Example usage:

<tree-view id="customtree" :initial-model="model">
    <template #text="{ model, customClasses }">
      <!-- The treeview node's model is available, and built-in classes and overrides are available -->
      <marquee :title="model.treeNodeSpec.title"
                class="grtvn-self-text"
                :class="customClasses.treeViewNodeSelfText">
            {{ model[model.treeNodeSpec.labelProperty] }}
      <marquee>
    </template>
  
    <template #checkbox="{ model, customClasses, inputId, checkboxChangeHandler }">
      <label :for="inputId"
          :title="model.treeNodeSpec.title"
          class="grtvn-self-label"
          :class="customClasses.treeViewNodeSelfLabel">
  
        <!-- The generated inputId for the node is available -->
        <input :id="inputId"
               class="my-awesome-checkbox-class"
               type="checkbox"
               :disabled="model.treeNodeSpec.state.input.disabled"
               v-model="model.treeNodeSpec.state.input.value"
               @change="checkboxChangeHandler" /> <!-- The TreeViewNode change handler is available -->
  
        <blink>{{ "Slotted Content for " + model[model.treeNodeSpec.labelProperty] }}</blink>
      </label>
    </template>
  </tree-view>

Asynchronous Loading

Child nodes can be loaded asynchronously by providing a method to the treeNodeSpec.loadChildrenAsync property of the model. The method will be called when the node is expanded, and the property containing the node’s children will be overwritten with the results of the async call. For example, the following could be used as modelDefaults that would have every node load children when it was expanded.

{
    expandable: true,
    loadChildrenAsync: (m) => axios.get(`/children/${m.id}`)
  }

The method may accept one argument, which will be the model of the node that has been expanded. It should resolve to an array of child node models.

The load method is called once, and after that the children are part of the model and are not reloaded.

Drag and Drop

A user can drag and drop an individual TreeViewNode. A drag only affects the node where the dragging starts, and has nothing to do with any node selection within the tree. To make a node draggable, the node’s treeNodeSpec.draggable must be true. To make a node accept drops, the node’s treeNodeSpec.allowDrop must be true. Both Move and Copy operations are supported. To copy in most browsers hold down the Ctrl key while dragging.

When dropping a node on another node, there are three areas of the target node where a drop can occur. If dropped at the top of the target node in the shaded area then the node will be inserted before the target. If dropped at the bottom of the target node in the shaded area then the node will be inserted after the target. If dropped directly on the of the target node then the node will be inserted as a child of the target. The drop can occur on a node in the same tree or in a different tree as long as the receiving node allows drops.

The drop can also occur anywhere that allows dropping data with the application/json or text/plain MIME types (e.g., a simple text input field or a text editor).

When copying a node the newly created node will have its own unique identifier, will not be the currently focusable node even if the source node was the focusable node.

When moving a node within the same tree, the actual node is moved within the tree data. If the node is copied within the same tree, any function members of the node data (e.g., the addChildCallback) are copied.

When a node is moved or copied to a different tree, the node data that passes between trees does not contain any of the functions from the original node data.

Aria

ARIA Accessibility recommendations have been implemented at a basic level. This means keyboard navigation follows ARIA recommendations, but the component has not been tested with a screen reader and, since many screen readers exhibit different behaviors for treeview controls anyway, it would be expected to fail articulation checks in many cases. Additionally, some recommended keyboard controls are not implemented (e.g., Expand All Nodes, Type-ahead Focusing). When using the component, there are only a couple of things you need to know.

Setting Key Bindings

The keys used to navigate the treeview can be customized using the customAriaKeyMap prop of the TreeView component. The value of the prop is an object, with each attribute named for a type of action and its value as an Array of integer key codes that trigger that action.

* The previous visible node is a)the focused node’s previous sibling’s last child if visible, b)the previous sibling if it has no children or is collapsed, or c)the parent node.

** The next visible node is a)the focused node’s first child if one exists and the focused node is expanded, b)the focused node’s next sibling if one exists, or c)the focused node’s parent’s next sibling if one exists.

Focusable

The treeview uses a roaming tab index to maintain focusability in the tree. A node model can specify a treeNodeSpec.focusable property of true in order for that node to be used as the initial target of keyboard focus within the treeview. If multiple node models specify this then only the first will have treeNodeSpec.focusable set to true once the treeview is intialized. If no models have it specified then the first selected node in the treeview is given a treeNodeSpec.focusable of true. If there are no selected nodes then the first node in the treeview is given a treeNodeSpec.focusable of true.

More about ARIA TreeViews

WAI-ARIA Authoring Best Practices, Tree View