Noodel.js

😃 Intuitive

Noodel is simple and intuitive. Most people immediately understand how it works. It aims to leverage the user's spatial memory for navigation, and reduce screen clutter and cognitive load.

📱 Device agnostic

Noodel's layout and navigation mechanism remains identical regardless of screen size and input method. By reducing the essential controls to 4-way movements, it can be easily used in contexts where control ability is limited.

💪 Flexible

Everything about Noodel is designed to be flexible - from its fully customizable styles and layout, to what kind of content you can put in.

🚀 Dynamic

Noodel is more than just a static content viewer, although you can certainly use it that way. It provides an extensive API with navigation methods and getters, and allows you to insert, update or delete nodes at any time.

⚡ Performant

Noodel is built with performance in mind using modern best practices. It uses the powerful Vue.js library under the hood for DOM management and updates.

✨ Interactive

And finally, who doesn't like an interface that feels like it walked out from a sci-fi movie? Noodel is responsive, interactive and comes with fancy animation effects. It's just cool.

Noodel encourages you to break down large blocks of content into smaller chunks, which is generally good for readability.

A node should never exceed the size of the viewport - a precondition for node-based navigation.

In other words, a branch refers to a node's list of children. Each branch is always uniquely associated with a node - the parent node of the branch.

Direct script embed

You can use Noodel by directly embedding its script and CSS into your HTML:

                            
                                // You should specify the version number (e.g noodel@3.0.0) in production
                                <script src="https://cdn.jsdelivr.net/npm/noodel/dist/noodel.umd.min.js"></script>
                                <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/noodel/dist/noodel.min.css">
                                <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/noodel/dist/noodel-default.min.css">
                            
                        

Noodel can be obtained via npm-linked CDNs such as jsdelivr and unpkg. It is bundled as a UMD package and available in minimized (production) and non-minimized (development) versions.

npm

For more complex projects that use bundlers, install from npm:

                        
                            npm install noodel
                        
                        

And import into your code:

                            
                                import Noodel from 'noodel'

                                // Don't forget to also include the CSS from Noodel's module directory
                            
                        

Stylesheets

Noodel comes with a "core" stylesheet, noodel.css, and a theming stylesheet, noodel-default.css.

The core stylesheet contains styles critical for Noodel's functioning and needs to be included in all cases.

The theming stylesheet provides a default grayscale theme with basic transitions for Noodel's visual effects. You can include this stylesheet and tweak it for customization, or replace it altogether with your own custom theme. See Styling for more details.

Creating a noodel

Creating a noodel is simple. The basic operations are:

                            
                                // Creates a view model based on the given content tree
                                const noodel = new Noodel(contentTree);
                                
                                // Renders the view into an element on the page
                                noodel.mount(container);
                            
                        

The contentTree is an element selector or array of objects that specifies the content tree, and container is the target container element for placing the noodel.

Defining content tree via HTML

For sites driven by static HTML templates, you can define the tree via HTML and give the root element to the constructor:

                        
                            <div id="noodelDefinition" style="display: none;">
                                <div class="node">
                                    <p>My first node</p>
                                </div>
                                <div class="node">
                                    <p>My second node</p>
                                    <div class="node">
                                        <p>First child of my second node</p>
                                    </div>
                                </div>
                            </div>

                            <div id="noodel"></div>

                            <script>
                                const noodel = new Noodel("#noodelDefinition");
                                noodel.mount("#noodel");
                            </script>
                        
                    

Defining content tree via object array

Alternatively, for dynamic sites/apps driven by JavaScript, you can specify the content tree as an array of objects corresponding to nodes on the first level:

                        
                            const contentTree = [
                                {
                                    content: "<p>My first node</p>"
                                },
                                {
                                    content: "<p>My second node</p>"
                                    children: [
                                        {
                                            content: "<p>First child of my second node</p>"
                                        }
                                    ]
                                }
                            ];

                            const noodel = new Noodel(contentTree);
                            noodel.mount("#noodel");
                        
                    

Specifying options

