SwSelect

SwSelect is a dropdown selector: options are tucked into a popup and the trigger stays collapsed. Single- and multi-select live in one component (the multiple switch), with support for clearing (clearable), grouping (the option group field), searching (searchable), and create-on-type (creatable). It's a controlled v-model — a single value for single-select, an array for multi-select.

It's a thin shell over reka-ui: the default branch is built on the Select primitives; with searchable it internally switches to the Combobox primitives (the trigger becomes an input) while keeping the same props / v-model / slots. The popup is self-rendered (not the OS popup of a native <select>), so it's fully customizable; keyboard navigation, popup positioning, and a11y all work out of the box. Visuals follow a "minimal necessary baseline" — the trigger, popup, selected, highlighted, and disabled states are all distinguishable by default; colors, corner radius, etc. are left to the applier to override.

When to use: reach for this component (a dropdown) when there are many options and you need to save horizontal space. When you have few options (2–5), want them all visible, and want to save a click, use SwSegmented (laid out flat). The two are complementary — much like antd ships both Select and Segmented.

Single select

<script setup lang="ts">
const status = ref()
</script>

<template>
  <SwSelect
    v-model="status"
    :options="[
      { value: 'all', label: '全部状态' },
      { value: 'ongoing', label: '连载中' },
      { value: 'completed', label: '已完结' },
    ]"
    placeholder="选择状态"
    aria-label="状态筛选"
  />

  <!-- Disable the whole select: lock it while the parent form is pending / no permission -->
  <SwSelect v-model="status" :options="options" disabled />
</template>

Multi-select + clearable

multiple turns v-model into an array; clearable shows a one-click clear button when there's a selected value. In multi-select mode the trigger shows "已选 N 项" (N selected) by default; to render tags / chips, go through the #trigger slot:

Grouping

When options carry a group field, consecutive same-named ones are merged into one group and a group title is rendered at the head of the group; without group the list is flat:

<template>
  <SwSelect
    v-model="city"
    :options="[
      { value: 'bj', label: '北京', group: '直辖市' },
      { value: 'sh', label: '上海', group: '直辖市' },
      { value: 'hz', label: '杭州', group: '浙江' },
    ]"
  />
</template>

Searchable

searchable turns the trigger into an input: typing filters options locally by label (case-insensitive substring match; groups whose items are all filtered out are hidden), and ↑↓ + Enter selects. Use it when there are dozens or hundreds of options (cast & crew / tags / cities); when the set is too large to fetch at once (a media library / all users), use remote search below.

In single-select mode the input shows the selected label (after the popup opens, the list isn't filtered until you type — so the selection doesn't lock the list); in multi-select mode selected items render as chips (label + ✕ to remove; Backspace on an empty input removes the last one).

Remote search (remote + @search + loading)

Three pieces combine into "search one, pick one from a large set": remote turns off local label filtering (options is the remote result set — items the server matched by pinyin / alias / id may not contain the keyword in their label, and a second local pass would hide them); @search(term) hands the user's input to the business (debounced by searchDebounce, default 300ms; clearing emits '' immediately so you can reset the list); loading shows a "Loading…" row in the popup and suppresses the "no matches" empty state, keeping the current list in place (no flicker on every keystroke).

While results are stale (the user has typed but results haven't arrived: the debounce window ∪ loading), the current list stays in place but can't be selected (options disabled + dimmed) — staying prevents layout jumps, non-selectable prevents "clicking fast and picking an item unrelated to the current query"; the creatable "create" item is hidden for the same period. When options is swapped out, the selected item keeps its label even if it's absent from the new result set — the single-select echo and multi-select chips don't go blank. The component caches labels of values that were selected (only selected ones, so it stays bounded); if a value's label changes later, the latest one wins.

Two semantics belong to you: the '' from @search only means "the search term was cleared" — resetting / restoring the initial list / not searching is your call, it does not mean "search everything"; and with remote, the creatable exact-match check only catches duplicates within the loaded page — the real dedupe guarantee lives on the server (a unique constraint).

<SwSelect v-model="mediaId" searchable remote :loading="pending" :options="mediaOptions" @search="onSearch" />

async function onSearch(term: string) {
  pending.value = true;
  mediaOptions.value = await api.media.options({ keyword: term }); // replace the result set
  pending.value = false;
}

Create-on-type (creatable, tag-picking scenario)

creatable (effective only with searchable) appends a "创建 "xxx"" (create "xxx") item at the end of the list when the input has no exact match (case-insensitive). Selecting it does not change v-model — it only emits @create (payload is the trimmed input text); the business creates the item on the backend, then pushes the new option into options + v-model itself. multiple + searchable + creatable together form the tag-input shape:

<script setup lang="ts">
async function onCreateTag(name: string) {
  const tag = await createTag(name) // business calls the backend
  tagOptions.value.push({ value: tag.id, label: tag.name })
  tagIds.value = [...tagIds.value, tag.id] // push into options + v-model
}
</script>

<template>
  <SwSelect v-model="tagIds" multiple searchable creatable :options="tagOptions" @create="onCreateTag" />
</template>

Props

SwSelectOption: { value: string \| number; label: string; disabled?: boolean; group?: string } (importable from the package: import type { SwSelectOption } from '@swift-web/framework')

Events

Slots

Styling Tokens

Brand the trigger and popup via --sw-select-* tokens (fallbacks are the default look). The popup portals to body, so override its tokens on :root (or any body ancestor) — no :global piercing needed:

Default height / font size come from the form-control semantic tokens --control-height (32px) / --control-font-size (14px) — SwInput / SwSelect / SwSegmented align to the same height out of the box; override these two tokens to scale every control site-wide (component-level tokens still take precedence).

Caveats

• The popup is teleported to body via a Portal: to change popup styles (e.g. font size), the applier must use a global / :global selector (a scoped :deep can't reach it), targeting .sw-select-content.
• No built-in visual branding: the component ships only the minimal necessary baseline styles; colors, corner radius, etc. are left to the applier to override.
• The multi-select trigger shows "已选 N 项" (N selected) by default: to render tags / chips, customize it via the #trigger slot.
• searchable filters locally by default: only a case-insensitive substring match on label; remote search must add remote to turn it off, otherwise items the server matched by alias / pinyin get hidden by the local pass. The data source is still yours (the component only hands out the @search term and takes back options).
• @create doesn't change v-model: selecting the "create" item only emits the event — the business must push the new option into options and update v-model, otherwise nothing visibly changes.
• The #trigger slot has no effect with searchable: the searchable trigger is an input (chips + input in multi-select); there's no custom-trigger slot in that shape.
• In multiple mode the v-model must be an array: initializing it as a single value (e.g. ref('')) for multi-select breaks the selected state and the "N selected" count and corrupts the type — use ref([]) for multiple, a single value for single-select.
• Groups are formed by consecutive same-name runs: options sharing a group must be adjacent; a same-named group scattered across the list renders as multiple separate group blocks — sort options by group before passing them in.

See Also

• SwSegmented · SwFormField