Tree Selectors

Most common uses are bulk selections of sub-options, and a file/directory browser.

Selector

Mostly used as a tree structure for selection which options a user wants when there are nested options.

A good example is excluding tables from databases.

Select this item (Checkbox) Parent / Group
- Child / Group
  - Select this item Sub Child Item
  - Sub Child Item
  - Sub Child Item
- Child / Group
  - Sub Child Item
  - Sub Child Item
  - Sub Child Item
Parent / Group
- Child / Group
  - Sub Child Item
  - Sub Child Item
  - Sub Child Item
Parent / Single
Parent / Single (Disabled)

Directory Browser Used for browsing and selecting files and folders. Most common use case can be found in Smush’s Directory Browsing feature.

Directory browser allows you to have a simple form to add extra folders. Search for the "+" button to try it.

wp-admin
- file.php
- file.php
- file.php
wp-content
- plugins
  - Forminator
    - file.php
    - file.php
    - file.php
  - Hummingbird
    - file.php
    - file.php
    - file.php
  - Hustle
    - file.php
    - file.php
    - file.php
  - hello.php
  - index.php
- themes
  - divi
    - assets
      - images
        
        image.jpg
        
        image.jpg
        
        image.jpg
        
        image.jpg
      - css
        
        styles.min.css
        
        styles.min.css
        
        styles.min.css
        
        styles.min.css
      - js
        
        scripts.min.js
        
        scripts.min.js
        
        scripts.min.js
        
        scripts.min.js
      - fonts
        
        custom-font.eot
        
        custom-font.svg
        
        custom-font.ttf
        
        custom-font.woff
        
        custom-font.woff2
    - file.php
    - file.php
  - twentyseventeen
    - file.php
    - file.php
    - file.php
    - file.php
- uploads
  - 2017
    - image.jpg
    - image.jpg
    - image.jpg
  - 2018
    - image.jpg
    - image.jpg
    - image.jpg
  - 2019
    - image.jpg
    - image.jpg
    - image.jpg
wp-includes
- file.php
- file.php
- file.php

Documentation

Simple Tree Find here the basics to make SUI Tree work correctly on your installation.

1. Initialize JS

Initialize JS 1. Get latest stable Shared UI release. 2. Load shared-ui.js on your plugin or trees.js file if you are using individual components. 3. SUI.suiTree() will initialize auto-magically on load, but if this doesn't happen you can initialize it on your installation by running the following script:

$( function() {

	// Init SUI Tree
	if ( 0 !== $( 'SUI_BODY_CLASS .sui-tree' ).length ) {

		$( 'SUI_BODY_CLASS .sui-tree' ).each( function() {
			SUI.suiTree( $( this ), false );
		});
	}

}( jQuery ) );

2. Markup Selectors Tree

Starter Markup Here you will find two different base markups that will work with Simple Tree. Click on each tab to see more details. NOTE: Please pay attention to the notes I left in the sample code.

Basic Mode This markup uses only <span />'s inside <li /> reason why elements like checkboxes or buttons are handled with roles to make them correctly accessible for screen readers.

<ul class="sui-tree" data-tree="selector" role="group">

	<li role="treeitem">

		<span class="sui-tree-node">

			<!-- Checkbox -->
			<span class="sui-node-checkbox" role="checkbox">
				<span class="sui-screen-reader-text">Select this item</span>
			</span>

			<!-- Text -->
			<span class="sui-node-text">Parent / Group</span>

			<!-- Button expander (for open/close) -->
			<span role="button" data-button="expander">
				<span class="sui-screen-reader-text">Open or close this item</span>
			</span>

		</span>

		<!-- NOTE:
		Wrap more items inside UL to create a new group inside parent item
		-->
		<ul role="group">

			<li role="treeitem">

				<span class="sui-tree-node">

					<!-- Checkbox -->
					<span class="sui-node-checkbox" role="checkbox">
						<span class="sui-screen-reader-text">Select this item</span>
					</span>

					<!-- Text -->
					<span class="sui-node-text">Child Item</span>

					<!-- IMPORTANT:
					Notice expander button isn't here, this because it's not necessary.
					If for any case you can't remove the expander button from the markup
					don't worry because the JS function will check if item doesn't have
					child elements and will remove the expander button.
					-->

				</span>

			</li>

		</ul>

	</li>

</ul>

If you need to get the value assigned to checkbox, that must be retrieved using JS. For example, assign data-attribute="..." and check on change if li has aria-selected="true" attribute.

Complex Mode This markup uses <div />'s and other regular markup inside <li />.

