Select / dropdown

In review

Live · web

Placeholder vs. a value: click or press Enter / ↓ to open

RegionChoose a region…

Nothing selected yet, so the placeholder holds the empty state.

Providercloud-personal

Leading status mark · the chosen option carries a cyan check · one disabled option.

Grouped options: group labels, leading + secondary text

ModelLarge 2.0

Cloud and local engines, bucketed under headers.

Error / invalid + disabled

WorkspacePick a workspace…

A workspace is required to continue.

Locked fieldlocal

Inert, but the chosen value stays legible.

Sizes: sm and md

Thinking (sm)High

Theme (md)System

Committed 0 selections. The island is live.

Code

TypeScriptKotlinSwift

// Web: React, consuming @dizyx/nockerl-tokens. NockerlSelect ships from
// @dizyx/nockerl-react: the recessed WELL trigger + the lifted popover listbox +
// the selected-row check + the full keyboard model are all in the package.
import { useState } from 'react';
import { NockerlSelect } from '@dizyx/nockerl-react';

export function SessionConfig() {
  const [provider, setProvider] = useState<string | null>('cloud-personal');
  const [model, setModel] = useState<string | null>('large-2-0');

  return (
    <>
      <NockerlSelect
        label="Provider"
        value={provider}
        onChange={setProvider}
        placeholder="Select a provider…"
        options={[
          { value: 'cloud-personal', label: 'cloud-personal', secondary: 'Cloud Agent', status: 'success' },
          { value: 'local', label: 'local', secondary: 'Local runtime', status: 'info' },
          { value: 'openrouter', label: 'openrouter', secondary: 'Cloud · billable', status: 'warning' },
        ]}
      />
      <NockerlSelect
        label="Model"
        value={model}
        onChange={setModel}
        grouped
        options={[
          { value: 'large-2-0', label: 'Large 2.0', secondary: 'coding', group: 'Cloud' },
          { value: 'qwen3-32b', label: 'Qwen3 32B', secondary: 'local', group: 'Local' },
        ]}
      />
    </>
  );
}

// Android (Jetpack Compose, canonical). The shipped single-select dropdown is a
// DropdownAnchor (recessed control-shaped field + ArrowDropDown) over a Material3
// DropdownMenu of DropdownMenuItem rows. See chat/ui/SessionCreationDropdowns.kt.
import androidx.compose.material3.DropdownMenu
import androidx.compose.material3.DropdownMenuItem
import androidx.compose.material3.Text
import com.nockerl.app.chat.ui.DropdownAnchor

@Composable
fun ProviderDropdown(
    providers: List<ProviderInfo>,
    selectedProvider: ProviderInfo?,
    isLoading: Boolean,
    onSelect: (ProviderInfo) -> Unit,
) {
    var expanded by remember { mutableStateOf(false) }

    Box {
        DropdownAnchor(
            label = selectedProvider?.name ?: "Select a provider",
            placeholder = selectedProvider == null,
            isLoading = isLoading,
            onClick = { if (!isLoading && providers.isNotEmpty()) expanded = true },
        )
        DropdownMenu(expanded = expanded, onDismissRequest = { expanded = false }) {
            providers.forEach { provider ->
                DropdownMenuItem(
                    text = { Text(provider.name) },
                    onClick = { onSelect(provider); expanded = false },
                )
            }
        }
    }
}

// macOS: SwiftUI (canonical). The shipped single-select is a Menu of Buttons; the
// chosen row carries a leading checkmark via Label(systemImage:). The trigger is a
// chevron.up.chevron.down on a recessed accent-outlined field. See UI/AppSettingsView.swift.
Menu {
    Button { settings.selectedMicUID = "" } label: {
        micMenuLabel("System Default", selected: settings.selectedMicUID.isEmpty)
    }
    ForEach(micMonitor.devices) { mic in
        Button { settings.selectedMicUID = mic.uid } label: {
            micMenuLabel(mic.name, selected: settings.selectedMicUID == mic.uid)
        }
    }
} label: {
    HStack(spacing: 8) {
        Text(currentMicName).lineLimit(1).truncationMode(.middle)
        Spacer(minLength: 0)
        Image(systemName: "chevron.up.chevron.down")
    }
    .foregroundStyle(NockerlTheme.accent)
    .padding(.horizontal, 12).padding(.vertical, 8)
    .background(NockerlTheme.canvasAlt, in: RoundedRectangle(cornerRadius: NockerlRadius.control))
    .overlay(
        RoundedRectangle(cornerRadius: NockerlRadius.control)
            .strokeBorder(
                NockerlTheme.accent.opacity(NockerlBorderOpacity.selection),
                lineWidth: NockerlBorder.widthSelection
            )
    )
}
.menuStyle(.borderlessButton)
.menuIndicator(.hidden)

