Search by

ideasonpurpose / wp-theme-addons

joemaller

WordPress Block Editor add-ons — JavaScript blocks, utilities, and PHP components

Package info

github.com/ideasonpurpose/wp-theme-addons

Language:JavaScript

pkg:composer/ideasonpurpose/wp-theme-addons

Statistics

Installs: 30

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 1

v0.5.1 2026-11-19 21:51 UTC

This package is auto-updated.

Last update: 2026-11-19 21:54:08 UTC


README

Version 0.5.1

NPM Version Packagist

This repository contains JavaScript and PHP add-ons for the WordPress Block Editor and Hybrid themes. The project is used in production, but is under active development and implementations are likely to change.

What's in here

Block Variations

Linked Group Block

A variation on the Group block which adds standard Link controls. The link implementation uses ideas from Accessible cards and Inclusive Components: Cards.

new LinkedGroup() wraps the core/group render callback and, when the variation has a URL, appends an empty overlay link inside the group. The stretch-link rules live in editor/Block/Variation/Group/LinkedGroup/linked-group.css. The editor script imports that file. PHP reads the same file and inlines it on the iop-linked-group handle from wp_enqueue_scripts, so the rules print in the head. No theme copy is required.

Related Posts Query

A variation on the Query Loop block which replaces the query with ranked related posts. Ranking lives in lib/RelatedPosts (IdeasOnPurpose\WP\RelatedPosts) — weighted shared taxonomies, post type, and recency, with optional REST at GET /wp-json/ideasonpurpose/v1/related_posts/{id} (see PHP usage to enable it).

Carousel

Three core/group variations — Carousel, Viewport, and Container — plus a front-end module. Any direct child of the container is a slide (cover, group, a pattern, or the items of a query loop). The editor shows the slides for editing and does not autoplay. The front end uses Embla Carousel 9.

Namespaces and classes:

Piece Block Namespace Class
Carousel core/group ideasonpurpose/carousel iop-carousel
Viewport core/group ideasonpurpose/carousel-viewport iop-carousel__viewport
Container core/group ideasonpurpose/carousel-container iop-carousel__container
Slide any direct child — iop-carousel__slide is added in the browser if missing

Viewport and Container are hidden from the inserter. Insert Carousel; it starts with a viewport, a container, and two group slides. Replace those slides with whatever the site needs. For a query loop, put the loop inside the viewport and add iop-carousel__container to the post template. Each post item is then a slide.

Settings live on the Carousel variation and are copied to data attributes when PHP renders the block. The saved group markup is unchanged. Omitted attributes use the defaults below.

Block attribute Data attribute Default
carouselAutoplay data-autoplay true
carouselDuration data-duration 6 (seconds)
carouselArrows data-arrows true
carouselDots data-dots true
carouselPause data-pause false
carouselLoop data-loop true
carouselRandom data-random 0 (keep every slide)

carouselRandom greater than 0 keeps that many slides, chosen in the browser on each visit, and removes the rest before Embla starts. That still varies when the HTML is served from a page cache.

A slide can set its own slideDuration (seconds) in the inspector. It is saved as data-slide-duration on that block and overrides carouselDuration for that slide only.

Arrow clicks and dot clicks both restart the autoplay timer. carouselPause adds a pause button that stops and resumes it. The button is off by default; an autoplaying carousel needs it to meet WCAG 2.2.2. It sits on its own, outside the pagination row. Autoplay does not start when prefers-reduced-motion: reduce is set, while the pointer is over the carousel, or while the carousel is off screen. Arrow keys move only the carousel that contains the focus, and they leave text fields alone.

Look is custom properties on .iop-carousel. Override these in the theme; the structural selectors can stay alone.

Property Default Use
--carousel-max-width none Viewport max width
--carousel-arrow-size 2.75rem Previous / next hit target
--carousel-arrow-icon-size 1.25rem Icon inside the arrow
--carousel-arrow-offset 0.75rem Inset from the sides
--carousel-arrow-color currentColor Icon color
--carousel-arrow-bg translucent Canvas Arrow and pause fill
--carousel-arrow-radius 999px Arrow and pause radius
--carousel-arrow-shadow none Arrow and pause shadow
--carousel-arrow-prev chevron mask-image for the previous icon
--carousel-arrow-next chevron mask-image for the next icon
--carousel-pause-icon pause bars Pause icon
--carousel-play-icon triangle Play icon
--carousel-pause-size 2.25rem Pause button
--carousel-pause-inset auto 1rem 1rem auto Pause position (inset shorthand)
--carousel-dot-width 0.625rem Pagination mark
--carousel-dot-height 0.625rem Pagination mark
--carousel-dot-radius 999px 0 makes bars
--carousel-dot-gap 0.5rem Space between marks
--carousel-dot-color translucent currentColor Inactive mark
--carousel-dot-active-color currentColor Active mark and hover
--carousel-controls-offset 1rem Distance from the bottom
--carousel-controls-justify center flex-start for left aligned
--carousel-controls-padding 1rem Inline padding of the control row