<ul class="sui-tree" data-tree="selector" role="group">

	<li role="treeitem">

		<div class="sui-tree-node">

			<!-- Checkbox -->
			<label for="unique-checkbox-id" class="sui-node-checkbox">
				<input
					type="checkbox"
					id="unique-checkbox-id"
				/>
				<span aria-hidden="true"></span>
				<span>Select this item</span>
			</label>

			<!-- Text -->
			<span class="sui-node-text">Parent / Group</span>

			<!-- Button expander (for open/close) -->
			<button data-button="expander">
				<span aria-hidden="true"></span>
				<span class="sui-screen-reader-text">Open or close this item</span>
			</button>

		</div>

		<!-- NOTE:
		Wrap more items inside UL to create a new group inside parent item
		-->
		<ul role="group">

			<li role="treeitem">

				<div class="sui-tree-node">

					<!-- Checkbox -->
					<label for="unique-checkbox-id" class="sui-node-checkbox">
						<input
							type="checkbox"
							id="unique-checkbox-id"
						/>
						<span aria-hidden="true"></span>
						<span>Select this item</span>
					</label>

					<!-- Text -->
					<span class="sui-node-text">Child Item</span>

					<!-- IMPORTANT:
					Notice expander button isn't here, this because it's not necessary.
					If for any case you can't remove the expander button from the markup
					don't worry because the JS function will check if item doesn't have
					child elements and will remove the expander button.
					-->

				</div>

			</li>

		</ul>

	</li>

</ul>

If you need to get the value assigned to checkbox, that must be retrieved using JS. For example, assign data-attribute="..." and check on change if li has aria-selected="true" attribute.

3. Markup Directory Browser Tree

This markup supports complex mode markup variations mentioned on Selectors Tree markup.

Starter Markup This is the basic markup for directory browser tree and contains parent and child items. NOTE: Please pay attention to the notes I left in the sample code.

<ul class="sui-tree" data-tree="directory" role="group">

	<li role="treeitem">

		<span class="sui-tree-node">

			<!-- Button expander (for open/close) -->
			<span role="button" data-button="expander">
				<span class="sui-screen-reader-text">Open or close this item</span>
			</span>

			<!-- Checkbox -->
			<span class="sui-node-checkbox" role="checkbox">
				<span class="sui-screen-reader-text">Select this item</span>
			</span>

			<!-- Icon -->
			<span aria-hidden="true"></span>

			<!-- Text -->
			<span class="sui-node-text">Parent / Group</span>

		</span>

		<!-- NOTE:
		Wrap more items inside UL to create a new group inside parent item
		-->
		<ul role="group">

			<li role="treeitem">

				<span class="sui-tree-node">

					<!-- IMPORTANT:
					Notice expander button isn't here, this because it's not necessary.
					If for any case you can't remove the expander button from the markup
					don't worry because the JS function will check if item doesn't have
					child elements and will remove the expander button.
					-->

					<!-- Checkbox -->
					<span class="sui-node-checkbox" role="checkbox">
						<span class="sui-screen-reader-text">Select this item</span>
					</span>

					<!-- Icon -->
					<span aria-hidden="true"></span>

					<!-- Text -->
					<span class="sui-node-text">Child Item</span>

				</span>

			</li>

		</ul>

	</li>

</ul>

4. Tricks

1. Expand Item Add aria-expanded="true" to show parent item child elements on load.

<li role="treeitem" aria-expanded="true"> ... </li>

2. Select Item Add aria-selected="true" to check an item on load.

<li role="treeitem" aria-selected="true"> ... </li>

3. Disable Item Add aria-disabled="true" to disable an item and its childs.

<li role="treeitem" aria-disabled="true"> ... </li>

4. Change Item Icon Add data-type=" ... " to change an item icon. Don't forget to replace ... with the type of icon you want to use.

Basic Icons

<!-- TYPE: Page (Default icon for simple items) -->
<span data-type="page" aria-hidden="true"></span>

<!-- TYPE: Folder (Default icon for parent items) -->
<span data-type="folder" aria-hidden="true"></span>

<!-- TYPE: PDF -->
<span data-type="pdf" aria-hidden="true"></span>

<!-- TYPE: ZIP -->
<span data-type="zip" aria-hidden="true"></span>

<!-- TYPE: Image -->
<span data-type="image" aria-hidden="true"></span>

<!-- TYPE: Padlock (locked) -->
<span data-type="lock" aria-hidden="true"></span>

Logo Icons

<!-- TYPE: WPMU DEV Logo -->
<span data-type="wpmudev" aria-hidden="true"></span>

<!-- TYPE: Defender Logo -->
<span data-type="defender" aria-hidden="true"></span>

<!-- TYPE: Smush Logo -->
<span data-type="smush" aria-hidden="true"></span>

<!-- TYPE: Hummingbird Logo -->
<span data-type="hummingbird" aria-hidden="true"></span>

<!-- TYPE: Uptime Logo -->
<span data-type="uptime" aria-hidden="true"></span>

<!-- TYPE: Smartcrawl Logo -->
<span data-type="smartcrawl" aria-hidden="true"></span>

