Fumadocs on TanStack Start

A simplified select component wrapper for common use cases with automatic label detection and type-safe selection

Overview

SelectField is a simplified wrapper around the Select component that streamlines common use cases. It handles item rendering, label detection, and key generation automatically while maintaining full type safety. For more complex scenarios requiring custom sub-component composition, use the full Select component from @px-ui/core.

Import

import { SelectField } from "@px-ui/forms";

Usage

import { SelectField } from "@px-ui/forms";
import { useState } from "react";

export default function Example() {
  const [value, setValue] = useState<string | null>(null);

  const items = [
    { id: "apple", label: "Apple" },
    { id: "banana", label: "Banana" },
    { id: "orange", label: "Orange" },
    { id: "mango", label: "Mango" },
    { id: "grape", label: "Grape" },
  ];

  return (
    <SelectField
      items={items}
      value={value}
      onValueChange={setValue}
      placeholder="Select a fruit"
    />
  );
}

Examples

Multiple Selection

Enable multiple item selection with the multiple prop.

import { SelectField } from "@px-ui/forms";
import { useState } from "react";

export default function Example() {
  const [value, setValue] = useState<string[]>([]);

  const items = [
    { id: "react", label: "React" },
    { id: "vue", label: "Vue" },
    { id: "angular", label: "Angular" },
    { id: "svelte", label: "Svelte" },
    { id: "solid", label: "Solid" },
  ];

  return (
    <SelectField
      items={items}
      value={value}
      onValueChange={setValue}
      multiple
      placeholder="Select frameworks"
    />
  );
}

Sizes

Control the size of the select field using the size prop.

import { SelectField } from "@px-ui/forms";
import { useState } from "react";

export default function Example() {
  const [value, setValue] = useState<string | null>(null);

  const items = [
    { id: "sm", label: "Small" },
    { id: "md", label: "Medium" },
    { id: "lg", label: "Large" },
  ];

  return (
    <div className="flex flex-col gap-4">
      <SelectField
        items={items}
        value={value}
        onValueChange={setValue}
        placeholder="Small size"
        size="sm"
      />
      <SelectField
        items={items}
        value={value}
        onValueChange={setValue}
        placeholder="Medium size (default)"
        size="md"
      />
      <SelectField
        items={items}
        value={value}
        onValueChange={setValue}
        placeholder="Large size"
        size="lg"
      />
    </div>
  );
}

Custom Rendering

Use renderLabel and renderOption to customize how items are displayed. If not provided, SelectField automatically uses the label property from items.

import { SelectField } from "@px-ui/forms";
import { useState } from "react";

interface User {
  id: number;
  name: string;
  email: string;
  role: string;
}

export default function Example() {
  const [value, setValue] = useState<User | null>(null);

  const users: User[] = [
    { id: 1, name: "John Doe", email: "john@example.com", role: "Admin" },
    { id: 2, name: "Jane Smith", email: "jane@example.com", role: "Editor" },
    { id: 3, name: "Bob Johnson", email: "bob@example.com", role: "Viewer" },
    { id: 4, name: "Alice Brown", email: "alice@example.com", role: "Editor" },
  ];

  return (
    <SelectField
      items={users}
      value={value}
      onValueChange={setValue}
      placeholder="Select a user"
      renderLabel={(user) => user.name}
      renderOption={(user) => (
        <div className="flex flex-col">
          <span className="font-medium">{user.name}</span>
          <span className="text-sm text-gray-11">{user.email}</span>
        </div>
      )}
    />
  );
}

Prop	Type	Default	Description
`items` *	`ReadonlyArray<TItem>`	-	Array of items to display in the select dropdown
`renderLabel`	`(item: TItem) => React.ReactNode`	-	Function to render the label in the trigger for the selected item. If not provided and item has a `label` property, it will be used automatically
`renderOption`	`(item: TItem) => React.ReactNode`	-	Function to render each option in the dropdown. If not provided and item has a `label` property, it will be used automatically
`placeholder`	`string`	-	Placeholder text when no value is selected
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Size variant for the select trigger
`widthVariant`	`'sm' \| 'md' \| 'lg' \| 'full'`	`'full'`	Width variant for the select trigger
`contentWidthVariant`	`'trigger' \| 'full'`	`'trigger'`	Width variant for the dropdown content
`triggerClassName`	`string`	-	Additional CSS classes for the trigger element
`contentProps`	`Omit<React.ComponentProps<typeof Select.Content>, 'children' \| 'widthVariant'>`	-	Additional props for Select.Content component

Inherited Props from Select.Root

Prop	Type	Default	Description
`value` *	`TItem \| TItem[] \| null`	-	The current selected value(s)
`onValueChange` *	`(value: TItem \| TItem[] \| null) => void`	-	Callback fired when the selected value changes
`multiple`	`boolean`	`false`	Whether multiple items can be selected
`disabled`	`boolean`	`false`	Whether the select is disabled
`invalid`	`boolean`	`false`	Whether the select is in an invalid state
`readOnly`	`boolean`	`false`	Whether the select is read-only
`name`	`string`	-	Name attribute for form submission
`isItemEqualToValue`	`(item: TItem, value: TItem) => boolean`	-	Custom equality function to compare items. By default, uses strict equality
`inputRef`	`React.Ref<HTMLInputElement>`	-	Ref to the hidden input element used for form submission

* Required prop

Notes

SelectField automatically detects label, id, or value properties from items for key generation and display
For complex layouts or custom sub-component composition, use the full Select component from @px-ui/core
The component is fully type-safe and infers the item type from the items array
When using multiple selection, selected items are displayed as chips with a configurable max items (default: 2)

Select Field

Overview

Import

Usage

Examples

Multiple Selection

Sizes

Custom Rendering

API Reference

SelectField

Custom Props

Inherited Props from Select.Root

Notes

On this page