> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linktr.ee/llms.txt
> Use this file to discover all available pages before exploring further.

# Selection Elements

> Select, radio, and checkbox elements for choosing options

## Overview

Selection elements let users choose from predefined options. Pick the right element based on how many options you have and whether users can select one or multiple items.

| Element    | Options | Selection          | Best For                                |
| ---------- | ------- | ------------------ | --------------------------------------- |
| `select`   | 3+      | Single             | Many options, dropdown UI               |
| `radio`    | 2-5     | Single             | Few options, visible comparison         |
| `checkbox` | 1+      | Single or multiple | Multiple selections or terms acceptance |

## Select Dropdown

Dropdown menu for choosing one option from a list. Best when you have many options (3+).

### Properties

| Property       | Type               | Description                           |
| -------------- | ------------------ | ------------------------------------- |
| `id`           | `string`           | Unique identifier (becomes prop name) |
| `inputType`    | `'select'`         | Must be `'select'`                    |
| `title`        | `string`           | Field title                           |
| `description`  | `string`           | Help text                             |
| `label`        | `string`           | Input label                           |
| `defaultValue` | `string \| number` | Initial selected value                |
| `options`      | `array`            | Array of `{ label, value }` objects   |
| `validation`   | `object`           | Validation rules                      |

### Options Format

```ts theme={"system"}
options: [
  { label: "Display text shown to user", value: "value-sent-to-layout" },
  { label: "Light Mode", value: "light" },
  { label: "Dark Mode", value: "dark" },
];
```

### Validation

| Rule       | Type      | Description              |
| ---------- | --------- | ------------------------ |
| `required` | `boolean` | A value must be selected |

### Example

```ts linkapp.config.ts theme={"system"}
{
  id: "theme",
  inputType: "select",
  title: "Theme",
  description: "Choose a color theme",
  label: "Color theme",
  defaultValue: "light",
  options: [
    { label: "Light Mode", value: "light" },
    { label: "Dark Mode", value: "dark" },
    { label: "Auto (System)", value: "auto" }
  ],
  validation: {
    required: true
  }
}
```

### Usage in Layout

```tsx app/expanded.tsx theme={"system"}
type Settings = {
  theme: "light" | "dark" | "auto";
};

export default function ClassicLayout({ theme }: AppProps<Settings>) {
  const isDark =
    theme === "dark" ||
    (theme === "auto" &&
      window.matchMedia("(prefers-color-scheme: dark)").matches);

  return <div className={isDark ? "dark-theme" : "light-theme"}>Content</div>;
}
```

### Common Patterns

**Theme selector:**

```ts theme={"system"}
{
  id: "colorScheme",
  inputType: "select",
  title: "Color Scheme",
  label: "Theme",
  defaultValue: "auto",
  options: [
    { label: "Light", value: "light" },
    { label: "Dark", value: "dark" },
    { label: "Auto", value: "auto" }
  ]
}
```

**Category/type selector:**

```ts theme={"system"}
{
  id: "contentType",
  inputType: "select",
  title: "Content Type",
  label: "Type",
  defaultValue: "article",
  options: [
    { label: "Article", value: "article" },
    { label: "Video", value: "video" },
    { label: "Gallery", value: "gallery" },
    { label: "Product", value: "product" }
  ],
  validation: { required: true }
}
```

**Language selector:**

```ts theme={"system"}
{
  id: "language",
  inputType: "select",
  title: "Language",
  label: "Display language",
  defaultValue: "en",
  options: [
    { label: "English", value: "en" },
    { label: "Spanish", value: "es" },
    { label: "French", value: "fr" },
    { label: "German", value: "de" }
  ]
}
```

**Units/format:**

```ts theme={"system"}
{
  id: "dateFormat",
  inputType: "select",
  title: "Date Format",
  label: "Format",
  defaultValue: "mdy",
  options: [
    { label: "MM/DD/YYYY", value: "mdy" },
    { label: "DD/MM/YYYY", value: "dmy" },
    { label: "YYYY-MM-DD", value: "ymd" }
  ]
}
```

<Tip>
  Use `select` when you have 3+ options. For 2-5 options, consider `radio` for
  better visual comparison.
</Tip>

## Radio Buttons

Radio button group for choosing one option. Best for 2-5 options where users benefit from seeing all choices at once.

### Properties

| Property       | Type      | Description                         |
| -------------- | --------- | ----------------------------------- |
| `id`           | `string`  | Unique identifier                   |
| `inputType`    | `'radio'` | Must be `'radio'`                   |
| `title`        | `string`  | Field title                         |
| `description`  | `string`  | Help text                           |
| `options`      | `array`   | Array of `{ label, value }` objects |
| `defaultValue` | `string`  | Initial selected value              |
| `validation`   | `object`  | Validation rules                    |