// A checkmark on the selected row; a plain Text otherwise.
@ViewBuilder
func micMenuLabel(_ name: String, selected: Bool) -> some View {
    if selected { Label(name, systemImage: "checkmark") } else { Text(name) }
}

Parameters

TypeScriptKotlinSwift

Prop	Type	Default	Description
label *	string	n/a	Persistent label above the trigger, never a placeholder.
options *	NockerlSelectOption[]	n/a	The fixed set to pick one from.
value *	string | null	n/a	The chosen value, or null for the empty/placeholder state.
onChange *	(value: string) => void	n/a	Commit a single selection (the option value), then close the popover.
placeholder	string	'Select…'	Shown when nothing is selected (label still persists above).
helperText	string	n/a	Quiet supporting line under the well.
errorText	string	n/a	When set, the field reads invalid (warm border + icon + this message).
size	NockerlSelectSize	'md'	Control height + type: 'md' (44px) | 'sm' (34px).
grouped	boolean	false	Bucket options under their group header.
disabled	boolean	false	Inert + still legible (never invisible).

The single-select is composed from DropdownAnchor (the field) + Material3 DropdownMenu / DropdownMenuItem (the list). Parameters are those of DropdownAnchor plus the menu items the caller emits.

Parameter	Type	Default	Description
label *	String	n/a	The value (or placeholder) shown in the anchor. Rendered with bodyMedium.
placeholder *	Boolean	n/a	When true, the label is rendered as muted placeholder text (nothing chosen yet).
isLoading *	Boolean	n/a	Shows an inline CircularProgressIndicator before the chevron and (by convention) gates opening.
enabled	Boolean	true	When false, the anchor is dimmed + filled (surfaceVariant) and non-clickable.
onClick *	() -> Unit	n/a	Opens the caller-owned DropdownMenu (typically sets expanded = true).
expanded / onDismissRequest	Boolean / -> Unit	n/a	On the wrapping DropdownMenu: open state + outside-dismiss.
DropdownMenuItem(text, onClick, enabled)	@Composable	n/a	One option row: a Text label; onClick selects + dismisses; enabled = false for an inert option.

SwiftUI builds the picker as a Menu whose label is the trigger and whose content is a Button per option. What this tab documents is that idiom rather than a wrapper type: the rows below are the load-bearing modifiers plus the per-row selection pattern.

Style	Type	Default	Description
Menu { content } label: { trigger }	View	n/a	The select. content is the option Buttons; label is the field (value text + chevron.up.chevron.down).
.menuStyle(.borderlessButton)	MenuStyle	n/a	Renders the trigger as a flat field, not a bordered system button.
.menuIndicator(.hidden)	View modifier	n/a	Hides the default disclosure chevron so the custom one is the only indicator.
Button { select } label: { Label(name, systemImage: "checkmark") }	View	n/a	One option. The SELECTED row uses Label(_, systemImage: "checkmark"); others are a plain Text.
.foregroundStyle(NockerlTheme.accent) + RoundedRectangle(cornerRadius: NockerlRadius.control)	View modifiers	n/a	The recessed accent-outlined field look: an accent label plus a border drawn at NockerlBorder.widthSelection and softened to NockerlBorderOpacity.selection. Both shapes consume the radius token, never a literal (law §11).

Pick the right picker

Select is the plainest picker: one value from a fixed list, no typing. Reach for a neighbour when you need more: Combobox when the user should type to filter a long list (autocomplete); Multi-select when they pick several values (token chips, per-row checkboxes, select-all); Menu when the rows are actions, not a value (icons, shortcuts, submenus).

Cross-platform drift (tracked for reconciliation)

The spec is in review; these are the real divergences between the shipped platforms:

• Selected-row check (settled): a trailing check on the selected row is the shared expression. The web package stamps it and the Swift idiom here uses Label(_, systemImage: "checkmark"); the Compose idiom documented on this page reads the selection in the anchor only, so a trailing check on DropdownMenuItem is the piece this page specifies.
• Control radius: the field is the radius.control token everywhere, reached through NockerlControlShape on Compose and NockerlRadius.control in SwiftUI. A literal corner radius on a picker is a law §11 violation rather than a platform difference.
• Grouping + secondary text: web supports group headers and a secondary line per option. The Android and Swift idioms documented here are flat label-only rows, so grouping and the secondary line are specified on this page rather than mirrored from an app.
• Sizing: web has size (sm/md); Compose’s anchor is fixed at 48dp; Swift is intrinsic.
• Error state: web has a first-class errorText (warm border + icon + message); the apps surface validation outside the control today.