<!-- TYPE: Forminator Logo -->
<span data-type="forminator" aria-hidden="true"></span>

<!-- TYPE: Shipper Logo -->
<span data-type="shipper" aria-hidden="true"></span>

<!-- TYPE: Snapshot Logo -->
<span data-type="snapshot" aria-hidden="true"></span>

<!-- TYPE: Hustle Logo -->
<span data-type="hustle" aria-hidden="true"></span>

<!-- TYPE: Performance Logo -->
<span data-type="performance" aria-hidden="true"></span>

5. Simple Form On Directory Browser Tree you can allow a parent item to add a new child item through a simple form.

Enable show/hide animation for the simple form by editing the tree function like this: SUI.suiTree( $( this ), true );

NOTE: This comes enabled by default from SUI but in case is not change above on the function might help you.

<ul class="sui-tree" data-tree="directory" role="group">

	<li role="treeitem">

		<span class="sui-tree-node">
			<span role="button" data-button="expander">
				<span class="sui-screen-reader-text">Open or close this item</span>
			</span>
			<span class="sui-node-checkbox" role="checkbox">
				<span class="sui-screen-reader-text">Select this item</span>
			</span>
			<span aria-hidden="true"></span>
			<span class="sui-node-text">Parent / Group</span>
			<span role="button" data-button="add">
				<span class="sui-screen-reader-text">Add new folder</span>
			</span>
		</span>

		<ul role="group">

			<span role="contentinfo">

				<span id="label-unique-id" class="sui-screen-reader-text">Folder name</span>

				<span role="form">

					<input
						type="text"
						value=""
						placeholder="New folder name;"
						id="unique-id"
						aria-labelledby="label-unique-id"
					/>

					<span role="button">
						<span class="sui-screen-reader-text">Add Folder</span>
					</span>

				</span>

				<span role="button" data-button="remove">
					<span class="sui-screen-reader-text">Remove Folder</span>
				</span>

			</span>

			<!-- Already existing item -->
			<li role="treeitem">

				<span class="sui-tree-node">
					<span class="sui-node-checkbox" role="checkbox">
						<span class="sui-screen-reader-text">Select this item</span>
					</span>
					<span aria-hidden="true"></span>
					<span class="sui-node-text">Child Item</span>
				</span>

			</li>

		</ul>

	</li>

</ul>

Fancy Tree Find here the basics to make Fancy Tree JS with SUI styles work in your plugin.

1. Installation

Installation 1. Get latest Fancytree JS. Read their Wiki for correct steps. 2. Init Fancytree JS on your plugin:

$( function() {

	// Init fancy tree
	$( '#tree-id' ).fancytree({
		// Put here all your settings
	});

}( jQuery ) );

In the showcase we use Fancytree JS 2.27.0 because latest available version 2.30.2 has an annoying bug that makes page scroll up or down when you click on an item.

2. Markup

Markup Selector Notice the class and attribute to load the correct styles for your tree.

<div
	id="tree-id"
	class="sui-tree-fancy"
	data-tree="selector"
></div>

Markup Directory Browser Notice the class and attribute to load the correct styles for your tree.

<div
	id="tree-id"
	class="sui-tree-fancy"
	data-tree="directory"
></div>

3. Tricks Fancytree JS

1. Enable / Disable Checkbox You can do this globally (for all checkboxes on tree) or per item.

$( function() {

	$( '#tree-id' ).fancytree({

		// (Bool) global checkbox
		checkbox: false,

		// (Bool) Checkbox per item
		source: [
			{ title: 'Item', checkbox: true }
		],
	});

}( jQuery ) );

2. Expand Item Some times you need an item expanded and show its child items as soon as tree loads.

$( function() {

	$( '#tree-id' ).fancytree({

		source: [
			{
				title: 'Item',
				expanded: true, // Expand item on load
				child: [ { title: 'Child Item' } ] // IMPORTANT: For expand to work correctly make sure you have child items
			}
		],
	});

}( jQuery ) );

3. Custom Icon When you use Directory Browser tree mode, notice each item have an icon (can be a folder or a page). To change the item icon follow this code example.

$( function() {

	$( '#tree-id' ).fancytree({

		// Replace icon per item
		source: [
			{
				title: 'Item',
				icon: 'sui-icon-photo-picture' // Replace this with any SUI icon class
			}
		],

		// Replace folder icon (globally)
		icon: function( event, data ) {

			if ( data.node.isFolder() ) {
				return 'sui-icon-folder'; // Replace this with any SUI icon class.
			}
		},
	});

}( jQuery ) );

4. Remove Icons When you use Selectors tree mode, notice items don't have an icon. By default Fancytree JS enables these icons, you need to remove them to make it match the design.

$( function() {

	$( '#tree-id' ).fancytree({

		// Remove icons (globally)
		icon: false,

	});

}( jQuery ) );