### Validation

| Rule       | Type      | Description              |
| ---------- | --------- | ------------------------ |
| `required` | `boolean` | A value must be selected |

### Example

```ts linkapp.config.ts theme={"system"}
{
  id: "displayMode",
  inputType: "radio",
  title: "Display Mode",
  description: "Choose how to display content",
  options: [
    { label: "List View", value: "list" },
    { label: "Grid View", value: "grid" },
    { label: "Compact", value: "compact" }
  ],
  defaultValue: "list",
  validation: {
    required: true
  }
}
```

### Usage in Layout

```tsx app/expanded.tsx theme={"system"}
type Settings = {
  displayMode: "list" | "grid" | "compact";
};

export default function ClassicLayout({ displayMode }: AppProps<Settings>) {
  return (
    <div className={`display-${displayMode}`}>
      {displayMode === "grid" ? <GridView /> : <ListView />}
    </div>
  );
}
```

### Common Patterns

**Layout choice:**

```ts theme={"system"}
{
  id: "layout",
  inputType: "radio",
  title: "Layout Style",
  options: [
    { label: "Single Column", value: "single" },
    { label: "Two Columns", value: "two" },
    { label: "Three Columns", value: "three" }
  ],
  defaultValue: "single"
}
```

**Size selector:**

```ts theme={"system"}
{
  id: "size",
  inputType: "radio",
  title: "LinkApp Size",
  options: [
    { label: "Small", value: "sm" },
    { label: "Medium", value: "md" },
    { label: "Large", value: "lg" }
  ],
  defaultValue: "md"
}
```

**Alignment:**

```ts theme={"system"}
{
  id: "alignment",
  inputType: "radio",
  title: "Text Alignment",
  options: [
    { label: "Left", value: "left" },
    { label: "Center", value: "center" },
    { label: "Right", value: "right" }
  ],
  defaultValue: "left"
}
```

<Note>
  Radio buttons show all options at once, making them perfect for choices users
  need to compare visually. Use `select` if you have more than 5 options.
</Note>

## Checkbox

Checkbox input for single acceptance (like terms) or multiple selections.

### Properties

| Property       | Type                 | Description                         |
| -------------- | -------------------- | ----------------------------------- |
| `id`           | `string`             | Unique identifier                   |
| `inputType`    | `'checkbox'`         | Must be `'checkbox'`                |
| `title`        | `string`             | Field title                         |
| `description`  | `string`             | Help text                           |
| `label`        | `string`             | Label for checkbox/group            |
| `options`      | `array`              | Array of `{ label, value }` objects |
| `defaultValue` | `string \| string[]` | Initial selected value(s)           |
| `validation`   | `object`             | Validation rules                    |

### Validation

| Rule       | Type      | Description                  |
| ---------- | --------- | ---------------------------- |
| `required` | `boolean` | At least one must be checked |

<Note>
  * **Single checkbox**: Provide 1 option (returns array with 1 item or empty
    array) - **Multiple checkboxes**: Provide 2+ options (returns array of
    selected values)
</Note>

### Example: Single Checkbox

For terms acceptance or single on/off choice:

```ts linkapp.config.ts theme={"system"}
{
  id: "termsAccepted",
  inputType: "checkbox",
  title: "Terms and Conditions",
  description: "You must accept to continue",
  options: [
    { label: "I agree to the terms and conditions", value: "accepted" }
  ],
  validation: {
    required: true
  }
}
```

**Usage:**

```tsx app/expanded.tsx theme={"system"}
type Settings = {
  termsAccepted: string[]; // ['accepted'] or []
};

export default function ClassicLayout({ termsAccepted }: AppProps<Settings>) {
  const hasAccepted = termsAccepted.includes("accepted");

  if (!hasAccepted) {
    return <div>Please accept terms to continue</div>;
  }

  return <div>Welcome!</div>;
}
```

### Example: Multiple Checkboxes

For selecting multiple options:

```ts linkapp.config.ts theme={"system"}
{
  id: "features",
  inputType: "checkbox",
  title: "Features",
  description: "Select features to enable",
  label: "Enabled features",
  defaultValue: ["notifications"],
  options: [
    { label: "Email Notifications", value: "notifications" },
    { label: "Dark Mode", value: "darkMode" },
    { label: "Analytics", value: "analytics" },
    { label: "Beta Features", value: "beta" }
  ]
}
```

**Usage:**