Embla's class-names plugin adds is-snapped and is-in-view on slides. Use those for motion that should wait until a slide is current. The package does not ship a slide-content animation.

Bars instead of dots, for example:

.iop-carousel {
  --carousel-dot-width: 1.5rem;
  --carousel-dot-height: 3px;
  --carousel-dot-radius: 0;
  --carousel-dot-color: #fff;
  --carousel-dot-active-color: var(--wp--preset--color--accent);
  --carousel-controls-justify: flex-start;
  --carousel-arrow-prev: var(--i-arrow-prev);
  --carousel-arrow-next: var(--i-arrow-next);
}

An example slide pattern a theme can register. The carousel structure comes from the variation, so the pattern is only the slide:

<?php
/**
 * Title: Carousel slide
 * Slug: theme/carousel-slide
 * Inserter: true
 */
?>
<!-- wp:group {"className":"iop-carousel__slide"} -->
<div class="wp-block-group iop-carousel__slide">
  <!-- wp:heading {"level":2} -->
  <h2 class="wp-block-heading">Slide title</h2>
  <!-- /wp:heading -->
  <!-- wp:paragraph -->
  <p>Slide text.</p>
  <!-- /wp:paragraph -->
</div>
<!-- /wp:group -->

A carousel inserted from the variation is a section with no alignment and no color. Set those on the block, or in the theme pattern that wraps it.

Block Extensions

Button Icons

This extension adds an icon-picker to the core/button block. Markup is unchanged, icons are specified by adding classes. Classes are added in the Block Editor as well as the front end, so authors can work with a true representation of the final button.

import { initButtonIconPicker } from "@ideasonpurpose/wp-theme-addons";

initButtonIconPicker(
  [
    { label: "Arrow Right", value: "arrow-right" },
    { label: "Mail", value: "mail" },
    { label: "Download", value: "download" },
  ],
  "arrow-right", // optional default icon, defaults to ""
);

Icons are displayed using CSS in the theme. Each icon maps to a mask variable the theme defines:

.wp-block-button.iop-button-icon.icon-arrow-right .wp-block-button__link::before {
  mask-image: var(--i-arrow-right);
}

CSS Local Props

Injects block color attributes as CSS custom properties (--local-text-color, --local-bg-color, --local-border-color) so theme styles can use them.

This feature includes a pair of front-end and block editor files:

File Runtime Role
CssLocalProps/CssLocalProps.php PHP (frontend + editor bootstrap) On render_block, writes the local props onto the outer wrapper tag. On enqueue_block_editor_assets, localizes the allowed-block list to window.iopLocalProps.
CssLocalProps/css-local-props.js Block editor Higher-order component on editor.BlockListBlock that injects the same vars into wrapperProps.style for live editor preview.

Named colors from theme.json are converted to var(--wp--preset--color--*); custom hex/rgb values pass through as-is.

By default only core/button is targeted. Change the list from PHP:

add_filter('iop/add_css_local_props_allowed_blocks', fn() => ['core/button', 'core/group']);

Both sides must stay in sync: enable PHP for frontend output and call initCssLocalProps() in the editor bundle so the canvas matches the saved markup.

The PHP block list is localized to the script handle {stylesheet}-editor (from get_stylesheet()). If the theme's editor script uses a different handle, or is enqueued after enqueue_block_editor_assets priority 10, the editor falls back to core/button. Pass the list to initCssLocalProps(['core/button', 'core/group']) directly in that case.

Utilities

A few utility hooks are exported. usePublicPostTypes and usePublicTaxonomies are direct lifts from the WordPress Gutenberg source code. These functions are useful for pre-populating a WordPress data-store with all PostType and Taxonomy data for use in interfaces or block rendering.

Installation

Prerequisites

  • SSH access to GitHub configured (your SSH key must be added to your GitHub account)
  • You or the consuming project must have access to this private repository

npm

