Developers

This is the technical reference for Kinetra 1.3.0: how a request becomes the animated site, every PHP hook, the data the frontend receives, the browser events, and how to build on it safely. It assumes you know WordPress themes and plugins. Site owners don’t need any of it; start with After installation instead.

How Kinetra works

Kinetra is a normal PHP theme that ships a prebuilt Next.js and React app. There is no Node.js on the server. Every request goes through WordPress as usual:

1. WordPress runs its query and loads index.php, the theme’s only page template.
2. kinetra_build_payload() turns the current query into a JSON payload (the page), and kinetra_site_data() builds the site data (menus, settings, labels).
3. The theme prints plain, crawlable HTML of the page in #kinetra-ssr for search engines and no-JavaScript visitors, followed by both JSON objects in <script id="__KINETRA__" type="application/json">.
4. The app starts, reads that JSON, renders the animated page in #kinetra-root and adds the class nx-ready to <html>.
5. When a visitor clicks an internal link, the app fetches the same URL with ?_kinetra=1, which returns just the payload as JSON, then animates to the new page and updates the title, meta tags and history.

Because the page is always built by WordPress, every plugin that changes the query, content or SEO data keeps working. Plugins that need a real page load can ask for one (see kinetra_needs_full_load).

Files

Constants

Where to put your code

• A small plugin or a child theme’s functions.php for PHP. Both load before the parent theme, so filters are in place in time.
• Kinetra → Custom Code for tracking tags and CSS. Snippets go in wp_head, wp_body_open or wp_footer with a priority and a condition (every page, front page only, logged-in users and so on).
• Customize → Additional CSS for style tweaks.

A child theme only needs a style.css:

/*
Theme Name: Kinetra Child
Template: kinetra
*/

Don’t add page.php, single.php, archive.php or similar to a child theme. WordPress would use them instead of Kinetra’s index.php, and those pages would lose the animated site. comments.php can be overridden; its output is shown inside the app.

Settings

Every Customizer option is defined once in kinetra_option_schema(). The schema registers the Customizer control, sanitises the value, gives it a default, and (unless public is false) sends it to the frontend as site.settings.

Values are stored as theme mods named kinetra_{key}, so get_theme_mod( 'kinetra_accent' ) gives the saved value only. Use kinetra_opt() to get the value with defaults.

A schema entry has section, type, label and default, and optionally description, choices (select), min/max (range, number), public and core. Types are select, toggle, color, range, number, text, textarea, url, email, code and palette.

Sections: kinetra_style, kinetra_colors, kinetra_typography, kinetra_layout, kinetra_header, kinetra_motion, kinetra_portfolio, kinetra_blog, kinetra_shop, kinetra_footer, kinetra_social, kinetra_contact, kinetra_seo, kinetra_advanced.

Add your own option

add_filter( 'kinetra_option_schema', function ( $schema ) {
	$schema['promo_text'] = array(
		'section' => 'kinetra_header',
		'type'    => 'text',
		'label'   => 'Promo text',
		'default' => '',
	);
	return $schema;
} );

// Anywhere later:
$text = kinetra_opt( 'promo_text' );

The schema is built once per request and then cached. Add this filter when your file loads, not inside a later hook such as init.

Design tokens (CSS variables)

The settings are printed as CSS custom properties on :root. Use them in your own CSS so it follows the Customizer and the light/dark switch:

The active colour scheme is on <html data-scheme="light|dark">. <body> has the classes kinetra and kinetra-style-{preset}.

.my-badge {
	background: var(--nx-accent);
	color: var(--nx-accent-text);
	border-radius: var(--nx-btn-radius);
	font-family: var(--nx-font-heading);
}
:root[data-scheme="dark"] .my-badge { box-shadow: 0 0 0 1px var(--nx-border); }

Presets, palettes and fonts

// Change a preset's defaults.
add_filter( 'kinetra_presets', function ( $presets ) {
	$presets['launch']['defaults']['accent'] = '#0EA5E9';
	return $presets;
} );