```tsx app/expanded.tsx theme={"system"}
type Settings = {
  features: string[]; // e.g., ['notifications', 'analytics']
};

export default function ClassicLayout({ features }: AppProps<Settings>) {
  const hasNotifications = features.includes("notifications");
  const hasDarkMode = features.includes("darkMode");
  const hasAnalytics = features.includes("analytics");

  return (
    <div className={hasDarkMode ? "dark" : "light"}>
      {hasNotifications && <NotificationBell />}
      {hasAnalytics && <Analytics />}
    </div>
  );
}
```

### Common Patterns

**Terms acceptance:**

```ts theme={"system"}
{
  id: "terms",
  inputType: "checkbox",
  title: "Agreement",
  options: [
    { label: "I agree to the Terms of Service", value: "tos" }
  ],
  validation: { required: true }
}
```

**Optional features:**

```ts theme={"system"}
{
  id: "optionalFeatures",
  inputType: "checkbox",
  title: "Optional Features",
  description: "Choose which features to enable",
  defaultValue: [],
  options: [
    { label: "Show timestamps", value: "timestamps" },
    { label: "Enable comments", value: "comments" },
    { label: "Display author info", value: "authorInfo" }
  ]
}
```

**Content filters:**

```ts theme={"system"}
{
  id: "contentTypes",
  inputType: "checkbox",
  title: "Content Types",
  description: "Select types to display",
  defaultValue: ["articles", "videos"],
  options: [
    { label: "Articles", value: "articles" },
    { label: "Videos", value: "videos" },
    { label: "Podcasts", value: "podcasts" },
    { label: "Images", value: "images" }
  ],
  validation: { required: true }  // At least one must be selected
}
```

## Comparison

Choose the right selection element:

| Scenario                                           | Use                         |
| -------------------------------------------------- | --------------------------- |
| 10+ options, select one                            | `select` dropdown           |
| 3-5 options, select one, visual comparison helpful | `radio` buttons             |
| 2 options, select one                              | `radio` buttons or `switch` |
| Select multiple from a list                        | `checkbox` (multiple)       |
| Accept terms/agreement                             | `checkbox` (single)         |

## Complete Example

Here's a product display configurator using all selection types:

```ts linkapp.config.ts theme={"system"}
export default {
  settings: {
    title: "Product Display",
    elements: [
      // Select: Many options
      {
        id: "category",
        inputType: "select",
        title: "Product Category",
        label: "Category",
        defaultValue: "all",
        options: [
          { label: "All Products", value: "all" },
          { label: "Electronics", value: "electronics" },
          { label: "Clothing", value: "clothing" },
          { label: "Books", value: "books" },
          { label: "Home & Garden", value: "home" },
          { label: "Sports", value: "sports" },
        ],
        validation: { required: true },
      },

      // Radio: Few options, visual comparison
      {
        id: "layout",
        inputType: "radio",
        title: "Display Layout",
        options: [
          { label: "Grid (3 columns)", value: "grid" },
          { label: "List (full width)", value: "list" },
          { label: "Carousel", value: "carousel" },
        ],
        defaultValue: "grid",
      },

      // Checkbox: Multiple selections
      {
        id: "displayOptions",
        inputType: "checkbox",
        title: "Display Options",
        description: "Choose what to show for each product",
        defaultValue: ["price", "rating"],
        options: [
          { label: "Show price", value: "price" },
          { label: "Show rating", value: "rating" },
          { label: "Show reviews count", value: "reviews" },
          { label: "Show availability", value: "availability" },
        ],
      },
    ],
  },
};
```

## Type Safety

Define exact types for your selections:

```ts theme={"system"}
type ProductSettings = {
  category: 'all' | 'electronics' | 'clothing' | 'books' | 'home' | 'sports'
  layout: 'grid' | 'list' | 'carousel'
  displayOptions: string[]  // ['price', 'rating', 'reviews', 'availability']
}

export default function ClassicLayout({
  category,
  layout,
  displayOptions
}: AppProps<ProductSettings>) {
  // TypeScript knows exact types ✨
  const showPrice = displayOptions.includes('price')

  return <ProductGrid category={category} layout={layout} showPrice={showPrice} />
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Text Inputs" icon="keyboard" href="/essentials/settings/text-inputs">
    Text, textarea, URL, and number inputs
  </Card>

  <Card title="Toggles" icon="toggle-on" href="/essentials/settings/toggles">
    Switch and link behavior elements
  </Card>

  <Card title="Advanced Elements" icon="layer-group" href="/essentials/settings/advanced">
    Arrays, integrations, and conditional display
  </Card>

  <Card title="Back to Reference" icon="arrow-left" href="/essentials/settings-reference">
    Return to settings reference overview
  </Card>
</CardGroup>