Selection Elements

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

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

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

linkapp.config.ts

{
  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

app/expanded.tsx

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:

{
  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:

{
  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:

{
  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:

{
  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" }
  ]
}

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

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

linkapp.config.ts

{
  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

app/expanded.tsx

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:

{
  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:

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

Alignment:

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

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.

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

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

Example: Single Checkbox

For terms acceptance or single on/off choice:

linkapp.config.ts

{
  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:

app/expanded.tsx

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:

linkapp.config.ts

{
  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:

app/expanded.tsx

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:

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

Optional features:

{
  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:

{
  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:

linkapp.config.ts

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:

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

Text Inputs

Text, textarea, URL, and number inputs

Toggles

Switch and link behavior elements

Advanced Elements

Arrays, integrations, and conditional display

Back to Reference

Return to settings reference overview

Getting Started

Essentials

Overview

Properties

Options Format

Validation

Example

Usage in Layout

Common Patterns

Radio Buttons

Properties

Validation

Example

Usage in Layout

Common Patterns

Checkbox

Properties

Validation

Example: Single Checkbox

Example: Multiple Checkboxes

Common Patterns

Comparison

Complete Example

Type Safety

Next Steps

Text Inputs

Toggles

Advanced Elements

Back to Reference

Getting Started

Essentials

​Overview

​Select Dropdown

​Properties

​Options Format

​Validation

​Example

​Usage in Layout

​Common Patterns

​Radio Buttons

​Properties

​Validation

​Example

​Usage in Layout

​Common Patterns

​Checkbox

​Properties

​Validation

​Example: Single Checkbox

​Example: Multiple Checkboxes

​Common Patterns

​Comparison

​Complete Example

​Type Safety

​Next Steps

Text Inputs

Toggles

Advanced Elements

Back to Reference

Overview

Select Dropdown

Properties

Options Format

Validation

Example

Usage in Layout

Common Patterns

Radio Buttons

Properties

Validation

Example

Usage in Layout

Common Patterns

Checkbox

Properties

Validation

Example: Single Checkbox

Example: Multiple Checkboxes

Common Patterns

Comparison

Complete Example

Type Safety

Next Steps