@isudev/gutenberg

Standalone components, controls, fields and hooks for the WordPress Gutenberg editor. No host-project coupling: icons, option lists and configuration are passed in as props, never read from a global registry.

Targets WordPress 7.0 and ships ESM with type declarations. Nothing but @wordpress/* and React at runtime, and both are peer dependencies.

Release status

First release is 0.1.0. While the major is 0, a minor version may change the public API; pin a minor range (~0.1.0) if you need that not to happen mid-project.

Install

npm install @isudev/gutenberg

Requires a block build that externalizes WordPress packages — @wordpress/scripts does this out of the box. Building the library itself requires Node 22.

Using an AI coding agent?

npx @isudev/gutenberg init

This writes the module catalog to .agents/vendor/isudev-gutenberg.md in your project and adds a pointer to your AGENTS.md — plus your Cursor rules and Copilot instructions if you use them — so your agent finds the documentation on its own. Agents do not index node_modules, which is why the copy shipped in the tarball is not enough by itself. Re-run it after upgrading; npx @isudev/gutenberg init --check fails a CI build when the vendored copy has fallen behind.

The same content is in AGENTS.md beside this file, with the machine-readable version in catalog.json. Both are generated when the package is built or packed, so they are present in the installed package but not in the repository.

Importing modules

Prefer the narrowest public subpath. This bypasses the category barrel and gives consumer bundlers the smallest and most explicit module graph:

import { BlockLinkControl } from '@isudev/gutenberg/controls/BlockLinkControl';
import { IconSelect } from '@isudev/gutenberg/components/IconSelect';
import { useBreakpoint } from '@isudev/gutenberg/hooks/useBreakpoint';

Category imports are convenient when several related modules are used together and remain tree-shakeable in production ESM builds:

import { BlockLinkControl, LinkText } from '@isudev/gutenberg/controls';

The root entry point is supported, but component and category subpaths communicate intent more clearly and are preferred in reusable block code. Never import from dist/ directly.

Peer dependencies

The library never bundles React or @wordpress/*; your block build resolves them to the WordPress-provided globals (wp.element, React, ReactJSXRuntime), so there is exactly one copy at runtime. Install whichever peers you actually use:

@wordpress/block-editor  >=15.0.0
@wordpress/components    >=32.0.0
@wordpress/core-data      >=7.0.0
@wordpress/data          >=10.0.0
@wordpress/editor        >=14.0.0
@wordpress/element        >=6.0.0
@wordpress/i18n           >=6.0.0
@wordpress/icons         >=11.0.0
react                    ^18 || ^19

ESM only, and what your build needs to know

The package ships ESM exclusively, and its public surface is defined entirely by exports — there is no main, no CommonJS build, and no dist/ path you are meant to reach into. Two practical consequences:

TypeScript consumers need a modern moduleResolution. The legacy "node" strategy (TypeScript also calls it "node10") predates exports and reads only main, so it finds nothing here and you get no types — regardless of which Node version you run. Use one of:

{
  "compilerOptions": {
    "moduleResolution": "bundler"  // webpack, vite, esbuild — including @wordpress/scripts
    // or "node16" / "nodenext" when the consumer really is Node resolving the package
  }
}

CommonJS consumers need a dynamic import. require( '@isudev/gutenberg/…' ) will not work; use await import( … ). This rarely comes up in block code, which is ESM and bundled.

Neither is an oversight — npm run verify:package asserts exactly this shape with attw --profile esm-only, so the legacy rows it reports are expected rather than broken. @wordpress/scripts needs no configuration for any of it.

Entry points

Import from the narrowest subpath that has what you need — the per-component subpaths skip the category barrel entirely.

| Subpath | Contains | | --- | --- | | @isudev/gutenberg | Everything, re-exported. | | @isudev/gutenberg/breakpoints | DEFAULT_BREAKPOINTS, resolveCascade, isPresent, validateBreakpoints and the Breakpoint type. | | @isudev/gutenberg/components | Pure components — responsive switching, colors, icons and media/focal previews. | | @isudev/gutenberg/components/* | One component, e.g. .../components/BreakpointSwitcher. | | @isudev/gutenberg/controls | Editor controls — responsive, link and modular media editing surfaces. | | @isudev/gutenberg/controls/* | One control, e.g. .../controls/LinkPickerControl. | | @isudev/gutenberg/fields | All fields — SelectField, RadioField. | | @isudev/gutenberg/fields/* | One field. | | @isudev/gutenberg/hooks | useBreakpoint, useResponsiveAttribute, useCurrentPostType, useCurrentPostId, useDebouncedValue, usePrevious. | | @isudev/gutenberg/hooks/* | One hook, e.g. .../hooks/useBreakpoint. | | @isudev/gutenberg/meta | Post-meta wrappers — MetaSelectControl, MetaRadioControl. | | @isudev/gutenberg/meta/* | One wrapper, e.g. .../meta/MetaSelectControl. | | @isudev/gutenberg/taxonomy | Taxonomy wrappers — TaxonomySelectControl. | | @isudev/gutenberg/taxonomy/* | One wrapper, e.g. .../taxonomy/TaxonomySelectControl. | | @isudev/gutenberg/bindings | The binding engine — useFieldBinding, useOptionsSource, useValueBinding and the individual option/value hooks. | | @isudev/gutenberg/appenders | Inner-block appenders — reserved, nothing exported yet. |

Every component, control, field, wrapper and hook has a README.md beside its source documenting all of its props, behaviour and examples; those files ship with the package.

Public module catalog

This is the complete public UI and hook surface currently available. The direct imports shown below are the narrowest supported entry points.

Components

| Module | Purpose | Direct import | | --- | --- | --- | | BreakpointSwitcher | Switches the breakpoint currently being edited, with optional editor-preview synchronization. | import { BreakpointSwitcher } from '@isudev/gutenberg/components/BreakpointSwitcher'; | | ColorPopup | Opens a WordPress color palette from a swatch and returns the full selected color object. | import { ColorPopup } from '@isudev/gutenberg/components/ColorPopup'; | | Icon | Renders a named icon from an injected collection and exports the icon collection helpers. | import { Icon } from '@isudev/gutenberg/components/Icon'; | | IconPicker | Displays a searchable, accessible grid for choosing or clearing an icon. | import { IconPicker } from '@isudev/gutenberg/components/IconPicker'; | | IconSelect | Opens IconPicker from a compact select-style button with the current icon preview. | import { IconSelect } from '@isudev/gutenberg/components/IconSelect'; | | MediaPreview | Renders a serializable image/video value with optional focal positioning. | import { MediaPreview } from '@isudev/gutenberg/components/MediaPreview'; | | MediaFocalPointControl | Provides standalone WordPress focal-point editing for an image or video. | import { MediaFocalPointControl } from '@isudev/gutenberg/components/MediaFocalPointControl'; |

Controls

| Module | Purpose | Direct import | | --- | --- | --- | | ResponsiveControl | Adds breakpoint selection and responsive attribute resolution to any consumer-rendered control. | import { ResponsiveControl } from '@isudev/gutenberg/controls/ResponsiveControl'; | | LinkPickerControl | Attaches WordPress' native link picker to a consumer-rendered trigger through a render prop. | import { LinkPickerControl } from '@isudev/gutenberg/controls/LinkPickerControl'; | | BlockLinkControl | Adds an add/edit link action for a whole block or non-text element to BlockControls. | import { BlockLinkControl } from '@isudev/gutenberg/controls/BlockLinkControl'; | | LinkText | Combines editable RichText, anchor rendering and a native-style toolbar link action. | import { LinkText } from '@isudev/gutenberg/controls/LinkText'; | | MediaPickerControl | Attaches the native media modal to any consumer-rendered trigger and normalizes its value. | import { MediaPickerControl } from '@isudev/gutenberg/controls/MediaPickerControl'; | | MediaSourceControl | Provides native-style library, upload, URL, featured-image and drop-zone sources with independent switches. | import { MediaSourceControl } from '@isudev/gutenberg/controls/MediaSourceControl'; | | MediaCanvasControl | Renders a media placeholder/preview with configurable on-canvas actions. | import { MediaCanvasControl } from '@isudev/gutenberg/controls/MediaCanvasControl'; | | MediaToolbarControl | Adds configurable select, replace and remove actions to BlockControls. | import { MediaToolbarControl } from '@isudev/gutenberg/controls/MediaToolbarControl'; | | MediaSidebarControl | Adds inspector actions with a static, focal-point or disabled preview. | import { MediaSidebarControl } from '@isudev/gutenberg/controls/MediaSidebarControl'; | | MediaControl | Composes canvas, toolbar and sidebar media editing with per-location feature switches. | import { MediaControl } from '@isudev/gutenberg/controls/MediaControl'; |

Fields

| Module | Purpose | Direct import | | --- | --- | --- | | SelectField | Composes a select control from independent options-source and value-binding definitions. | import { SelectField } from '@isudev/gutenberg/fields/SelectField'; | | RadioField | Composes a radio control from independent options-source and value-binding definitions. | import { RadioField } from '@isudev/gutenberg/fields/RadioField'; |

Easy-mode wrappers

| Module | Purpose | Direct import | | --- | --- | --- | | MetaSelectControl | Binds SelectField to one post-meta key. | import { MetaSelectControl } from '@isudev/gutenberg/meta/MetaSelectControl'; | | MetaRadioControl | Binds RadioField to one post-meta key. | import { MetaRadioControl } from '@isudev/gutenberg/meta/MetaRadioControl'; | | TaxonomySelectControl | Provides a single-term taxonomy picker bound to the current post. | import { TaxonomySelectControl } from '@isudev/gutenberg/taxonomy/TaxonomySelectControl'; |

Hooks

| Module | Purpose | Direct import | | --- | --- | --- | | useBreakpoint | Owns the selected breakpoint with optional two-way editor-preview synchronization. | import { useBreakpoint } from '@isudev/gutenberg/hooks/useBreakpoint'; | | useResponsiveAttribute | Reads, resolves and writes one logical attribute across a breakpoint cascade. | import { useResponsiveAttribute } from '@isudev/gutenberg/hooks/useResponsiveAttribute'; | | useCurrentPostType | Returns the post type currently open in the editor. | import { useCurrentPostType } from '@isudev/gutenberg/hooks/useCurrentPostType'; | | useCurrentPostId | Returns the ID of the post currently open in the editor. | import { useCurrentPostId } from '@isudev/gutenberg/hooks/useCurrentPostId'; | | useDebouncedValue | Returns a value only after the configured quiet period has elapsed. | import { useDebouncedValue } from '@isudev/gutenberg/hooks/useDebouncedValue'; | | usePrevious | Returns the value from the component's previous committed render. | import { usePrevious } from '@isudev/gutenberg/hooks/usePrevious'; |

The lower-level breakpoints and bindings entry points are also public for advanced composition. Their API is summarized in Entry points; the modules above are the recommended starting point for block development.

Example

A block setting that differs per breakpoint:

import { ResponsiveControl } from '@isudev/gutenberg/controls';
import { RangeControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

<ResponsiveControl
	attrName="columnGap"
	label={ __( 'Column Gap' ) }
	attributes={ attributes }
	setAttributes={ setAttributes }
>
	{ ( { value, inheritedValue, onChange } ) => (
		<RangeControl
			value={ value }
			placeholder={ inheritedValue }
			onChange={ onChange }
			__next40pxDefaultSize
		/>
	) }
</ResponsiveControl>

The base breakpoint writes columnGap; the others write columnGapTablet and columnGapMobile. Declare every one of them in block.json.

Documentation

The colocated module READMEs are the source of truth for API documentation and will feed a dedicated GitBook in the future. The public module catalog is the current documentation index and must stay synchronized with the exported modules.

License

MIT — see LICENSE.