Download the PHP package matterwp/admin-ui without Composer

MatterWP Admin UI

Reusable admin UI helpers, styles, and small JavaScript behaviors for MatterWP WordPress plugins.

Installation

Install the package with Composer:

Release-line namespaces prevent bundled copies from colliding across WordPress plugins:

• 1.3.x uses MTWP\ADMIN\V130
• 1.2.x uses MTWP\ADMIN\V120

• 1.1.x uses MTWP\ADMIN\V110

• Patch releases keep the namespace of their minor release line

Load Composer's autoloader from your plugin bootstrap if your plugin does not already do so:

Import the helpers you need:

Assets

The package includes compiled CSS and JavaScript in dist/ for direct use from WordPress plugins.

Call wp_enqueue_media() on admin pages that render media fields.

Extension model

matterwp/admin-ui is intended to be used as a Composer package. Plugins should consume the base components and extend them with arguments, stable classes, WordPress filters, CSS custom properties, and plugin-specific JavaScript.

Avoid copying package internals into consuming plugins. If a plugin needs a very custom workflow, compose it from smaller admin-ui primitives or use component slots/callbacks where available.

This package only provides admin UI components, assets, and small browser services. It does not include subscription, onboarding, licensing, or analytics dependencies; consuming plugins own those integrations when needed.

Attribute helpers

Use UI::attrs() or UI::dataAttrs() when a plugin needs to render escaped attributes consistently with the package.

Layout Shells

Sections and options are the base shells for admin screens. A section groups related content. An option row arranges the label, supporting copy, counters, and the control/content area. Inputs, buttons, forms, cards, tables, and custom markup should fit into these shells without each component inventing layout chrome.

Most helpers accept class, attributes, and data_attributes for the component root. Nested wrappers accept classes slot maps, while legacy scoped keys such as title_class, options_class, info_class, description_class, input_class, header_class, content_class, table_class, and pagination_class still work.

Sections support:

• title and description: string content, or false to hide.
• section_variant: wrapped for normal grouped section chrome, or minimal for direct card, stat, table, or result layouts.
• option_variant: standard for normal option rows, or minimal for option rows without row chrome or padding.

Deprecated variant and option_box aliases remain supported for 1.x consumers.

Use section_variant => 'minimal' for direct content such as tables, stat grids, cards, and result blocks:

UI::grid() accepts columns => 1..6|'auto'|'fit'|'fill', min_width, gap, row_gap, column_gap, density => 'compact'|'comfortable'|'spacious', align_items, justify_items, class, attributes, and data_attributes.

Use UI::divider() for section dividers. It renders a separator with CSS-variable-backed height, margin, and padding.

Options support:

• title and description: string content, or false to hide.
• input_label: show or hide the option label/info block. When true and input_id is provided, the title renders as a <label>.
• label_width: standard or full.
• layout: row, column, or divided.
• control_width: narrow, standard, wide, or full.
• align: center, start, or stretch.
• badge, help, and actions for option metadata and inline commands.

Deprecated style, wide, divider, and align_start aliases remain supported for 1.x consumers.

Use section_variant => 'minimal' for a table rendered directly in a section:

Schema-driven rows can use schemaOption():

Forms support variant => 'plain', columns => 1|2|3|'auto', and actions_align => 'left'|'right'|'between'.

Inputs support standard text-like controls plus schedule controls: text, number, url, email, password, search, color, tel, hidden, date, time, datetime-local, month, and week. The same types work in generated form() fields and schemaOption() rows.

For a schedule row with start/end datetime and timezone, compose a column option with fieldGrid():

Badges support size => 'compact'.

Buttons support named/custom SVG icons with icon and icon_position => 'before'|'after'.

UI::app() renders the common admin shell:

UI::navigation() is also available as a standalone component. Each group supports an optional label, alignment => 'top'|'bottom', and an items map. The shell includes package-owned tab persistence, active indicator measurement across groups, a dark-mode toggle, and an optional linked version badge via changelog_url. Use UI::fieldGrid() or form( array( 'fields' => ..., 'actions' => ... ) ) for generated form layouts.

Schema rows now understand richer metadata: ui, component, option, control, layout, control_width, media, choices_display, placeholder, help, dependencies, visible_if, disabled_if, and requires. Components include color_picker, media, switch, select, textarea, and standard inputs.

Tables

Admin tables use .mwp-table-wrap and .mwp-table. Columns can be strings or typed arrays with label, type, and optional callback. Supported cell types include badge, link, code, image, date, and actions.