Setting options can only be done via JavaScript. If your noodel is defined by an HTML template you still need to set your noodel and node options programmatically.

                            
                                // setting options for individual nodes
                                const nodeDefinition = {
                                    options: {
                                        showChildIndicator: false,
                                        focalAnchorTrunk: (size) => size / 3
                                    }
                                }

                                // setting global options for the noodel
                                const noodel = new Noodel([nodeDefinition], {
                                    visibleSubtreeDepth: 5,
                                    focalAnchorTrunk: (size) => size / 4
                                });
                            
                        

Specifying node ID

By default, a unique ID will be generated for each node, which will be used for various purposes. You can provide your own ID for nodes using a data attribute:

                            
                                <div class="node" data-id="myCustomId">
                                    ...
                                </div>
                            
                        

or in JavaScript:

                            
                                const nodeDefinition = {
                                    id: "myCustomId",
                                }
                            
                        

Your custom ID must be unique and should not start with "_" as it may conflict with Noodel's default IDs.

Specifying initial active child

By default, the initial active child for each node is at index 0 (the first child). You can specify another child to be initially active by using:

                        
                            <div class="node" data-active>
                                ...
                            </div>
                        
                    

or in JavaScript:

                            
                                const nodeDefinitions = [
                                    {
                                        content: "First child"
                                    },
                                    {
                                        isActive: true, // this node will be active instead
                                        content: "Second child"
                                    },
                                ];
                            
                        

Specifying custom CSS classes/styles

You can assign custom CSS classes/styles to the various DOM elements associated with each node. See here for the list of different elements you can style.

                            
                                <div 
                                    class="node" 
                                    data-class-node="myClassA myClassB"
                                    data-class-content-box="myClassC"
                                    data-style-content-box="color: green; max-width: 900px;"
                                >
                                    ...
                                </div>
                            
                        

or in JavaScript:

                            
                                const nodeWithCustomStyles = {
                                    classNames: {
                                        node: "myClassA myClassB",
                                        contentBox: "myClassC"
                                    },
                                    style: {
                                        contentBox: "color: green; max-width: 900px;"
                                    }
                                }
                            
                        

Specifying branch content

You can optionally define content that will be associated with a node's child branch rather than individual nodes. This branch content will only be displayed if the node has a branch (i.e. has at least 1 child).

For HTML templates this is specified via a div with the class "branch-content":

                            
                                <div class="node" >
                                    Some node content...
                                    <div class="branch-content">
                                        Any content inside here will be treated as branch content
                                    </div>
                                </div>
                            
                        

or in JavaScript:

                            
                                const nodeDefinition = {
                                    content: "node with branch content",
                                    branchContent: "this is a special branch"
                                }
                            
                        

Listening to events

You can attach one or more event listeners for each event on both the noodel and its individual nodes. See here for the list of events available.

                            
                                const noodel = new Noodel([]);
                                const onFocalNodeChange = () => console.log("focal node has changed");
                                const anotherListener = () => console.log("another listener triggered");
                                
                                noodel.on("focalNodeChange", onFocalNodeChange); // attach listener
                                noodel.on("focalNodeChange", anotherListener); // attach another listener
                                noodel.off("focalNodeChange", onFocalNodeChange); // detach listener
                            
                        

Preventing navigation

By default, a noodel responds to four types of user input for navigation: swipe(drag), keyboard, scroll wheel, and tap. Navigation will occur even when such input originates from content elements inside nodes.

This behaviour can be undesirable when you have UI elements that should capture those inputs and prevent them from causing navigation, e.g. a slider or a textbox.

Prevention classes

To address this issue, Noodel provides the following "prevention classes" that you can selectively apply to individual elements in your content:

• nd-prevent-swipe
• nd-prevent-key
• nd-prevent-wheel
• nd-prevent-tap

Noodel will ignore the input that originates from an element (or its descendants) with the corresponding prevention class and stops it from triggering any Noodel-specific behaviour.

                            
                                <div class="node">
                                    <input type="text" class="nd-prevent-swipe nd-prevent-key"></input>
                                    <button class="nd-prevent-tap">Submit</button>
                                </div>
                            
                        

Caveat

You should use prevention classes sparingly, on elements that really need them. Having large blocks of content with navigation prevention may impact usability, especially on smaller screens.

