Field Picker

FTFieldPicker picks one value out of many, when the values fall into categories. The trigger opens a panel with three columns: the categories, the items of the selected category, and the detail of the item under the cursor. Typing in the trigger searches every category at once.

Use it instead of FTSelect when a flat list is too long to scan, or when each option needs an explanation before the user can choose.

Usage

vue

<script setup lang="ts">
  import { FTFieldPicker } from '@fasttrack-solutions/vue-components-lib';
  import type { IFTFieldPickerItem } from '@fasttrack-solutions/vue-components-lib';
</script>

<script setup lang="ts">
  import { FTFieldPicker } from '@fasttrack-solutions/vue-components-lib';
  import type { IFTFieldPickerItem } from '@fasttrack-solutions/vue-components-lib';
</script>

INFO

vue

<script setup lang="ts">
  import { ref } from 'vue';
  import { FTFieldPicker } from '@fasttrack-solutions/vue-components-lib';

  const model = ref(null);

  const categories = [
    { key: 'player', label: 'Player', icon: 'fas user' },
    { key: 'bonus', label: 'Bonus' },
  ];

  const items = [
    {
      value: 'player-country',
      label: 'Country',
      category: 'player',
      description: 'The country the player registered from.',
      samples: ['SE', 'FI'],
      meta: [{ label: 'Data type', value: 'string' }],
    },
    { value: 'bonus-name', label: 'Bonus name', category: 'bonus' },
  ];
</script>

<template>
  <FTFieldPicker v-model="model" :items="items" :categories="categories" label="Segment field" allow-clear />
</template>

<script setup lang="ts">
  import { ref } from 'vue';
  import { FTFieldPicker } from '@fasttrack-solutions/vue-components-lib';

  const model = ref(null);

  const categories = [
    { key: 'player', label: 'Player', icon: 'fas user' },
    { key: 'bonus', label: 'Bonus' },
  ];

  const items = [
    {
      value: 'player-country',
      label: 'Country',
      category: 'player',
      description: 'The country the player registered from.',
      samples: ['SE', 'FI'],
      meta: [{ label: 'Data type', value: 'string' }],
    },
    { value: 'bonus-name', label: 'Bonus name', category: 'bonus' },
  ];
</script>

<template>
  <FTFieldPicker v-model="model" :items="items" :categories="categories" label="Segment field" allow-clear />
</template>

The item

Each item names its own category. The component does the grouping, the sorting and the search, so the consumer keeps its own domain rules.

Field	Type	Purpose
`value`	`string \| number`	Emitted when the item is picked. Required.
`label`	`string`	Row label. Required.
`category`	`string`	Category key. Required.
`description`	`string`	First block of the detail column.
`samples`	`string[]`	Example values, joined with commas.
`meta`	`{ label, value }[]`	Detail rows, rendered as a definition list.
`icon`	`string`	FTIcon name, shown before the label.
`keywords`	`string[]`	Extra search terms.
`disabled`	`boolean`	Shown, never selectable.
`disabledReason`	`string`	Row title, shown on hover.

The category

Pass categories to fix the order and the labels. Without it, categories sort alphabetically and the key doubles as the label. Categories that the items name but the prop does not declare follow the declared ones, alphabetically.

Field	Type	Purpose
`key`	`string`	Matches `category` on the items.
`label`	`string`	Column label. Falls back to `key`.
`icon`	`string`	FTIcon name.

Props

Prop	Default	Purpose
`modelValue`	`null`	The selected value.
`items`	—	The items. Required.
`categories`	`undefined`	Category order, labels and icons.
`label`	`''`	Label above the trigger.
`isRequired`	`false`	Shows the required asterisk.
`errorMessage`	`''`	Error text below the trigger.
`placeholder`	`'Select a field'`	Trigger text with no value.
`searchPlaceholder`	`'Type to search'`	Trigger text while open.
`categoriesHeader`	`'Category'`	Header of column 1.
`itemsHeader`	`'Fields'`	Header of column 2.
`resultsHeader`	`'Results'`	Header of the search column.
`emptyText`	`''`	Text when the search matches nothing.
`detailEmptyTitle`	`'Pick a field'`	Title of the empty detail column.
`detailEmptyHint`	`'Select a category, then an item to see its details here.'`	Hint below that title.
`icon`	`'fas columns-3'`	Leading icon on the trigger.
`disabled`	`false`	Blocks the trigger and every emit.
`loading`	`false`	Shows a spinner in the panel.
`allowClear`	`false`	Adds a clear button, which emits `null`.
`id`	`''`	Input id. Generated when empty.

Events

Event	Payload	When
`update:modelValue`	`string \| number \| null`	An item is picked, or the value is cleared.
`change`	`IFTFieldPickerItem \| null`	The same moment, with the whole item.
`open`	—	The panel opens.
`close`	—	The panel closes.

Slots

Slot	Scope	Replaces
`item`	`{ item, active }`	The content of one row.
`detail`	`{ item }`	The whole detail column.
`empty`	—	The empty state of the detail column.
`loading`	—	The panel's loading state, shown while `loading` is true. Defaults to an icon-only `FTSpinner`.

Exposed methods

open(), close() and focus(), for hosts that drive the picker from outside.

Keyboard

Key	Action
`Enter`, `Space`, `ArrowDown`	Opens the panel.
`ArrowUp`, `ArrowDown`	Moves inside the focused column.
`ArrowLeft`, `ArrowRight`	Switches between the category column and the item column.
`Enter`	Picks the active item.
`Escape`	Closes and returns focus to the trigger.
`Tab`	Closes and moves on.

While a search term is present, the arrow keys move through the results.

Styling

The panel teleports to the body, so it is never clipped by a scrolling parent. Override these variables to change its size or stacking order.

Variable	Default
`--ft-field-picker-panel-width`	`886px`
`--ft-field-picker-panel-height`	`400px`
`--ft-field-picker-column-width`	`240px`
`--ft-field-picker-items-column-width`	`280px`
`--ft-field-picker-z-index`	`1000`
`--ft-field-picker-trigger-height`	`38px`
`--ft-field-picker-error-color`	`var(--color-brand-red-500)`

Field Picker ​

Usage ​

The item ​

The category ​

Props ​

Events ​

Slots ​

Exposed methods ​

Keyboard ​

Styling ​