Dynamic Head Node

When creating a project in Eko studio, the first node that’s pushed to the playlist (i.e., the head node) is the node that’s connected to Loading Screen. In the picture below it is the Beginning node:

Override headnodeid

The head node can be overridden via headnodeid query param. This is an easy way to use a different head node. The main drawback of this approach is that the head node configuration becomes a part of the URL and is not made dynamically in code. Having different head nodes means having different URLs. For example:

# default head node as defined in Eko Stuido
# start the project with node_alt_head1 
# start the project with node_alt_head2 

headnodeid is useful for performing split testing of different variations of the project, or for embedding a specific variation in a web page.

Head Hook

Adding a head property or function to your intro.js allows you to override the head node using code.
The head can be one of the following:

  1. Node ID string.
  2. An array of node IDs strings (node IDs).
  3. A function that receives a player instance as an argument and returns a string (node ID), a node object or an array of strings or node objects. If the function returns a falsy value (or a promise that resolves with a falsy value), the default head that was defined in Eko Studio will be pushed to the beginning of the playlist.

If your head function returns a promise, the project won’t start playing until the promise is resolved. Make sure it doesn’t take too long to resolve, so the user’s experience won’t be affected. See the async-hooks section in the JavaScript Entrypoints guide for more details.

Let’s assume you want a different head node according to the current season. You have a function called getCurrentSeason which fetches the current season value from a web service. Here is a snippet of an intro.js that shows how this can be implemented:

// Function that returns a promise which resolves with the current season
function getCurrentSeason() {...}

export default {
    head: function(player) {

        // Define an object that maps seasons to node IDs
        const seasonMap = {
            summer: 'node_summer',
            winter: 'node_winter',
            fall: 'node_fall',
            spring: 'node_spring'

        // Get current season value
        return getCurrentSeason()
            .then(season => {
                // Return node ID according to the season
                if (seasonMap[season]) {
                    return seasonMap[season];

                // Return false if we got unknown season
                // this means that we won't override the head
                return false;
            // If an error occurred we also won't override the head
            .catch(() => {
                 return false;

    // All potential head node IDs must be included in the introNodes array
    introNodes: [

The headnodeid query param takes precedence over Eko Studio’s head node and intro.js exported head.

Rate this page: X
Tell us more!