Download at Github


Turn html lists into stunning orbital navigation

What is Orbitlist.js?

Orbitlist.js is a jQuery plugin that turns unordered ul lists in an html document into a visual display of orbits and satellites.

Just add class="orbit" to any ul element you like and Orbitlist.js does all the mechanics and provides several css classes for styling.

More info on how to use it and several possibilities to customize your orbits below!

Including Orbitlist.js

There are three files that must be included in your html header:

    <link rel="stylesheet" type="text/css" href="orbitlist.css" media="all" />
    <script src=""></script>
    <script src="orbitlist.js"></script>

orbitlist.js will execute after the page is loaded and transform every unordered list with class="orbit" into what we call an orbitlist.

Orbitlist.js also uses a little piece of css that will only effect the site after orbitlist.js is run, so include this file, too.

Because Orbitlist.js is a jQuery plugin you also need to include jQuery. In the example above jQuery 2.1.4 is used, but Orbitlist.js should be compatible with all newer versions of jQuery as well. Using the most recent version is always a good idea.

Creating an Orbitlist

All you need is an unordered list somewhere in the html document:

<div class="container">
    <ul class="orbit">
        <li>Item 1</li>
        <li>Item 2</li>
        <li>Item 3</li>
        <li>Item 4</li>
        <li>Item 5</li>

There are two important things in this code:

  1. The class="orbit" is the only addition in the code that's absolutely necessary. This class triggers Orbitlist.js to transform the list - without this class the list stays just a standard list (which very often is exactly what it should be).
  2. The surrounding div isn't actually part of the orbitlist but still it's of great importance: Orbitlist.js will take the dimensions of the orbitlist's parent element when calculating the positions of the list elements, which we call satellites. So this element needs to have a certain width and height, for example set via class "container", but every other way is possible as well.

Well, the result on the right is a bit underwhelming, isn't it? Let's try to style it up a little bit!

The orbitlistJS css class

Every orbitlist will be given the class orbitlistJS during transformation, so it will have both the classes orbit and orbitlistJS afterwards. You can use the class orbitlistJS for styling your orbitlist, so let's make some visual enhancements:

.orbitlistJS li { 
    width: 60px;
    height: 60px;
    border-radius: 60px;
    border: 2px solid #000;
    background: #fff;
    text-align: center;
    line-height: 60px;

.orbitlistJS li:hover { background: #24d; }

Already looking much better!

Remember: this style will not apply if Orbitlist.js fails, particularly if javascript is turned of. Use the css class "orbit" for styling the standard/fallback and "orbitlistJS" for styling the orbitlist.

Complex orbits

You can nest a new unordered list into an orbitlist for getting a new layer of satellites. We call these layers orbits. These satellites will be intially invisible and will be shown only after the parent satellite is clicked.

Let's expand Item 2 from the orbitlist above:

    Item 2

The text Item 2 is still shown in the correspondings satellite but the ul block resides in a hidden second orbit. Just click Item 2 to see it!

Orbitlists will only show elements of orbits connected with satellites clicked by the user. If there would be another list within Item 1, it would not be shown be cicking Item 2.

There must not be another class="orbit" in the nested list - the whole thing is declared an orbitlist already.

Markup Classes

We already met the orbitlistJS class yet, but Orbitlist.js also provides you with a number of classes for the satellite li elements:

Active satellite: orbitlistJS-active

If you click at a satellite, this satellite becomes active and therefore its li element gains the class orbitlistJS-active. There is only one element at a time having this class, it's removed after another satellite becomes active or the active satellite gets clicked again. There is no active satellite before any user action occured.

Active trace: orbitlistJS-trace

Together the active satellite and al its ancestor satellites - that's one satellite per lower orbit - form the active trace. This means the active element is both active and trace.

Let's illustrate this with a little more styling:

.orbitlistJS .orbitlistJS-trace { background: #1ca; }
.orbitlistJS .orbitlistJS-active { background: #2F4; }

Orbit Classes

You can also style each orbit of an orbitlist individually. Each satellite gets an orbit-specific class: li elements of the general orbitlist get the class orbitlistJS-orbit-1, all li elements of first-level nested lists the class orbitlistJS-orbit-2 and so on.

Let's style the two orbits of our example differently:

.orbitlistJS .orbitlistJS-orbit-1 {
    border: 2px solid #000;

.orbitlistJS .orbitlistJS-orbit-2 {
    border: 2px dotted #33f;

There are three more classes planned but not yet implemented: one class for all satellites of orbits lower than the active satellite's orbit, one class for all satellites of the active satellite's orbit, and one class for the active satellite's child orbit. Check back some time for new releases!

Customization via data attributes

For determining the radiuses of the different orbits Orbitlist.js divides the distance between center and nearest point of the surrounding container into equal parts, one more than visible orbits. This means if there are two orbits visible, the distance is divided into 3 parts. The lower orbit gets a radius of 1/3 of the total distance and the higher orbit a radius of 2/3. However this is not always the best solution. You can change some of Orbitlist.js's parameters via html data attributes in the surrounding ul (which you give class "orbit" to):

<ul class="orbit"

In the example above we've displayed the default values for each parameter, setting these values wouldn't change anything at all. data-orbitlistjs-inner and data-orbitlistjs-outer set the minimal and maximal radius in relation to total distance. The space between these two is split equally as described above. For example a data-orbitlistjs-inner="0.3" would set a minimal radius of 0.3. This would prevent the satellites from covering the center of the orbitlist.

The parameter data-orbitlistjs-inner effects how Orbitlist.js treats space beyond the lowest and highest possible orbit other than between orbits. A value of 0.5 would cause the outer spaces to be half as wide as the inner spaces. Displaying two shells, the inner would be at 0.25 and the outer at 0.75 of the total distance. This is useful to pull the different orbits farther apart and make better use of small space.

Multiple orbits and more complex orbits

I guess by now you already realized you can have multiple orbits at the same page that are handled completely separately by Orbitlist.js. There's now limitation to this except space on your site and RAM. Mainly space.

There's also no limit in terms of how deep you can nest your orbitlists. As long as you find enough space to display them properly it's all fine. See if you can find the deepest spot in the example on the right!

Yeah, the overlapping doesn't look good. In the end this a gigantic orbitlist.