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

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