Image Browser

Presentational picker for static icons and images supplied by the host — filesystem catalogs, icon sets, preview folders. Plugin Kit does not scan disks or filter file types; assign items or groups with already-resolved preview URLs or inline SVG.

label is display text (a curated name or a filename). value is what gets stored. Use this instead of Craft asset pickers when the value must travel with Project Config across environments.

Grid name visibility is controlled by label-mode: tooltip (default — shared hover tip), inline (caption under each cell), or none (aria-label only).

Icon Mode

Default icon catalog — compact glyphs with label-mode="tooltip".

Icon Inline Labels

Captions under each glyph (label-mode="inline").

Icon No Labels

Names stay on aria-label only (label-mode="none").

Image Mode

Default image catalog — larger photo tiles with label-mode="tooltip".

Image Inline Labels

Captions under each photo (label-mode="inline").

Image No Labels

Names stay on aria-label only (label-mode="none").

Grouped Icons

Named groups, search, and scroll paging when a set is large. Use groups instead of a flat items list.

Grouped Images

Same groups API in mode="image" — headings sit above photo tiles.

Loading

Host-driven catalog warm. Set loading until items / groups arrive — the open panel shows a centered spinner (no loading copy). Pair with selected-label / selected-preview so the closed trigger still reflects a stored value before the catalog is ready.

API

Attributes & Properties

Name	Description
ariaLabel aria-label	Type string | null Default null
customError custom-error	Custom validation message; also settable via setCustomValidity(). Type string | null Default null
defaultValue default-value	Type string
disabled	Disables the control and excludes it from constraint validation. Type boolean Default false
emptyMessage empty-message	Type string Default No items match your query.
invalid	Type boolean Default false
labelMode label-mode	How option names appear in the grid: tooltip (default), inline under each cell, or none (aria-label only). Type PkImageBrowserLabelMode Default tooltip
loading	Host-driven catalog warm / refresh. Shows a centered pk-spinner in the panel (no loading copy). Prefer this over inferring from empty items / groups — empty can also mean a filter miss or a genuinely empty catalog. Type boolean Default false
mode	icon = compact glyph tiles; image = larger photo tiles. Type PkImageBrowserMode Default icon
name	Name submitted with form data. Type string | null Default null
open	Type boolean Default false
pageSize page-size	Items drawn per group before scroll reveals the next page. Type number Default 96
placeholder	Type string Default Choose…
placement	Type PkPopupPlacement Default bottom-start
readonly	Type boolean Default false
required	Marks the control as required for form submission. Type boolean Default false
searchPlaceholder search-placeholder	Type string Default Search…
selectedLabel selected-label	Closed-trigger label when value is set but not yet found in items / groups (e.g. catalog still loading). Type string
selectedPreview selected-preview	Closed-trigger preview for the same pre-catalog case as selected-label. Type string
sideOffset side-offset	Type number Default 4
size	Type PkImageBrowserSize Default default
value	Type string
width	Type PkImageBrowserWidth Default auto
withClear with-clear	Show a clear control when a value is selected. Type boolean Default true

Methods

Name	Description
checkValidity()	Runs constraint validation without showing the browser UI.
hide(source: PkOverlaySource)	—
reportValidity()	Runs constraint validation and shows the browser UI when invalid.
resetValidity()	Clears custom errors and re-syncs validity state.
setCustomValidity(message: string)	Sets or clears a custom validation message.
show()	—

Events

Name	Description
change	—
input	—
pk-change	—

Custom States

Name	Description	CSS selector
disabled	The control is disabled.	:state(disabled)
invalid	The control currently fails constraint validation.	:state(invalid)
optional	The control is not required.	:state(optional)
required	The control is required.	:state(required)
user-invalid	Invalid after the user has interacted with the control.	:state(user-invalid)
user-valid	Valid after the user has interacted with the control.	:state(user-valid)
valid	The control currently passes constraint validation.	:state(valid)

CSS Parts

Name	Description	CSS selector
clear-button	Clear selection button (inside the control)	::part(clear-button)
loading	Catalog-loading status region (spinner)	::part(loading)
option	Grid cell button	::part(option)
panel	Popup panel shell	::part(panel)
panel-body	Scrollable results region	::part(panel-body)
panel-input	Search input	::part(panel-input)
panel-search	Search field container	::part(panel-search)
root	Filled control surface (trigger + clear + chevron)	::part(root)
trigger	Opens the panel (preview + label)	::part(trigger)

Dependencies

This component registers the following elements when it loads.

Name	Description
pk-popup	Positioned panel host.
pk-spinner	Shown in the panel while loading is set.
pk-tooltip	Hover label when label-mode="tooltip".