UI::paginatedTable() supports pagination_mode => 'client'|'server', previous/next buttons, a page label, default per_page of 10, empty states, loading/error states, and server metadata through endpoint, action, nonce, current_page, total, and total_pages.

UI::dataTable() adds row-level and typed-column arguments for plugin-managed tables: row_id, row_key, row_attributes, row_data_attributes, row_class, empty_state, pagination, table_class, wrap, min_width, max_width, overflow, vertical_align, strip_site_url, display_callback, and format => 'relative_site_url'. Column types include text, title, link, external_link, code, image, badge, date, and actions. Columns support sortable => true, optional sort_key, and sort_callback.

Filters and search are first-class. Structured filters render package-owned button groups, search renders the search field, and filter_mode defaults to the pagination mode. Client tables filter and sort existing rows; server tables send filter, search, orderby, and order parameters to the configured endpoint.

The Boilerplate Blocks tab includes a server DataTable example with a type filter and search input. The package owns the filter/search markup and sends the active values to the AJAX handler; plugin code only reads request params and returns UI::dataTableResponse(). During local development, if another active plugin loads an older MTWP\ADMIN\V110 package first, update that plugin's admin-ui copy or add a compatibility render path for the demo controls.

AJAX handlers should use the same column schema and return UI::dataTableResponse():

The JavaScript table API is available as:

For compact table action columns, use UI::actionGroup() with named or custom SVG icons:

Named icons include edit, delete, trash, x, link, external-link, download, copy, view, image, play, pause, and refresh.

Modals, Ajax, And Results

Modals can be rendered without a trigger by passing render_trigger => false or trigger => false. Modal fields support attributes, data_attributes, readonly, required, placeholder, autocomplete, min, max, step, field_class, and layout. Footer actions support id, attributes, data_attributes, disabled, loading, size, and icon.

Ajax forms can use data-mwp-ajax-form, data-mwp-action, data-mwp-submit, and data-mwp-loading. The package exposes MatterAdminUI.ajax.submit(formOrRoot, options) and dispatches mwp:ajax-before, mwp:ajax-success, mwp:ajax-error, and mwp:ajax-complete.

Use MatterAdminUI.notice(message, type, options) for stacked, animated package-managed notices. Use UI::resultCard() for generated previews, exported files, uploaded assets, API keys, reports, or other Ajax results.

Use UI::emptyState() for neutral dashed empty blocks. Pair with paginated tables via empty_target or empty_selector. Pass a callback as the second argument to render custom static content, buttons, or HTML inside the empty-state content area.

Dynamic modals

Modal markup follows the package contract: triggers use data-mwp-modal-trigger, aria-controls, aria-haspopup="dialog", and aria-expanded; modals use data-mwp-modal, aria-hidden, and hidden; close controls use data-mwp-modal-close.

JavaScript exposes window.MatterAdminUI.openModal(idOrElement, values, trigger), closeModal(idOrElement), and populateModal(idOrElement, values) for edit modals. Values are matched by name or data-mwp-field.

Modals can generate simple fields with fields and submit controls with footer_actions:

scss html[data-mwp-theme="dark"] { --mwp-ui-primary: #6366f1; --mwp-ui-primary-hover: #818cf8; }

The value propagates to all primary-chain tokens: action-primary bg / bg-hover / border / border-hover / text, focus ring, switch active track, progress bar, nav upgrade button, premium badge, upsell action, primary badge, log filter active state.

For fine-grained control, override the individual `--mwp-action-primary-*` tokens instead — the dark block now redeclares them explicitly so the dark theme is self-contained.

If you want the same brand color in both themes, do nothing — the dark block's default matches the light block.

### Other tokens

Other overridable token families: `--mwp-color-*` (surfaces, borders, text, danger / warning / success / info / upsell), `--mwp-color-nav-active`, and per-component tokens like `--mwp-table-filter-active-*`, `--mwp-log-filter-active-*`, `--mwp-primary-badge-*`, and `--mwp-toast-*`. See `_tokens.scss` for the full list.

## Media field customization

The media field supports compact, logo, wide, and button-only modes. It can also be customized with CSS variables, data attributes, slots, and filters.

For deeper customization, pass callable slots:

Available media filters:

- `matterwp_admin_ui_media_field_args`
- `matterwp_admin_ui_media_field_preview`
- `matterwp_admin_ui_media_field_actions`

Available media JavaScript events:

- `mwp:media-selected`
- `mwp:media-removed`

Both events bubble from the media field root and include `uid`, `field`, and related control details in `event.detail`.