Kappa / Resource Picker

Overview

Resource Picker combines Kappa Dialog Layout, Selection List, Input, Button, Loader, and Empty. The application supplies resource data and performs network requests.

Use it when selection requires search, descriptions, or an explicit confirmation step. Use Select for a short field value or Selection List for a list that must stay visible.

Examples

Choose an item

Search item names and details. Confirm to apply the selection; Cancel keeps the previous item.

Selected itemTeam handbook

<script setup>
import { ref } from "vue";
import { ResourcePicker, Button } from "@dicehub/kappa";

const selected = ref(["handbook"]);
const items = [
  { value: "handbook", label: "Team handbook", description: "Shared document", meta: "Updated today" },
  { value: "guidelines", label: "Brand guidelines", description: "Shared document", meta: "Updated yesterday" },
  { value: "archive", label: "Archived draft", disabled: true },
];
</script>

<template>
  <ResourcePicker v-model="selected" :items="items" title="Choose an item">
    <template #trigger><Button variant="secondary">Choose item</Button></template>
  </ResourcePicker>
</template>

Attach files

Select files across searches. The selection count includes resources outside the current results.

Selected filesreport.pdf

<script setup>
import { ref } from "vue";
import { ResourcePicker } from "@dicehub/kappa";
const selected = ref(["report"]);
const files = [
  { value: "report", label: "report.pdf", meta: "1.2 MB" },
  { value: "notes", label: "notes.txt", meta: "840 KB" },
  { value: "archive", label: "archive.zip", meta: "24 MB" },
];
</script>

<template>
  <ResourcePicker
    v-model="selected"
    :items="files"
    title="Attach files"
    selection-mode="multiple"
    :labels="{ trigger: 'Choose files', confirm: 'Attach files' }"
  />
</template>

Loading, empty, and error

The application supplies the data and loading state. Retry requests another load from the application.

<ResourcePicker
  v-model="selectedIds"
  v-model:open="pickerOpen"
  :items="results"
  :loading="pending"
  :error="errorMessage"
  filter-mode="external"
  title="Choose resources"
  @search-change="searchResources"
  @retry="reloadResources"
/>

Installation

import { ResourcePicker } from "@dicehub/kappa";
// Or the dedicated block entrypoint:
import { ResourcePicker } from "@dicehub/kappa/blocks/resource-picker";

Opening the dialog copies the committed IDs into a draft. Selecting a row changes the draft. Confirm emits update:modelValue and confirm, then requests closure. Cancel, Escape, the close control, and an outside click discard the draft. The next opening starts from the current committed value.

The value is always a string array. In multiple mode, a click toggles a row without modifier keys. Search does not clear the selection. Local search matches labels, descriptions, metadata, and keywords without case sensitivity.

In external mode, listen to searchChange and supply the results, loading flag, and error message. Debounce requests and cancel stale responses in your application. Selected IDs remain available across result pages. Removed or disabled local resources cannot be confirmed. In external mode, the consumer must validate IDs that are absent from the current result set.

The list is scrollable, not virtualized. Use server-side search and a limited result set for large collections. Use Virtual Tree for large hierarchical data.

API

Prop	Type	Default	Purpose
items	ResourcePickerItem[]	required	Available resources; each value must be unique.
modelValue / defaultValue	string[]	[]	Committed IDs. Single selection also uses an array.
open / defaultOpen	boolean	false	Controlled or initial dialog state.
title	string	"Choose a resource"	Accessible dialog and list name.
description	string	—	Optional supporting text in the dialog header.
selectionMode	"single" \| "multiple"	"single"	Select one resource or toggle several.
filterMode	"local" \| "external"	"local"	Local search includes label, description, meta, and keywords.
loading / error	boolean / string	false / —	Replace results and disable confirmation.
allowEmpty	boolean	false	Permit confirmation with no selected resources.
disabled	boolean	false	Disable the trigger, selection, and confirmation.
labels	Partial<ResourcePickerLabels>	English labels	Translate controls, states, and the selectionCount function.

Items

interface ResourcePickerItem {
  value: string;
  label: string;
  description?: string;
  meta?: string;
  keywords?: string[];
  disabled?: boolean;
}

Events

update:open(boolean), update:modelValue(string[]), confirm(string[]), cancel(), searchChange(string), and retry(). Use v-model:open and v-model for controlled state.

Slots

trigger accepts one button. media, description, and meta receive { item }. Keep their contents non-interactive. empty receives { query }, error receives { message, retry }, loading replaces the loading state, and selection receives { value }.

Attributes, including class, style, and data attributes, are forwarded to the dialog content. Import ResourcePickerProps, ResourcePickerItem, and ResourcePickerLabels from the same entrypoint.

Accessibility

Kappa Dialog traps focus, closes on Escape, and restores focus to the trigger. The search input receives initial focus. Selection List supplies listbox roles, arrow-key navigation, disabled options, and selected states. Enter selects the highlighted resource; it does not confirm the dialog. Tab moves to Cancel and the confirmation button.

Use unique resource values and a clear title. Keep resource labels understandable without icons. Loading, errors, empty results, and selection counts are announced. Kappa components support visible focus and reduced motion.