Display & Actions

These types are stateless — they don’t persist a value. They render UI and (for export / import / upload / action) wire into server-side flows.

Types

Type	Description	Stored as
`html`	Read-only display block (info, success, warning, error variants)	—
`export`	Download settings as JSON	—
`import`	Upload JSON to restore settings	—
`upload`	Pick a local file to send with an action request	—
`action`	One or more buttons that dispatch to a server-side hook	—

`html`

A read-only block of markup. Ships with built-in prose styling — paragraphs, headings, lists, blockquotes, inline + block <code>, tables, images, <hr> — using the framework’s WPDS tokens, so raw markup renders with sensible spacing.

[
    'id'   => 'docs_link',
    'type' => 'html',
    'args' => [
        'variant' => 'info',
        'content' => '<p><strong>Tip:</strong> See the <a href="…">setup guide</a> for the full walkthrough.</p>',
    ],
],

Variants

plain (default), info, success, warning, error. Affects the surrounding chrome but not the prose inside.

`export`

Renders a download button. Clicking serialises the page’s saved settings to JSON and triggers a browser download.

[
    'id'    => 'backup',
    'type'  => 'export',
    'label' => __('Export settings', 'my-plugin'),
    'args'  => [
        'button_label' => __('Download JSON', 'my-plugin'),
        'filename'     => 'my-plugin-settings',
    ],
],

`import`

Pairs with export — file picker + button that uploads a JSON file and replaces the page’s saved settings.

[
    'id'    => 'restore',
    'type'  => 'import',
    'label' => __('Import settings', 'my-plugin'),
    'args'  => [
        'button_label' => __('Upload JSON', 'my-plugin'),
    ],
],

`upload`

Picks a file in the browser and sends it with action requests. The file is never uploaded to the Media Library and never saved — pair it with an action field whose handler processes it, e.g. a CSV import.

['id' => 'csv_file', 'type' => 'upload', 'label' => __('CSV file', 'my-plugin'), 'columns' => 6,
    'args' => ['accept' => '.csv,text/csv', 'max_size' => MB_IN_BYTES, 'button_label' => __('Choose CSV', 'my-plugin')],
],
['id' => 'import_csv', 'type' => 'action', 'label' => __('Import', 'my-plugin'), 'columns' => 6,
    'args' => ['button_label' => __('Import rows', 'my-plugin'), 'variant' => 'primary'],
],

Arg	Default	Notes
`accept`	`''`	`<input>` accept filter, e.g. `'.csv,text/csv'`.
`max_size`	5 MB	Maximum size in bytes, checked in the browser and on the server.
`button_label`	—	Picker button text.

The handler receives the file in $values as ['name', 'type', 'size', 'content'], where content is a base64 data URL:

add_filter('my-plugin/action/default/import_csv/run', function ($unhandled, array $values) {
    $file = $values['csv_file'] ?? null;
    if (!is_array($file)) {
        return ['status' => 'error', 'message' => __('Choose a CSV file first.', 'my-plugin')];
    }

    [, $base64] = explode(',', $file['content'], 2);
    $csv = base64_decode($base64);
    // … parse and import
}, 10, 2);

The server only accepts base64 data URLs and checks max_size against the decoded length, not the size the browser reports; anything invalid arrives as null.

`action`

One or more buttons that POST in-flight form values to a server-side hook. Config is pure data — handlers wire in via add_filter.

[
    'id'      => 'billing_tools',
    'type'    => 'action',
    'label'   => __('Billing tools', 'my-plugin'),
    'args'    => [
        'buttons' => [
            ['id' => 'refresh_stats', 'label' => __('Refresh stats', 'my-plugin'), 'variant' => 'primary'],
            ['id' => 'export_csv',    'label' => __('Export CSV',    'my-plugin')],
            ['id' => 'wipe',          'label' => __('Wipe',          'my-plugin'),
             'destructive' => true,
             'confirm'     => __('Wipe everything? This cannot be undone.', 'my-plugin')],
        ],
    ],
],