Settings Element Reference - Linktree LinkApp SDK

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

Getting Started

Essentials

​Overview

​Quick Reference

​Common Properties

​Example

​Element Categories

​Text Inputs

Text & Textarea

URL Input

Number Input

View All Text Inputs →

​Selection Controls

Select Dropdown

Radio Buttons

Checkboxes

View All Selection Controls →

​Toggles & Switches

Switch Toggle

Link Behavior

View All Toggles →

​Advanced Elements

Array Lists

Integrations

Conditional Display

View All Advanced Elements →

​Validation

​Validation Rules Reference

​Array Validation Example

​File Validation Example

Validation Examples

​Type Safety

​Best Practices

​Use Descriptive IDs

​Provide Default Values

​Add Help Text

​Choose Appropriate Types

​Complete Example

​Explore Element Types

Text Inputs

Selection Controls

Toggles

Advanced Elements

​Next Steps

Configuration

Layouts

Examples

Overview

Quick Reference

Common Properties

Example

Element Categories

Text Inputs

Selection Controls

Toggles & Switches

Advanced Elements

Validation

Validation Rules Reference

Array Validation Example

File Validation Example

Type Safety

Best Practices

Use Descriptive IDs

Provide Default Values

Add Help Text

Choose Appropriate Types

Complete Example

Explore Element Types

Next Steps