For situations that require extensive navigation prevention, you should rely on the inspect mode instead. Alternatively, you can disable the corresponding input in Noodel's options and provide your own means of navigation via Noodel's API.

Summary

For swipe-based interfaces such as Noodel, there is always an unavoidable conflict between the swipe mechanism and native mechanisms that depend on the same motion, such as text selection.

The inspect mode is the solution Noodel offers to address this issue. By default, text selection is disabled on a noodel and all input directed towards navigation. Once inspect mode is on, all navigation methods will be suspended and the user is free to select text or perform other conflicting interactions e.g. drag-and-drop in the focal node.

It is recommended that you rely on inspect mode, in addition to prevention classes, to deal with situations where UI elements in your content conflict with Noodel's mechanism.

Inspect mode trigger

The default trigger for inspect mode is the double tap (on any area of the noodel), or the Enter key on a keyboard.

This trigger is chosen for maximum convenience and compatibility, but like anything else it does end up conflicting with interactions such as multiple clicks to select a word/line. If you wish to prevent the default trigger you can always disable it through Noodel's options and provide your own means of toggling inspect mode (e.g a custom button) via Noodel's API.

Viewing overflow content

The inspect mode is also used for viewing overflow content in nodes. Scrolling inside nodes is disabled normally but enabled during inspect mode.

Noodel is based on the principle of content chunking. Because each node has a limited space, as a general rule, you should try to break down large blocks of content into bite-sized pieces that can fit into individual nodes.

However, this can be impractical in many situations, so inspect mode is provided as a fallback for viewing overflow content.

The view model

The object instance you get when you create a noodel is its "view model". You can also obtain the view model of individual nodes via methods on the noodel instance.

These view models have 2-way sync with the view, and provide extensive API methods for you to dynamically query and update almost every aspect of the content tree.

                            
                                // view model of whole noodel
                                const noodel = new Noodel(...);

                                // view model of an individual node
                                const currentFocalNode = noodel.getFocalNode();
                            
                        

Programmatic navigation

                            
                                const noodel = new Noodel(...);
                                const node = noodel.findNodeById("someNode");

                                // move to the next node
                                noodel.moveForward();

                                // move 2 steps back towards ancestors
                                noodel.moveOut(2);

                                // move to the 3rd branch in the active tree
                                noodel.setFocalLevel(3);

                                // jump to a specific node
                                node.jumpToFocus();
                            
                        

Updating node properties

                            
                                const node = noodel.findNodeById("someNode");

                                // update node content
                                node.setContent("new content");

                                // update node styles
                                node.setStyles({
                                    contentBox: "color: green"
                                });

                                // update node options
                                node.setOptions({
                                    focalAnchorTrunk: () => 100
                                })
                            
                        

Node insertion and deletion

                            
                                const rootNode = new Noodel([{}]).getRoot();

                                // insert nodes and their descendants at index 0
                                rootNode.insertChildren([
                                    {
                                        content: "Fruits!",
                                        children: [
                                            {
                                                content: "Tomatoes!"
                                            }
                                        ]
                                    },
                                    {
                                        content: "Vegetables!"
                                    }
                                ], 0);

                                // you can also insert new nodes from an HTML template
                                rootNode.insertChildren("#nodeDefinition");

                                // delete nodes
                                rootNode.deleteChildren(1, 2);
                            
                        

View state persistence

The noodel's view state is independent of whether it's mounted or not. You can mutate it while the noodel is not mounted and the change will persist.

                            
                                const noodel = new Noodel(...);

                                // make jump before view is mounted
                                noodel.jumpTo(noodel.findNodeById("firstFocus"));

                                // the view will focus on the "firstFocus" node initially
                                noodel.mount("#container");

                                // the view model is still focused on the same node after unmount
                                noodel.unmount();
                                noodel.getFocalNode().getId(); // ==> "firstFocus"
                            
                        

Using nextTick()

When using Noodel's API, all changes to Noodel's view model are synchronous, while any DOM updates triggered by these changes will be asynchronous. This means that, if you need to do operations that depends on the updated DOM state, you must wait for the updates to settle before doing so.

