> ## 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.

# 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.

```ts linkapp.config.ts theme={"system"}
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:

```tsx app/expanded.tsx theme={"system"}
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       | [→](/essentials/settings/text-inputs#text)      |
| `textarea`     | Multi-line text input     | Descriptions, long text         | [→](/essentials/settings/text-inputs#textarea)  |
| `url`          | URL input with validation | Website links                   | [→](/essentials/settings/text-inputs#url)       |
| `number`       | Number input              | Counts, limits, quantities      | [→](/essentials/settings/text-inputs#number)    |
| `select`       | Dropdown menu             | Predefined choices (3+ options) | [→](/essentials/settings/selections#select)     |
| `radio`        | Radio button group        | Exclusive choices (2-5 options) | [→](/essentials/settings/selections#radio)      |
| `checkbox`     | Checkbox input            | Multiple selections, acceptance | [→](/essentials/settings/selections#checkbox)   |
| `switch`       | Boolean toggle            | Enable/disable features         | [→](/essentials/settings/toggles#switch)        |
| `linkBehavior` | Linktree link behavior    | Embed vs. direct link           | [→](/essentials/settings/toggles#link-behavior) |
| `location`     | Google Places picker      | Addresses, venues, stores       | [→](/essentials/settings/location)              |
| `array`        | Dynamic list of items     | Collections, lists              | [→](/essentials/settings/advanced#array)        |
| `integration`  | Third-party integration   | Email marketing, etc.           | [→](/essentials/settings/advanced#integration)  |
| `file`         | File upload               | Images, documents               | [→](/essentials/settings/advanced#file-upload)  |
| `button`       | Action button             | Trigger actions                 | [→](/essentials/settings/advanced#button)       |

## 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

```ts theme={"system"}
{
  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.

<CardGroup cols={2}>
  <Card title="Text & Textarea" icon="keyboard" href="/essentials/settings/text-inputs#text">
    Single-line and multi-line text inputs
  </Card>

  <Card title="URL Input" icon="link" href="/essentials/settings/text-inputs#url">
    Validated URL inputs for website links
  </Card>

  <Card title="Number Input" icon="hashtag" href="/essentials/settings/text-inputs#number">
    Numeric values with min/max validation
  </Card>

  <Card title="View All Text Inputs →" icon="arrow-right" href="/essentials/settings/text-inputs">
    See detailed documentation
  </Card>
</CardGroup>

### Selection Controls

Dropdowns, radio buttons, and checkboxes for choosing options.

<CardGroup cols={2}>
  <Card title="Select Dropdown" icon="caret-down" href="/essentials/settings/selections#select">
    Choose one from many options
  </Card>

  <Card title="Radio Buttons" icon="circle-dot" href="/essentials/settings/selections#radio">
    Visual option selection (2-5 choices)
  </Card>

  <Card title="Checkboxes" icon="check-square" href="/essentials/settings/selections#checkbox">
    Single or multiple selections
  </Card>

  <Card title="View All Selection Controls →" icon="arrow-right" href="/essentials/settings/selections">
    See detailed documentation
  </Card>
</CardGroup>

### Toggles & Switches

Boolean controls for on/off states.

<CardGroup cols={2}>
  <Card title="Switch Toggle" icon="toggle-on" href="/essentials/settings/toggles#switch">
    Enable/disable features
  </Card>

  <Card title="Link Behavior" icon="link" href="/essentials/settings/toggles#link-behavior">
    Control how links open (Linktree-specific)
  </Card>

  <Card title="View All Toggles →" icon="arrow-right" href="/essentials/settings/toggles">
    See detailed documentation
  </Card>
</CardGroup>

### Advanced Elements

Complex inputs for lists, integrations, and conditional logic.

<CardGroup cols={2}>
  <Card title="Array Lists" icon="list" href="/essentials/settings/advanced#array">
    Dynamic lists of structured items
  </Card>

  <Card title="Integrations" icon="plug" href="/essentials/settings/advanced#integration">
    Connect third-party services
  </Card>

  <Card title="Conditional Display" icon="eye" href="/essentials/settings/advanced#conditional-display">
    Show/hide elements based on values
  </Card>

  <Card title="View All Advanced Elements →" icon="arrow-right" href="/essentials/settings/advanced">
    See detailed documentation
  </Card>
</CardGroup>

## Validation

Add validation rules to ensure correct input:

```ts theme={"system"}
{
  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                     |

<Note>
  **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.
</Note>

### Array Validation Example

```ts theme={"system"}
{
  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

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

<Card title="Validation Examples" icon="shield" href="/essentials/settings/advanced#validation">
  See validation examples for each element type
</Card>

## Type Safety

Define settings types for full TypeScript support:

```ts theme={"system"}
// 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>
}
```

<Tip>
  TypeScript will autocomplete prop names and catch type errors during
  development!
</Tip>

## Best Practices

### Use Descriptive IDs

```ts theme={"system"}
// ✅ Good - clear, descriptive
{
  id: "showTitle";
}
{
  id: "backgroundColor";
}

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

### Provide Default Values

```ts theme={"system"}
{
  id: "itemCount",
  defaultValue: 10  // Sensible default
}
```

### Add Help Text

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

### Choose Appropriate Types

```ts theme={"system"}
// ✅ 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:

```ts linkapp.config.ts theme={"system"}
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

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

  <Card title="Selection Controls" icon="list-check" href="/essentials/settings/selections">
    Select, radio, and checkbox elements
  </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>
</CardGroup>

## Next Steps

<CardGroup cols={3}>
  <Card title="Configuration" icon="gear" href="/essentials/configuration/settings">
    Learn about settings structure
  </Card>

  <Card title="Layouts" icon="layer-group" href="/essentials/layouts">
    Use settings in your layouts
  </Card>

  <Card title="Examples" icon="code" href="/essentials/settings/advanced#complete-examples">
    See real-world examples
  </Card>
</CardGroup>