Kinekt API

Kinekt now provides a comprehensive JavaScript API for external programmatic control of timelines. This API allows you to interact with Kinekt animations from your custom JavaScript code without modifying the core plugin functionality.

The API is available globally through the window.kinektAPI object after the DOM is loaded and Kinekt has initialized.

// Wait for Kinekt API to be ready
document.addEventListener('DOMContentLoaded', () => {
    // Small delay to ensure Kinekt is fully initialized
    setTimeout(() => {
        // API is now available at window.kinektAPI
        console.log('Kinekt API Version:', window.kinektAPI.getVersion());
    }, 100);
});

It is extremely useful if you plan to chain animations in order to play them in sequential order, to access timelines with the custom JS code, or even create a “connection” with Bricks builder Interactions.

Core Methods

🔶 Timeline Access

getTimeline(id)

Get a GSAP timeline by its name or ID (case-insensitive, supports multiple formats).

// All of these work:
const timeline1 = window.kinektAPI.getTimeline('Hero Fade In');     // Exact name
const timeline2 = window.kinektAPI.getTimeline('hero fade in');     // Lowercase
const timeline3 = window.kinektAPI.getTimeline('hero-fade-in');      // Dash format
// Returns the GSAP timeline object or null if not found

getTimelineByName(name)

Get a timeline by its Bricks Builder animation name (case-insensitive).

// If you named your animation "Hero Fade In" in Bricks Builder
const timeline = window.kinektAPI.getTimelineByName('Hero Fade In');
const timeline2 = window.kinektAPI.getTimelineByName('hero fade in'); // Also works

getTimelineById(convertedId)

Get a timeline by its converted ID format (name converted to lowercase with dashes).

// If you named your animation "Hero Fade In" in Bricks Builder
const timeline = window.kinektAPI.getTimelineById('hero-fade-in');

Note: This method provides backward compatibility and enhanced format conversion. The getTimeline() method now also supports multiple formats.

listAllTimelines()

Get all available timelines with their current states.

const allTimelines = window.kinektAPI.listAllTimelines();
// Returns: { 'Hero Fade In': { timeline, state, type }, 'Button Hover': {...} }

listTimelineIds()

Get an array of all available timeline names (as set in Bricks Builder).

const names = window.kinektAPI.listTimelineIds();
// Returns: ['Hero Fade In', 'Button Hover', 'Scroll Animation']

Note: This returns the actual names you set in Bricks Builder, not converted IDs. Use these names with getTimeline() or getTimelineByName().

---

🔶 Timeline Control

Basic Controls

// Play a timeline
window.kinektAPI.play('Hero Fade In');

// Pause a timeline
window.kinektAPI.pause('Hero Fade In');

// Reverse a timeline
window.kinektAPI.reverse('Hero Fade In');

// Restart a timeline (goes back to beginning and plays)
window.kinektAPI.restart('Hero Fade In');

Advanced Controls

// Jump to specific progress (0 to 1)
window.kinektAPI.progress('Hero Fade In', 0.5); // Jump to 50%

// Jump to specific time (in seconds)
window.kinektAPI.time('Hero Fade In', 2.5); // Jump to 2.5 seconds

// Change playback speed
window.kinektAPI.timeScale('Hero Fade In', 2); // Play at 2x speed
window.kinektAPI.timeScale('Hero Fade In', 0.5); // Play at half speed

---

🔶 State Inspection

getState(id)

Get the current state of a timeline.

const state = window.kinektAPI.getState('Hero Fade In');
console.log(state);

isActive(id)

Check if a timeline is currently active (playing).

if (window.kinektAPI.isActive('Hero Fade In')) {
    console.log('Timeline is playing');
}

getAllStates()

Get states for all timelines.

const allStates = window.kinektAPI.getAllStates();
// Returns object with all timeline states

---

🔶 Batch Operations

playAll(), pauseAll(), reverseAll()

Control all timelines at once.

// Play all timelines
window.kinektAPI.playAll();

// Pause all timelines
window.kinektAPI.pauseAll();

// Reverse all timelines
window.kinektAPI.reverseAll();

Event System

🔶 Listening to Events

The API provides an event system to react to timeline changes:

// Listen to timeline state changes
window.kinektAPI.on('timelineStateChanged', (data) => {
    console.log(`Timeline ${data.id} changed:`, data.currentState);
});

// Listen to timeline completion
window.kinektAPI.on('timelineCompleted', (data) => {
    console.log(`Timeline "${data.id}" completed!`);
});

// Listen to timeline start
window.kinektAPI.on('timelineStarted', (data) => {
    console.log(`Timeline "${data.id}" started!`);
});

// Listen to timeline control actions
window.kinektAPI.on('timelineControlled', (data) => {
    console.log(`Timeline "${data.id}" was ${data.action}`);
});

---

🔶 Available Events

• timelineStateChanged: Fired when any timeline state changes

  {
      id: 'Hero Fade In',
      previousState: {...},
      currentState: {...}
  }

• timelineStarted: Fired when a timeline starts playing
• timelineCompleted: Fired when a timeline reaches completion
• timelineReversed: Fired when a timeline completes in reverse
• timelineControlled: Fired when a timeline is controlled via API

---