The nextTick() function is Noodel's preferred way to wait for DOM updates to fully complete and settle. One common use case is to wait for the view to mount before querying a DOM element:

                                                            
                                noodel.mount("#noodel");
                                noodel.nextTick(() => {
                                    // gets the canvas element after the view is actually mounted
                                    const canvasEl = noodel.getEl();
                                });
                            
                        

                                     
                                    // this operation inserts a node, then jumps to it                               
                                    
                                    const newNode = someNode.insertChildren([{}], 1)[0];                                     
                                    // Because it takes one DOM update cycle to capture the size of new nodes, the movement may glitch if you do this synchronously. Using nextTick will make the animation smooth.
                                    noodel.nextTick(() => {                                      
                                        newNode.jumpToFocus();
                                    });
                                
                            

Layout options

Noodel has a variety of layout options that, when used in combination, can customize the layout in almost every way you can think of.

To use these options properly, you need to understand the concepts of the branch axis and the trunk axis, which are used in place of the horizontal and vertical axes depending on the noodel's orientation.

Orientation and branch direction

The orientation option specifies the direction of the trunk axis, and can be either ltr (default), rtl, ttb (top-to-bottom) and btt (bottom-to-top).

The branch direction option specifies how a branch layout its nodes, and can be either "normal" (default) or "reverse". When the trunk axis is the horizontal axis (i.e. ltr or rtl), "normal" puts nodes from top to bottom, and "reverse" the opposite. When the trunk axis is the vertical axis, "normal" puts nodes from left to right, and "reverse" the opposite.

Focal offsets and anchor offsets

The focal offsets specify the "snap-to lines" on the canvas where the focal branch and active nodes align to, on their respective axis. These are calculated as a function of the canvas length, and defaults to 1/2 of the canvas length (i.e. the center).

The anchor offsets specify the "snap-to lines" on each branch/node that should be aligned to the focal offset, on their respective axis, when they become focal or active. These are calculated as a function of the length of the branch/node, and defaults to 1/2 of their length (i.e. the center).

These offsets can be specified globally and/or customized on each individual node. When used in combination, you can decide how and where the branches and nodes align in a highly flexible way.

Handling element resize

In Noodel v3, automatic resize detection has been removed in favor of a manual approach, to address some limitations and improve performance.

If the noodel is mounted, and something happens that causes the size of nodes/branches/canvas to change, you should immediately call one of Noodel's various realign() methods to register the size change and reposition elements as necessary.

                            
                                // this operation will cause the size of someNode to change on both axes
                                someNode.setStyle({
                                    contentBox: "width: 200px; height: 300px"
                                });

                                // immediately call realign to capture node resize on the branch-axis
                                someNode.realign();

                                // parent need to realign branch since the change also caused branch resize on the trunk-axis
                                someNode.getParent().realignBranch();
                            
                        

                                
                                    // if everything is dependent on viewport units...
                                    window.addEventListener("resize", () => {
                                        noodel.realignAll();
                                    });

                                    // ideally, you should debounce the function above for better performance
                                
                            

Summary

Noodel has a routing capability which is enabled by default. This allows Noodel to control the hash of your URL to sync with the location of the current focal node. It will use the ID of the focal node as the fragment identifier.

This allows you to use the browser's history navigation to jump between nodes, as well as create URL links that target specific nodes in a noodel.

History push behavior

Only explicit changes to the URL (e.g. by clicking on a link) will cause a new entry to be pushed to the browser history. Noodel uses history.replaceState() to replace the URL hash as you navigate around the noodel to prevent creating too many unnecessary entries. This includes when you use Noodel's API to navigate.

Caveat

You should use routing on one noodel per page only (ideally, when you use a single noodel to control a site). Routing behaviour for multiple noodels on the same page is not well defined.

Due to the fact that Noodel does not use native scrolling for its navigation, basic Ctrl+F search in browsers will not be able to jump to individual occurrences. You may need to implement your own search function for your noodel.

For a simple DOM based text search plugin for Noodel, see noodel-search.

Summary

You can control most aspects of Noodel's appearance using plain CSS, by extending/overriding Noodel's CSS classes, or by setting custom class/styles on individual nodes.

