All
API
Docs
Demos
Blogs
Webinars

Introduction

Layouts in KeyLines let you display your data in a clear and effective format. There are several different layouts, each with multiple customisation options.

// pass the layout name as the first argument of the chart.layout function
chart.layout('layout name');

As new nodes are initially given default coordinates, it's almost always a good idea to call chart.layout() after you have loaded in data to avoid nodes being on top of one another.

If you're adding new data and want to keep the approximate position of existing nodes, consider using chart.expand().

See our Layouts demo to compare the layouts and find the best one for your application. See also the layout options API which you can use to customise your layouts.

Organic

The organic layout is our default layout that is used when you don't specify a layout while running chart.layout() or chart.expand().

Organic is a force-directed layout, which means that the layout places connected nodes closer together and organises them in a way that reduces link crossings in the chart as much as possible. It is clear, reliable and makes a good all-rounder for any type or size of data as it focuses on finding patterns and symmetries.

In addition, organic is especially useful for untangling complex networks as it spreads nodes and links apart.

Organic can be run as a short layout in adaptive mode which adjusts the current item positions to respond to layout changes while minimising the overall amount of movement.

See examples of organic in action in our Mafia Network demo.

an example of organic layout chart

Sequential

The sequential layout is useful for displaying data with a clear sequence of links between distinct levels of nodes.

It can automatically work out where to place nodes in the hierarchy in order to minimise link crossings and make efficient use of the available screen space.

Sequential can be run as a short layout in adaptive mode which adjusts the current item positions to respond to layout changes while minimising the overall amount of movement.

The sequential layout options let you customise position of nodes in the hierarchy and also in relation to each other within each level.

Explore sequential layout and its various options in the Display Hierarchies and Navigate Large Hierarchies demos.

an example of sequential layout chart

Structural

The structural layout functions in a similar manner to a force-directed layout, but nodes with the same neighbouring nodes are grouped together.

This makes it easier to see the general organisation of a network.

By giving you an overview of the clusters within a network, the structural layout allows you to see groupings and patterns without the need to focus on any one element.

The Database demos offer a good example of how you can use the structural layout.

an example of structural layout chart

Radial

The radial layout arranges nodes in concentric circles around the original subject in a radial tree.

Each 'generation' of node becomes a new ring surrounding the previous generations.

This layout is a great option for networks containing a large number of child nodes compared to the number of parents as it makes use of any available space.

As with sequential, radial can be customised using the top and level options.

Have a look at the Light Monochrome view in the Styling Charts demo to get a feel for the radial layout.

an example of radial layout chart

Lens

The lens layout pushes highly-connected nodes into the centre, and forces less connected nodes into the periphery.

The circular outline makes good use of the available space and generally creates networks that are denser than other layouts.

This results in an attractive 'lens' view which is particularly useful for large networks.

Lens is the default layout for arranging items inside open combos.

Our Combining Nodes demo is a great example of this layout.

an example of lens layout chart

Layout Options

Layout options can be used to fine-tune the appearance and behaviour of layouts. Options are set in the second argument of the layout API:

// brings the nodes closer together
chart.layout('layout name', { tightness: 10 });

Note that not all layout options apply to every layout.

Adaptive Behaviour

Adaptive behaviour is the layout's ability to respond to changes in the data while minimising unnecessary movement and preserving as much of the original layout as possible. Different layouts achieve the best adaptive behaviour using different options.

Use Case ExampleOrganicSequentialLensRadialStructural
Adaptive behaviour when adding data with expand()fix: 'adaptive'XXpacking: 'adaptive'packing: 'adaptive'
Adaptive behaviour when loading or changing data with layout()mode: 'adaptive'mode: 'adaptive'Xpacking: 'adaptive'packing: 'adaptive'
Consistent layout with unchanged componentsconsistent: trueXconsistent: trueXX
Fix existing nodes when adding data with expand()fix: 'all'XXXX
Fix existing nodes when loading or changing data with layout()fixed: []XXXX

consistent