// Add a colour combination to Customize → Colors.
add_filter( 'kinetra_palettes', function ( $palettes ) {
	$palettes['brand'] = array(
		'label'  => 'Our brand',
		'colors' => array( 'accent' => '#0B5FFF', 'accent_text' => '#FFFFFF', 'light_highlight' => '#0B5FFF', 'dark_highlight' => '#8DB2FF' ),
	);
	return $palettes;
} );

// Add a Google Font to the font choices.
add_filter( 'kinetra_fonts', function ( $fonts ) {
	$fonts['Lexend'] = array( 'spec' => 'wght@400;500;600;700', 'fallback' => 'sans-serif' );
	return $fonts;
} );

A new preset key works too. It sets option defaults and uses the Kinetic section layouts; the six built-in layouts are part of the frontend app.

Content and sections

A page is turned into a list of sections. Each kinetra/* block becomes { type: "block", name, data }. Everything between them (paragraphs, images, embeds, shortcodes, other plugins’ blocks) is rendered by WordPress and grouped into { type: "html", html }. Classic-editor content becomes one HTML section.

Each section is defined once in kinetra_block_schemas() in Kinetra Core. The schema registers the block (kinetra/{name}), builds its editor form, registers the Elementor widget (kinetra-{name}), renders the crawlable HTML, and shapes the data the app gets.

'hero' => array(
	'title'       => 'Hero',
	'description' => 'Big animated headline with intro text and buttons.',
	'icon'        => 'superhero', // Dashicon name
	'fields'      => array(
		'eyebrow' => array( 'type' => 'text', 'label' => 'Small label', 'default' => '' ),
		'image'   => array( 'type' => 'image', 'label' => 'Side image', 'default' => 0 ),
		// …
	),
),

Field types: text, textarea, url, color, number (min, max), toggle, select (choices), image (attachment ID; the app gets url, width, height, alt, srcset) and list (a repeater with its own fields).

Section names: hero, marquee, projects, feature, services, tabs, showreel, about, process, quote, clients, logos, testimonials, team, stats, features, pricing, faq, cta, newsletter, contact, products, categories, promo, banners, perks.

Change section defaults or fields

add_filter( 'kinetra_block_schemas', function ( $schemas ) {
	// New Hero blocks start with your own button text.
	$schemas['hero']['fields']['primary_label']['default'] = 'Book a call';

	// Give the Call to Action a field your own code can read.
	$schemas['cta']['fields']['campaign'] = array( 'type' => 'text', 'label' => 'Campaign ID', 'default' => '' );
	return $schemas;
} );

The built app only draws the 26 sections it knows, and only the fields each one was written for. A new field reaches the payload (and the kinetra_payload filter) straight away; to show it, or to add a completely new section, change the frontend source and rebuild. A new section name without a frontend component renders nothing on the animated site.

Replace a page’s sections

kinetra_pre_content_sections runs before the content is parsed. Return an array of sections to skip parsing, or null to continue.

add_filter( 'kinetra_pre_content_sections', function ( $sections, $post ) {
	if ( 'landing' !== $post->post_name ) {
		return $sections; // null: parse as usual
	}
	return array(
		array( 'type' => 'block', 'name' => 'hero', 'data' => kinetra_block_data( 'hero', array( 'title' => "Hello\nworld" ) ) ),
		array( 'type' => 'html', 'html' => '<p>Rendered by my plugin.</p>' ),
	);
}, 10, 2 );

Post types, fields and meta

Useful functions: kinetra_get_projects( array( 'count' => 4, 'category' => 'branding', 'featured' => true ) ), kinetra_project_card( $post ), kinetra_post_card( $post ), kinetra_image( $id, $size ), kinetra_menu( $location ).

The payload

The payload is what the app draws for one URL. Change it with kinetra_payload. It always has kind, seo (title, description, canonical, image, noindex), url and lang.

With Elementor, builder holds the page’s Elementor content and Theme Builder header and footer, plus layout (canvas or full).

add_filter( 'kinetra_payload', function ( $payload ) {
	if ( 'single' === $payload['kind'] && 'post' === $payload['postType'] ) {
		$payload['readingTime'] = max( 1, $payload['readingTime'] - 1 );
		$payload['sponsor']     = get_post_meta( $payload['id'], 'sponsor', true );
	}
	return $payload;
} );

To see the payload of any page, open it with ?_kinetra=1 added to the address. Use ?_kinetra=boot to get the site data as well.

Full page loads

Some content needs a real page load: its scripts only start on DOMContentLoaded, or it prints its own assets. Kinetra already does this for pages with Contact Form 7, WPForms, Gravity Forms, Fluent Forms, Ninja Forms, Formidable, Mailchimp for WP, Everest Forms and Forminator, and for WooCommerce cart, checkout and account pages. Add your own with kinetra_needs_full_load:

add_filter( 'kinetra_needs_full_load', function ( $needs, $post ) {
	return $needs || has_shortcode( $post->post_content, 'my_booking_widget' );
}, 10, 2 );

In your own HTML, add data-native to a link to open it with a normal page load. Links with a target other than _self, with download, to files, to wp-admin, wp-json, feeds and to other sites always load normally.

JavaScript in the browser

Page changes don’t reload the page, so scripts that set themselves up on page load run only once. Use these events to run your code again:

Kinetra also triggers jQuery’s post-load event on document.body (used by Jetpack and many lazy loaders) and starts Contact Form 7, WPForms and Gravity Forms in new content. The class nx-ready appears on <html> once the app has started.

// Run a widget library on new content.
document.addEventListener('kinetra:content', function (e) {
  e.detail.root.querySelectorAll('.my-slider').forEach(function (el) {
    MySlider.init(el);
  });
});

// Send a page view to a tool that doesn't track history changes.
window.addEventListener('kinetra:navigate', function (e) {
  if (window.plausible) plausible('pageview', { u: e.detail.url });
});

// Wait for the app before measuring layout.
function whenReady(fn) {
  var html = document.documentElement;
  if (html.classList.contains('nx-ready')) return fn();
  new MutationObserver(function (m, o) {
    if (html.classList.contains('nx-ready')) { o.disconnect(); fn(); }
  }).observe(html, { attributes: true, attributeFilter: ['class'] });
}

Google Analytics 4 (Kinetra’s own setting or Site Kit) needs nothing extra: the title is updated before the history change, and GA4 counts history changes as page views by default.

Snippets in Kinetra → Custom Code are printed on the first page load only. A snippet that must run on every page should listen for kinetra:navigate.

Hooks reference

Every filter and action Kinetra provides. Theme hooks run when the Kinetra theme is active; Kinetra Core hooks run when the plugin is active.

Design and settings

Pages and content

SEO

add_filter( 'kinetra_schema_graph', function ( $graph ) {
	$graph[] = array(
		'@type'     => 'LocalBusiness',
		'name'      => get_bloginfo( 'name' ),
		'telephone' => '+44 20 0000 0000',
	);
	return $graph;
} );

Forms and email

add_action( 'kinetra_newsletter_signup', function ( $email ) {
	wp_remote_post( 'https://api.example-mail.com/v1/subscribers', array(
		'headers' => array( 'Authorization' => 'Bearer ' . MY_MAIL_API_KEY ),
		'body'    => array( 'email' => $email ),
	) );
} );
add_filter( 'kinetra_store_subscribers', '__return_false' );

Speed, caching and scripts

add_action( 'kinetra_purge_caches', function () {
	if ( function_exists( 'my_cdn_purge_all' ) ) {
		my_cdn_purge_all();
	}
} );

Uploads

Demos, plugins and setup

Add your own demo

Agencies can ship their own starter site in the Setup Wizard. Register it, then return its package:

add_filter( 'kinetra_demos', function ( $demos ) {
	$demos['studio'] = array(
		'label'       => 'Our studio starter',
		'tagline'     => 'Agency · clean',
		'description' => 'Our standard client site.',
		'preview'     => plugins_url( 'preview.svg', __FILE__ ),
	);
	return $demos;
} );

add_filter( 'kinetra_demo_package', function ( $package, $id ) {
	if ( 'studio' !== $id ) {
		return $package;
	}
	return array(
		'id'       => 'studio',
		'site'     => array( 'name' => 'Studio', 'tagline' => 'Design and build' ),
		'settings' => array( 'style' => 'collective', 'accent' => '#FF5A1F' ),
		'pages'    => array(
			array(
				'title'   => 'Home',
				'slug'    => 'home',
				'role'    => 'front',
				'meta'    => array( 'hide_title' => '1' ),
				'content' => '<!-- wp:kinetra/hero {"title":"We make\\nthings move."} /-->',
			),
		),
		'projects' => array(),
		'posts'    => array(),
		'menus'    => array( 'primary' => array( array( 'title' => 'Home', 'page' => 'home' ) ) ),
	);
}, 10, 2 );

Page role can be front (set as the home page) or blog (set as the posts page). settings takes option keys from the schema. Look at kinetra/inc/demo/*.php for full examples with projects, posts, products and images.

REST API

Both POST endpoints have a hidden website field as a spam trap: if it is filled in, the request looks successful but nothing is sent.

Elementor

• Each section is an Elementor widget named kinetra-{section} in the Kinetra Sections category, built from the same schema as the block.
• Elementor pages, and Elementor Pro Theme Builder single, archive, 404, header and footer templates, are rendered by Elementor and placed inside the app.
• The Theme Builder header sits in .nx-builder-header and the footer in .nx-builder-footer. Kinetra adds kx-sticky, kx-scrolled and kx-hidden to the header from the Header & Menu settings, so style against those instead of using Elementor Pro’s sticky option.
• When Elementor Pro (or Pro Elements) is active, Kinetra creates “Kinetra Header” and “Kinetra Footer” templates from the Customizer settings and keeps them updated until you edit them in Elementor. They show on the site once their Display Conditions are set to Entire Site.
• One Elementor kit per preset (“Kinetra — Kinetic” and so on) mirrors the Customizer’s colours and fonts as Elementor globals.

WooCommerce

• Shop, category and product pages are drawn by the app by default. With Customize → Shop → WooCommerce classic templates, or for cart, checkout and account, WooCommerce renders the page and the app places it in its layout (#kinetra-native). All WooCommerce hooks and template overrides work on those pages.
• On animated product pages, the product data comes from kinetra_product_payload(). Change it in kinetra_payload under product.
• woocommerce_short_description and woocommerce_default_catalog_orderby are respected.
• Links with add-to-cart, remove_item, wc-ajax or customer-logout in the address always load normally.

Translation

• Text domains are kinetra (theme) and kinetra-core (plugin), with .pot files in each languages folder.
• Customizer text options are registered as WPML strings and Polylang strings in the Kinetra context.
• The frontend’s labels come from kinetra_i18n(), so they are translated with the theme.
• When a visitor switches language, the app does a full page load.

Changing the frontend

The Professional and Agency plans include kinetra-frontend-source.zip, the Next.js source (React 19, Framer Motion, Lenis). Work against a local WordPress site:

cd frontend
npm install
echo "NEXT_PUBLIC_WP_URL=http://your-local-wp.test" > .env.local
npm run dev

Allow the dev server in that site’s wp-config.php:

define( 'KINETRA_DEV_ORIGIN', 'http://localhost:3000' );

To add a section: add its schema with kinetra_block_schemas, write a component that takes { data }, add it to BLOCKS under the same name, then build. npm run build exports the app and copies it into kinetra/app/; Kinetra publishes the new build to uploads on the next visit.

A theme update replaces kinetra/app/ with the official build. If you ship a changed frontend, put it in a child theme’s own copy of the theme, or rebuild after every update, and keep your changes in version control.

Debugging checklist

• Kinetra → Dashboard → System status shows the app build, uploads folder, Kinetra Core and SEO system.
• Open the page with ?_kinetra=1 to see exactly what the app receives.
• View the page source: the plain HTML in #kinetra-ssr is what search engines read.
• If the page shows plain text for a few seconds and then the plain version, the app didn’t start. Check the browser console and optimizer plugins first.
• Turn off Custom Code with add_filter( 'kinetra_disable_custom_code', '__return_true' ); to rule it out.
• Clear caches after changing PHP filters; payloads are cached for 60 seconds for visitors.