npm install @ideasonpurpose/wp-theme-addons

Or in package.json:

{
  "dependencies": {
    "@ideasonpurpose/wp-theme-addons": "^0.5.1"
  }
}

Composer

Add the VCS repository and require the package in your project's composer.json:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "git@github.com:ideasonpurpose/wp-theme-addons.git"
        }
    ],
    "require": {
        "ideasonpurpose/wp-theme-addons": "dev-main"
    }
}

Usage

JavaScript

Import into editor.js. Minimal required styles are bundled with the JS:

// @link https://github.com/ideasonpurpose/wp-theme-addons
import {
  initButtonIconPicker,
  initCarouselBlock,
  initCssLocalProps,
  initLinkedGroupBlock,
  initRelatedPostsQueryBlock,
} from "@ideasonpurpose/wp-theme-addons";

initLinkedGroupBlock();
initRelatedPostsQueryBlock();
initCarouselBlock();
initCssLocalProps();
initButtonIconPicker([...]);

Call initCarouselBlock() while the editor script evaluates, same as the other inits. The import pulls carousel.css into the editor bundle. Autoplay does not run in the editor.

Front end, in main.js. This entry is separate so the editor bundle does not load Embla:

import { initCarousels } from "@ideasonpurpose/wp-theme-addons/carousel";

initCarousels();

Embla and its accessibility, autoplay, and class-names plugins are dependencies of this package, pinned to the 9.0.0 release candidate (9.0.0-rc04) because the carousel uses the v9 API. initCarousels() waits for DOMContentLoaded if the document is still loading.

The package ships untranspiled source: .js files contain JSX and import .scss files. The theme's build must transpile JSX and compile Sass for this package inside node_modules. @wordpress/* packages are expected to be provided as externals by the theme's build (for example @wordpress/scripts).

PHP

use IdeasOnPurpose\WP\RelatedPosts;
use IdeasOnPurpose\WP\Theme\Addons\Block\Variation\Group\Carousel\Carousel;
use IdeasOnPurpose\WP\Theme\Addons\Block\Variation\Group\LinkedGroup\LinkedGroup;
use IdeasOnPurpose\WP\Theme\Addons\Block\Variation\Query\RelatedPostsQuery\RelatedPostsQuery;
use IdeasOnPurpose\WP\Theme\Addons\CssLocalProps\CssLocalProps;

new LinkedGroup();
new Carousel(); // inlines carousel.css and writes data-* settings
new RelatedPostsQuery(); // uses RelatedPosts for ranking
new CssLocalProps();

// Optional: enables the REST endpoint. Must run before `rest_api_init`, e.g. in functions.php
new RelatedPosts();

// Optional: use the ranker directly
// $posts = (new RelatedPosts())->get(['post' => $id, 'posts_per_page' => 4]);

PHP components require WordPress 6.2 or later (WP_HTML_Tag_Processor).

Coexistence

npm and Composer operate independently in the same repository:

npm Composer
Config package.json composer.json
Package name @ideasonpurpose/wp-theme-addons ideasonpurpose/wp-theme-addons
Installs to node_modules/ vendor/
Serves JS + SCSS PHP
Imports resolve via npm package name PSR-4 autoloading

No conflicts: separate config files, separate dependency directories, separate language ecosystems.

graph TD
    subgraph REPO["Single Git Repository: ideasonpurpose/wp-theme-addons"]
        PJ[package.json]
        CJ[composer.json]
        JS[JS + SCSS files]
        PHP[PHP files]
    end

    subgraph NPM_CONSUMER["npm Consumer Project"]
        NPJ[package.json]
        NM[node_modules/]
    end

    subgraph COMPOSER_CONSUMER["Composer Consumer Project"]
        CPJ[composer.json]
        VD[vendor/]
    end

    NPJ -- "npm install" --> PJ
    PJ -- "resolves to" --> NM
    JS -- "import from" --> NM

    CPJ -- "composer require" --> CJ
    CJ -- "resolves to" --> VD
    PHP -- "PSR-4 autoload" --> VD
Loading
  • npm reads package.json → installs to node_modules/ → JS/SCSS imports resolve via @ideasonpurpose/wp-theme-addons
  • Composer reads composer.json → installs to vendor/ → PHP classes autoload via PSR-4
  • No conflicts: separate config files, separate dependency directories, separate language ecosystems.

 

Brought to you by IOP

IOP Logo
     
This project is actively developed and used in production at Ideas On Purpose.