🔶 Removing Event Listeners

const myCallback = (data) => console.log(data);

// Add listener
window.kinektAPI.on('timelineCompleted', myCallback);

// Remove listener
window.kinektAPI.off('timelineCompleted', myCallback);

Utility Methods

waitForTimeline(id)

Wait for a timeline to be available (useful for dynamically loaded content).

// Returns a Promise that resolves when timeline is found
window.kinektAPI.waitForTimeline('dynamic-animation')
    .then(timeline => {
        timeline.play();
    })
    .catch(error => {
        console.error('Timeline not found:', error);
    });

getVersion()

Get the API version.

console.log('Kinekt API Version:', window.kinektAPI.getVersion());

debug()

Get debug information about the API and available timelines.

// Log debug info to console
window.kinektAPI.debug();

// Or get debug data as object
const debugInfo = window.kinektAPI.debug();
console.log('Available timelines:', debugInfo.timelines);

---

Complete Examples

🔶 Example 1: Basic Timeline Control

document.addEventListener('DOMContentLoaded', () => {
    setTimeout(() => {

        // Get timeline by name (use the exact name from Bricks Builder)
        const heroTimeline = window.kinektAPI.getTimelineByName('Hero Animation');

        if (heroTimeline) {
            // Direct GSAP control
            heroTimeline.play();

            // Or use API methods with the same name
            window.kinektAPI.play('Hero Animation');
        }

        // Control with custom buttons
        document.getElementById('play-btn').addEventListener('click', () => {
            window.kinektAPI.play('Hero Animation');
        });

        document.getElementById('pause-btn').addEventListener('click', () => {
            window.kinektAPI.pause('Hero Animation');
        });

        document.getElementById('reverse-btn').addEventListener('click', () => {
            window.kinektAPI.reverse('Hero Animation');
        });

    }, 1000);
});

---

🔶 Example 2: Progress Control with Slider

document.addEventListener('DOMContentLoaded', () => {
    setTimeout(() => {

        const progressSlider = document.getElementById('progress-slider');
        const progressValue = document.getElementById('progress-value');

        // Update slider when timeline progresses
        window.kinektAPI.on('timelineStateChanged', (data) => {
            if (data.id === 'Hero Animation') {
                progressSlider.value = data.currentState.progress * 100;
                progressValue.textContent = Math.round(data.currentState.progress * 100) + '%';
            }
        });

        // Control timeline with slider
        progressSlider.addEventListener('input', (e) => {
            const progress = e.target.value / 100;
            window.kinektAPI.progress('Hero Animation', progress);
        });

    }, 1000);
});

---

🔶 Example 3: Sequential Animation Control

document.addEventListener('DOMContentLoaded', () => {
    setTimeout(() => {

        // Play animations in sequence (use actual Bricks Builder names)
        const sequence = ['Intro Fade', 'Hero Slide', 'Content Reveal'];

        let currentIndex = 0;

        const playNext = () => {
            if (currentIndex < sequence.length) {
                const timelineId = sequence[currentIndex];

                // Listen for completion of current animation
                const onComplete = (data) => {
                    if (data.id === timelineId) {
                        window.kinektAPI.off('timelineCompleted', onComplete);
                        currentIndex++;
                        playNext();
                    }
                };

                window.kinektAPI.on('timelineCompleted', onComplete);
                window.kinektAPI.play(timelineId);
            }
        };

        // Start sequence
        document.getElementById('start-sequence').addEventListener('click', playNext);

    }, 1000);
});

---

🔶 Example 4: State Monitoring Dashboard

document.addEventListener('DOMContentLoaded', () => {
    setTimeout(() => {

        // Create a simple dashboard
        const dashboard = document.createElement('div');
        dashboard.id = 'kinekt-dashboard';
        dashboard.style.cssText = `
            position: fixed;
            top: 10px;
            right: 10px;
            background: rgba(0,0,0,0.8);
            color: white;
            padding: 10px;
            border-radius: 5px;
            font-family: monospace;
            font-size: 12px;
            z-index: 9999;
        `;
        document.body.appendChild(dashboard);

        // Update dashboard on state changes
        window.kinektAPI.on('timelineStateChanged', (data) => {
            updateDashboard();
        });

        function updateDashboard() {
            const allStates = window.kinektAPI.getAllStates();
            const timelineIds = window.kinektAPI.listTimelineIds();

            dashboard.innerHTML = '<strong>Kinekt Timelines:</strong><br>';

            timelineIds.forEach(id => {
                const state = allStates[id];
                const status = state.isActive ? 'play' : 'pause';
                const progress = Math.round(state.progress * 100);

                dashboard.innerHTML += `${status} ${id}: ${progress}%<br>`;
            });
        }

        // Initial update
        updateDashboard();

    }, 1000);
});

Error Handling

The API includes built-in error handling and logging:

// The API methods return false on failure and log warnings
const success = window.kinektAPI.play('Non-existent Timeline');
if (!success) {
    console.log('Failed to play timeline - check console for details');
}

// Use try-catch for async operations
try {
    const timeline = await window.kinektAPI.waitForTimeline('Dynamic Timeline');
    timeline.play();
} catch (error) {
    console.error('Timeline not found:', error.message);
}