In addition, you have complete freedom in structuring and styling the content inside your nodes.

Styling via Noodel's CSS classes

Noodel comes with a "core" stylesheet that determines the layout, and a theming stylesheet with a default theme. While you must keep the core stylesheet, you can override or replace the CSS rules in the theming stylesheet as you see fit.

All of Noodel's DOM elements have various built-in CSS classes attached dynamically. See CSS classes for the list of classes you can work with.

Styling via node-specific class/styles

You can specify custom class/styles for each node that will be applied to the nd-node element. This is useful when you need to have different types of nodes (e.g large vs small) in the same tree.

See specifying custom class/styles for example.

Controlling node size

The size of nodes are completely flexible - they are simply placed in a flex container, and will grow or shrink to fit their content while respecting any CSS rules applied.

This means you can control the size of nodes by specifying their various height, width and flex properties. In addition, you can style your content and let them influence the size of their node containers.

                            
                                .nd-canvas {
                                    height: 100vh;
                                    width: 100vw;
                                }

                                .nd-node {
                                    height: 100vh;
                                    width: 100vw;
                                }
                            
                        

Controlling animations

All animations in Noodel are done via CSS transitions. This means you can control the duration and timing functions of all animations via CSS overrides of the corresponding classes.

Enter/leave animations make use of the transition classes of Vue.js. You can apply any combination of them according to your needs.

Movement animations use transitions of the CSS transform property. These should be specified on the nd-xxx-move classes for the corresponding element, and should only be specified on these classes. The move classes are always attached on their elements and temporarily removed when necessary to disable transform transitions.

Summary

Noodel uses Vue.js internally and hence provides integration with Vue out of the box. Noodel is available as a Vue component, and also allows you to use Vue components as the content for individual nodes.

Using the Vue-less build

If you are including Noodel and Vue's scripts directly in your HTML, it is recommended that you use Noodel's Vue-less build, alongside the Vue script used in your main project (Noodel requires Vue V3). This prevents Vue from being included twice.

If you are using Noodel via a bundler, the default entry is the Vue-less build and the bundler should be able to take care of bundling Vue as a dependency.

Using Noodel's Vue component

Noodel's Vue component is exposed as a static variable on the Noodel class, which can be used like any other Vue components. The way to use it is as follows:

                            
                                import Noodel from 'noodel';
                                import { createApp } from 'vue';

                                const NoodelComponent = Noodel.VueComponent;                            
                                const app = createApp({
                                    component: {
                                        NoodelComponent
                                    },
                                    template: '<NoodelComponent :noodel="noodel.getState()"/>',
                                    data: {
                                        noodel: new Noodel([])
                                    }
                                });
                                
                                app.mount("#el");
                             
                        

Using Vue components as node content

You can pass Vue components as node content and they will be rendered via Vue's dynamic component feature, i.e. <component :is="yourComponent"></component>. To do so, you need to provide an object as node content:

                        
                            const noodel = new Noodel([
                                {
                                    content: {
                                        component: YourVueComponent, // your Vue component reference
                                        props: { // name-value pairs of props to pass to this component
                                            "propA": "abc",
                                            "propB": 20
                                        },
                                        eventListeners: { // name-value pairs of event listeners to attach onto the component
                                            "onButtonClick": () => console.log("button click")
                                        }
                                    }
                                }
                            ]);
                        
                    

Noodel is completely written in TypeScript, fully typed and documented.

You don't need to install any additional type declarations - they come bundled out of the box when you install via npm.

Noodel is targeted to work on all major modern browsers.

Support for IE 10 and 11 is best-effort only - Noodel should work on these browsers, but there may be quirks and bugs in some features.

IE 9 and below are not supported.

Lifecycle

Query

Update / Navigation

Alignment

Event

Query

Update / Navigation

Tree Mutation

Traversal

Alignment

Event

ID of this node. If provided, must be unique and should NOT start with "_" .

Children nodes of this node. Defaults to an empty array.

If provided, will mark this node as active, overriding the default (first child). If multiple siblings are marked as active, only the first one will take effect.

