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 / labelMode: 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 with 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

Props

Name	Description
ariaLabel	Type string | null Default null
customError	Custom validation message; also settable via setCustomValidity(). Type string | null Default null
defaultValue	Type string
disabled	Disables the control and excludes it from constraint validation. Type boolean Default false
emptyMessage	Type string Default No items match your query.
invalid	Type boolean Default false
isInvalid	Alias for invalid.
labelMode	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	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
readOnly	Alias for readonly.
required	Marks the control as required for form submission. Type boolean Default false
searchPlaceholder	Type string Default Search…
selectedLabel	Closed-trigger label when value is set but not yet found in items / groups (e.g. catalog still loading). Type string
selectedPreview	Closed-trigger preview for the same pre-catalog case as selected-label. Type string
sideOffset	Type number Default 4
size	Type PkImageBrowserSize Default default
value	Type string
width	Type PkImageBrowserWidth Default auto
withClear	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".