Gradient Borders for Blocks

Adds a Gradient border control to any WordPress block that already supports the native border block support (Group, Buttons, Image, Cover, and others). Editors can pick one of the theme's predefined gradients or define a fully custom one, and a gradient ring is drawn around the block using the block's own native border width (and, where possible, its own corner radius) — no separate width control to keep in sync.

• Uses the block's own real border — enable it, then adjust the width in the native Border & Shadow panel like normal.
• Respects rounded corners when the block's own background is a solid color or gradient. When the block has a background image (or no background at all) and a radius, the ring falls back to square corners rather than risk covering the image — see How the gradient is drawn.
• Renders identically in the editor canvas and on the front end, and works for both statically-saved blocks and dynamically-rendered ones (Latest Posts, Query Loop, etc.).

How the gradient is drawn

This plugin picks between two real-border CSS techniques per block, based on whether it has a corner radius set (full reasoning in AGENTS.md):

• No radius → border-image. Paints the gradient directly into the border box. Never touches the block's background, so it's always safe — its only limitation is square corners, which don't matter here anyway.
• Radius set, and the block's background is a solid color or gradient → background-clip double-background. The block's own background is mirrored as an opaque interior layer underneath the gradient, so rounded corners work correctly without erasing the block's real background.
• Radius set, but the background can't be safely mirrored (a background image, or no background at all) → falls back to border-image, trading rounded corners for never risking a broken or incorrect background.

Requirements

• WordPress 6.5+
• PHP 7.4+
• Node.js (for building the editor JS bundle from source — see below)

Installation

1. Copy this directory into wp-content/plugins/.
2. If the build/ directory isn't already present (e.g. you pulled from source control before a build was committed), run:

   npm install
   npm run build

3. Activate Gradient Borders for Blocks from the Plugins screen (or wp plugin activate gradient-borders-for-blocks).

Usage

1. In the block editor, select a block that supports borders.
2. Open the block inspector's Styles tab (the half-circle icon) and expand the native Border & Shadow panel — a Gradient border toggle appears inside it, directly below the Radius control.
3. Toggle it on and choose a gradient (a theme preset, if the active theme defines any, or type a custom one). Adjust the width in the same panel, same as any other border.
4. The ring previews live in the canvas and appears identically once the post is published/viewed. If the block has rounded corners but no plain background color/gradient of its own, a warning explains that the ring will have square corners and points you at the background color control.

Blocks that don't support the native border setting (e.g. Paragraph) never show this control and are untouched by the plugin.

Development

npm install
npm run start   # watch mode, for local development
npm run build   # production build (writes to build/)

Source lives in src/:

• src/index.js — registers the block attribute, the inspector controls, and the editor-canvas live preview.
• src/style.css — the border-image/background-clip gradient-ring CSS, shared by the editor and the front end.

The PHP entry point, gradient-borders-for-blocks.php, enqueues the built assets and applies the same class/inline custom properties on the front end via a render_block filter.

See AGENTS.md for a fuller technical breakdown, intended for anyone (human or AI) making further changes to this plugin.

Try it without installing anything

The Try it live badge above opens a disposable WordPress instance in WordPress Playground with the plugin already installed and activated, and a demo page (set as the homepage) showing all four variants described above. Nothing you do there touches your own site — it all runs in-browser and resets when you close the tab.

The blueprint behind that link lives at .wordpress-playground/blueprint.json. It installs the plugin straight from this repo's trunk branch via Playground's git:directory resource (no build artifacts duplicated into the blueprint itself), then runs a short runPHP step that inserts the demo page and sets it as the site's front page.