Content of this node. If is a string, will be inserted as innerHTML of the nd-content-box element. Can also be a ComponentContent object that wraps a Vue component.

Content for this node's child branch. If is a string, will be inserted as innerHTML of the nd-branch-content-box element. Can also be a ComponentContent object that wraps a Vue component. Only rendered if this node has a child branch (i.e. has at least 1 child).

An object specifying custom CSS class(es) to apply to various elements associated with a node. Each property should be a string of one or more classes delimited by spaces.

An object specifying custom CSS styles to apply to various elements associated with a node. Each property should be a string in inline style format.

Options for this node.

The number of levels of descendant branches to show after the current focal branch. Defaults to 1.

If true, will keep the current branch depth (if possible) when tapping on the sibling of an ancestor. Useful to create an effect similar to conventional navigation menus. Defaults to false.

Whether to apply the default keyboard navigation. Defaults to true.

Whether to apply the default wheel navigation. Defaults to true.

Whether to apply the default swipe navigation. Defaults to true.

Whether to apply the default tap navigation. Defaults to true.

Whether to allow toggling inspect mode via the Enter key. Defaults to true.

Whether to allow toggling inspect mode via the double tap. Defaults to true.

Whether routing should be enabled for this noodel. Defaults to true.

Number of pixels to move for every pixel swiped in the branch axis. Defaults to 1.

Number of pixels to move for every pixel swiped in the trunk axis. Defaults to 1.

Number of nodes (per unit of velocity) to snap across after a swipe is released. Defaults to 1.

Number of levels (per unit of velocity) to snap across after a swipe is released. Defaults to 1.

Whether to render the limit indicators of the canvas. Defaults to true.

Whether to render the child indicators of nodes. Defaults to true.

Determines the direction of the trunk axis. Defaults to 'ltr' (left to right).

Determines the direction of the branch axis under the current trunk orientation. Defaults to 'normal'.

A function that determines the trunk-axis offset on the canvas where each branch should align to if they become focal, given the trunk-axis length of the canvas as reference. Should return a number of pixels counting from the trunk-axis origin of the canvas. If the number is greater than the canvas length, will use the canvas length. Defaults to 1/2 of the canvas length.

A function that determines the branch-axis offset on the canvas where each node should align to if they become active, given the branch-axis length of the canvas as reference. Should return a number of pixels counting from the branch-axis origin of the canvas. If the number is greater than the canvas length, will use the canvas length. Defaults to 1/2 of the canvas length.

A function that determines the trunk-axis offset on each branch that should align to the focal offset if they become focal, given their length on the trunk axis. Should return a number of pixels counting from the trunk-axis origin of the branch. If the number exceeds the branch length, will use the branch length. Defaults to 1/2 of the branch length.

A function that determines the branch-axis offset on each node that should align to the focal position if they become active, given their length on the branch axis. Should return a number of pixels counting from the branch-axis origin of the node. If the number exceeds the node length, will use the node length. Defaults to 1/2 of the node length.

Whether to apply FLIP animations when inserting, deleting or reordering nodes. If true, you must also specify CSS transition of the transform property for nodes via the nd-node-move class. Defaults to false.

If set to a boolean, will override the global showChildIndicators option for this specific node. Defaults to null.

If set to a function, will override the global focalOffsetTrunk option for this specific node's child branch. Defaults to null.

If set to a function, will override the global focalOffsetBranch option for this specific node. Defaults to null.

If set to a function, will override the global anchorOffsetTrunk option for this specific node's child branch. Defaults to null.

If set to a function, will override the global anchorOffsetBranch option for this specific node. Defaults to null.

If set to a boolean, will override the global useFlipAnimation option for this specific node's child branch. Defaults to null.

Vue component to be rendered using Vue's <component> tag. Can be name or component reference.

Name-value pairs of props to pass to this component.

Name-value pairs of event listeners to pass to this component.

CSS applied to the nd-node element.

CSS applied to the nd-content-box element.

CSS applied to the nd-child-indicator element.

CSS applied to the nd-branch element.

CSS applied to the nd-branch-content-box element.

CSS applied to the nd-branch-slider element.

Canvas

Trunk

Branch

Node