Settings Element Reference

Complete reference for all LinkApp settings element types

Overview

Settings elements define the form fields shown to users when they configure your LinkApp. Each element type provides different input options—from simple text boxes to complex arrays.

linkapp.config.ts

export default {
  settings: {
    elements: [
      {
        id: "username", // Becomes prop name
        inputType: "text", // Element type
        title: "Username", // Field title
        defaultValue: "", // Initial value
      },
    ],
  },
};

The id property becomes a prop in your layout component:

app/expanded.tsx

type Settings = { username: string };

export default function ClassicLayout({ username }: AppProps<Settings>) {
  return <div>Hello, {username}!</div>;
}

Quick Reference

Element Type	Description	Use Case	Details
text	Single-line text input	Names, titles, short text	→
textarea	Multi-line text input	Descriptions, long text	→
url	URL input with validation	Website links	→
number	Number input	Counts, limits, quantities	→
select	Dropdown menu	Predefined choices (3+ options)	→
radio	Radio button group	Exclusive choices (2-5 options)	→
checkbox	Checkbox input	Multiple selections, acceptance	→
switch	Boolean toggle	Enable/disable features	→
linkBehavior	Linktree link behavior	Embed vs. direct link	→
location	Google Places picker	Addresses, venues, stores	→
array	Dynamic list of items	Collections, lists	→
integration	Third-party integration	Email marketing, etc.	→
file	File upload	Images, documents	→
button	Action button	Trigger actions	→

Common Properties

All element types share these base properties:

Property	Type	Required	Description
id	string	Yes	Unique identifier (becomes prop name)
inputType	string	Yes	Element type from the table above
title	string	No	Field title displayed above input
description	string	No	Help text explaining the field
defaultValue	any	No	Initial value (type depends on inputType)
validation	object	No	Validation rules (required, min, max, etc.)
conditionalDisplay	object	No	Show/hide based on other elements

Example

{
  id: "apiKey",
  inputType: "text",
  title: "API Key",
  description: "Get your API key from example.com/settings",
  placeholder: "Enter your API key",
  defaultValue: "",
  validation: {
    required: true,
    minLength: 20
  }
}

Element Categories

Text Inputs

Simple and multi-line text entry fields.

Text & Textarea

Single-line and multi-line text inputs

URL Input

Validated URL inputs for website links

Number Input

Numeric values with min/max validation

View All Text Inputs →

See detailed documentation

Selection Controls

Dropdowns, radio buttons, and checkboxes for choosing options.

Select Dropdown

Choose one from many options

Radio Buttons

Visual option selection (2-5 choices)

Checkboxes

Single or multiple selections

View All Selection Controls →

See detailed documentation

Toggles & Switches

Boolean controls for on/off states.

Switch Toggle

Enable/disable features

Link Behavior

Control how links open (Linktree-specific)

View All Toggles →

See detailed documentation

Advanced Elements

Complex inputs for lists, integrations, and conditional logic.

Array Lists

Dynamic lists of structured items

Integrations

Connect third-party services

Conditional Display

Show/hide elements based on values

View All Advanced Elements →

See detailed documentation

Validation

Add validation rules to ensure correct input:

{
  id: "email",
  inputType: "text",
  validation: {
    required: true,              // Must not be empty
    pattern: "^[^@]+@[^@]+$",   // Must match regex
    minLength: 5,                // Minimum characters
    maxLength: 100               // Maximum characters (shows real-time counter)
  }
}

Validation Rules Reference

Rule	Applies To	Description
required	All types	Field must not be empty
minLength	Text, textarea, url	Minimum character count
maxLength	Text, textarea, url	Maximum character count (enables char counter)
pattern	Text, url	Regular expression match
min	Number	Minimum numeric value
max	Number	Maximum numeric value
minItems	Array	Minimum number of array items
maxItems	Array	Maximum number of array items
maxFileSize	File	Maximum file size in bytes

Character Counter: When you set maxLength on a text field, the Linktree editor automatically shows a real-time character counter (e.g., “45/100 characters”) as users type.

Array Validation Example

{
  id: "testimonials",
  inputType: "array",
  validation: {
    minItems: 1,    // At least 1 item required
    maxItems: 10    // Maximum 10 items allowed
  },
  array_options: {
    add_item_button_text: "Add testimonial",
    item_format: "{{name}} - {{title}}"
  },
  array_elements: [
    { id: "name", inputType: "text", title: "Name" },
    { id: "title", inputType: "text", title: "Title" }
  ]
}

File Validation Example

{
  id: "coverImage",
  inputType: "file",
  title: "Cover Image",
  accept: ["image/jpeg", "image/png"],
  validation: {
    required: true,
    maxFileSize: 5242880  // 5MB in bytes
  }
}

Validation Examples

See validation examples for each element type

Type Safety

Define settings types for full TypeScript support:

// Define settings type matching your config
type MyLinkAppSettings = {
  showTitle: boolean      // switch element
  username: string        // text element
  theme: 'light' | 'dark' // select element
  itemCount: number       // number element
}

// Use in layout with full type safety
export default function ClassicLayout({
  showTitle,
  username,
  theme,
  itemCount
}: AppProps<MyLinkAppSettings>) {
  // TypeScript knows all prop types ✨
  return <div>...</div>
}

TypeScript will autocomplete prop names and catch type errors during development!

Best Practices

Use Descriptive IDs

// ✅ Good - clear, descriptive
{
  id: "showTitle";
}
{
  id: "backgroundColor";
}

// ❌ Avoid - abbreviations, unclear
{
  id: "st";
}
{
  id: "bgClr";
}

Provide Default Values

{
  id: "itemCount",
  defaultValue: 10  // Sensible default
}

Add Help Text

{
  id: "apiKey",
  description: "Get your API key from https://example.com/settings/api"
}

Choose Appropriate Types

// ✅ Good - validates URL format
{ id: "website", inputType: "url" }

// ❌ Less good - allows any text
{ id: "website", inputType: "text" }

Complete Example

Here’s a real-world example for a weather LinkApp:

linkapp.config.ts

export default {
  settings: {
    title: "Weather",
    elements: [
      {
        id: "location",
        inputType: "text",
        title: "Location",
        description: "City name for weather data",
        label: "City",
        defaultValue: "San Francisco",
        validation: { required: true },
      },
      {
        id: "units",
        inputType: "select",
        title: "Temperature Units",
        label: "Units",
        defaultValue: "celsius",
        options: [
          { label: "Celsius (°C)", value: "celsius" },
          { label: "Fahrenheit (°F)", value: "fahrenheit" },
        ],
      },
      {
        id: "showForecast",
        inputType: "switch",
        title: "Display Options",
        label: "Show 5-day forecast",
        defaultValue: true,
      },
    ],
  },
};

Explore Element Types

Text Inputs

Text, textarea, URL, and number inputs

Selection Controls

Select, radio, and checkbox elements

Toggles

Switch and link behavior elements

Advanced Elements

Arrays, integrations, and conditional display

Next Steps

Configuration

Learn about settings structure

Layouts

Use settings in your layouts

Examples

See real-world examples