The consistent option produces the same chart display for the same chart structure each time the layout is run. This can be useful for providing undo-redo support for a chart. Note that layouts will only be consistent with previous layouts that use the exact same data and options.

fix

The fix option specifies which nodes should be fixed in position when the layout is run during chart.expand().

fixed

The fixed option fixes chosen nodes during chart.layout(). Fixed nodes will keep their position relative to other fixed nodes in the component, although the component itself may move.

mode

By default, layouts arrange nodes based on a random initialisation, producing a new result every time you run a layout. Setting mode to 'adaptive' when running chart.layout() runs a short force-directed layout instead. This uses the current node positions as a starting point and adapts them in a minimal way to respond to changes in the data.

This mode is ideal for visualising data evolving with time with the show function and the time bar. See an example in the Credit Card Fraud demo.

packing

The packing option controls where components are placed relative to one another. This affects both the overall shape and the behaviour of your graph when adding additional data.

Sequential Layout Options

Sequential automatically places nodes according to the orientation of the layout, and the direction of arrows on links.

You can also customise the position of nodes in sequential using the level or top options:

  • Use the level option to specify the name of a property in a node's custom data object, d, whose value is used to set that node's level.
  • Use the top option to specify the id(s) of the node(s) at the top of the hierarchy.
  • If both are specified, level is used.
  • If neither are specified, levels are assigned automatically (inferred from the nodes' links).

As an example, with this data:

a gif showing automatic assignment of levels in sequential layoutan image showing automatic assignment of levels in sequential layout
{ id: 'node1', type: 'node',
  d: {
    levelProperty: 1 // this node will be in the first level
  }
}, { id: 'node2', type: 'node',
  d: {
    levelProperty: 2 // this node will be in the level below
} }

we can run:

chart.layout('sequential', {level: 'levelProperty'})
// puts node1 above node2 in the hierarchy

By default, sequential aligns nodes on the same level across all components (i.e. packing set to 'aligned'). In cases where relationship between components doesn't need to be displayed, components in sequential can be packed like any other layout.

Within individual node levels, you can further customise sequential using the orderBy and stacking options.

chart.layout(
  'sequential', {
    orderBy: { property: 'orderByProperty', sortBy: 'ascending' },
    packing: 'rectangle',
    stacking: { arrange: 'grid' },
})

The string specified in the property option gives the name of a property in a node's custom data object, d. Sequential uses the value of that property to order nodes relative to each other within the same level.

The stacking option controls positions of nodes that share the same neighbours, level and property value in orderBy (if specified). The arrange property lets you stack such nodes into grids.

The stacking option is useful for visualising very wide family trees as it makes better use of space and helps to display wide networks at more readable zoom levels. See the benefits in our Navigate Large Hierarchies demo.

a sequential layout chart with grid stacking

Arrangements - Layouts inside Combos

When placing nodes inside open combos, KeyLines uses arrangements instead of layouts to get the best use of space.

You can set the arrangement in the name option and specify other options such as the arrangement tightness: 

chart.combo().arrange('combo_name', { name: 'arrangement name', tightness: 4 });

To test out our arrangements, see our Combo Options demo.

Concentric

an example of concentric arrangement inside a combo

Lays out nodes in a series of rings, with larger nodes in the centre.

Provides the best use of space within circular combos when the links within the combo are not important.

Lens

an example of lens arrangement inside a combo

Pushes highly-connected nodes into the centre, and forces less connected nodes into the periphery.

Default for cicular combos as it gives a space-efficient view of networks inside combos.

Grid

an example of grid arrangement inside a combo

Lays out nodes in a grid from left to right and from the top down, in the order set by the node ids. You can control the row or column dimension with the gridShape option.

Default for rectangular combos as it makes the best use of space when the links within combos are not important.

Sequential

an example of sequential arrangement inside a combo

Lays out a hierarchy of nodes according to which levels they belong to, and in a way that minimises empty space and link crossings. You can further customise this arrangement in the arrange object.

Provides useful insight into complex hierarchical data.