Advanced Elements - Linktree LinkApp SDK

Overview

Advanced elements provide complex functionality like dynamic lists, third-party integrations, and conditional forms. These elements unlock powerful features for sophisticated LinkApps.

Element	Use Case
`array`	Dynamic lists of structured items (FAQs, links, products)
`integration`	Connect third-party services (email marketing, etc.)
`conditionalDisplay`	Show/hide elements based on other values
`file`	Upload images or documents
`embedOption`	Configure embedded content display
`button`	Trigger actions or workflows

Array

Dynamic array of structured inputs for collecting lists of items. Perfect for FAQs, social links, product lists, or any repeating data.

Properties

Property	Type	Description
`id`	`string`	Unique identifier (becomes prop name)
`inputType`	`'array'`	Must be `'array'`
`title`	`string`	Field title
`description`	`string`	Help text
`label`	`string`	Label for the array
`defaultValue`	`array`	Initial array values
`array_options`	`object`	Array UI configuration
`array_elements`	`array`	Element definitions for each item
`validation`	`object`	Validation rules

Array Options

Configure the array UI in the admin:

Property	Type	Description
`min`	`number`	Minimum items required
`max`	`number`	Maximum items allowed
`add_item_button_text`	`string`	”Add” button text (empty array)
`add_second_item_button_text`	`string`	”Add” button text (after first item)
`add_item_title`	`string`	Add dialog title
`edit_item_title`	`string`	Edit dialog title
`item_format`	`string`	Display template (e.g., `{{question}}`)

Validation

Rule	Type	Description
`required`	`boolean`	Array must have at least one item
`maxSize`	`number`	Maximum items (alternative to `array_options.max`)

linkapp.config.ts

{
  id: "socialLinks",
  inputType: "array",
  title: "Social Links",
  description: "Add your social media profiles",
  label: "Social profiles",
  array_options: {
    min: 1,
    max: 5,
    add_item_button_text: "Add social link",
    add_second_item_button_text: "Add another link",
    item_format: "{{platform}}: {{url}}"
  },
  array_elements: [
    {
      id: "platform",
      inputType: "select",
      title: "Platform",
      label: "Social platform",
      options: [
        { label: "Twitter", value: "twitter" },
        { label: "Instagram", value: "instagram" },
        { label: "TikTok", value: "tiktok" },
        { label: "LinkedIn", value: "linkedin" }
      ],
      validation: { required: true }
    },
    {
      id: "url",
      inputType: "url",
      title: "Profile URL",
      label: "URL",
      placeholder: "https://twitter.com/username",
      validation: { required: true }
    }
  ],
  validation: {
    required: true
  }
}

Usage in layout:

app/expanded.tsx

type SocialLink = {
  platform: 'twitter' | 'instagram' | 'tiktok' | 'linkedin'
  url: string
}

type Settings = {
  socialLinks: SocialLink[]
}

export default function ClassicLayout({ socialLinks }: AppProps<Settings>) {
  return (
    <div className="social-links">
      <h2>Follow me:</h2>
      {socialLinks.map((link, index) => (
        <a key={index} href={link.url} className={`social-${link.platform}`}>
          {link.platform}
        </a>
      ))}
    </div>
  )
}

Example: FAQ List

linkapp.config.ts

{
  id: "questions_list",
  inputType: "array",
  title: "Questions",
  validation: {
    required: true,
    maxSize: 20
  },
  array_options: {
    add_item_button_text: "Add a question",
    add_item_title: "Add question",
    add_second_item_button_text: "Add another question",
    edit_item_title: "Edit question",
    item_format: "{{question}}"  // Shows question text in list
  },
  array_elements: [
    {
      id: "question",
      title: "Question",
      inputType: "text",
      validation: {
        required: true,
        minLength: 1,
        maxLength: 200
      }
    },
    {
      id: "answer",
      title: "Answer",
      inputType: "textarea",
      validation: {
        required: true,
        minLength: 1,
        maxLength: 800
      }
    }
  ]
}

Usage in layout:

app/expanded.tsx

type Question = {
  question: string
  answer: string
}

type FAQSettings = {
  questions_list: Question[]
}

export default function ClassicLayout({ questions_list }: AppProps<FAQSettings>) {
  return (
    <div className="faq">
      <h1>Frequently Asked Questions</h1>
      {questions_list.map((item, index) => (
        <details key={index}>
          <summary>{item.question}</summary>
          <p>{item.answer}</p>
        </details>
      ))}
    </div>
  )
}

Use item_format with {{fieldId}} syntax to show a preview of each item in the admin list view.

Conditional Display

Show or hide elements based on the value of other elements. Creates dynamic forms that adapt to user choices.

Properties

Property	Type	Description
`dependsOn`	`string`	ID of the element this depends on
`value`	`string \| boolean`	Value that triggers display
`operator`	`'equals' \| 'notEquals' \| 'contains'`	Comparison operator (default: `'equals'`)

Add conditionalDisplay to any element to control its visibility.

Example: Conditional Email Input

linkapp.config.ts

elements: [
  {
    id: "enableNotifications",
    inputType: "switch",
    title: "Notifications",
    label: "Enable email notifications",
    defaultValue: false
  },
  {
    id: "notificationEmail",
    inputType: "text",
    title: "Email Address",
    label: "Email",
    placeholder: "you@example.com",
    validation: {
      required: true
    },
    // Only show if enableNotifications is true
    conditionalDisplay: {
      dependsOn: "enableNotifications",
      value: true,
      operator: "equals"
    }
  }
]

Example: Conditional Based on Select

linkapp.config.ts

elements: [
  {
    id: "integrationProvider",
    inputType: "select",
    title: "Integration Provider",
    options: [
      { label: "Mailchimp", value: "mailchimp" },
      { label: "SendGrid", value: "sendgrid" },
      { label: "Custom API", value: "custom" }
    ]
  },
  {
    id: "customApiEndpoint",
    inputType: "url",
    title: "Custom API Endpoint",
    placeholder: "https://api.example.com/notify",
    validation: { required: true },
    // Only show if integrationProvider is 'custom'
    conditionalDisplay: {
      dependsOn: "integrationProvider",
      value: "custom"
    }
  },
  {
    id: "customApiKey",
    inputType: "password",
    title: "API Key",
    // Also only show for custom
    conditionalDisplay: {
      dependsOn: "integrationProvider",
      value: "custom"
    }
  }
]

Operators

Operator	Description	Example
`equals`	Exact match (default)	`value: true` shows when field is true
`notEquals`	Does not match	`value: "none"` shows when field is not “none”
`contains`	Array contains value	`value: "advanced"` shows if array includes “advanced”

Use conditional display to reduce form complexity and show users only relevant fields.

Integration

Connect to third-party services like email marketing platforms. Requires users to have the integration already set up in their Linktree account.

Properties

Property	Type	Description
`id`	`string`	Unique identifier
`inputType`	`'integration'`	Must be `'integration'`
`capability`	`string`	Required integration capability
`vendor`	`string`	Specific vendor identifier (optional)
`title`	`string`	Field title
`description`	`string`	Help text

Example

linkapp.config.ts

{
  id: "emailIntegration",
  inputType: "integration",
  title: "Email Marketing",
  description: "Connect your email marketing service to collect subscribers",
  capability: "MANAGE_EMAIL_SUBSCRIBERS",
  vendor: "mailchimp"  // Optional: specific vendor
}

Users must have the integration already connected in their Linktree account. This element lets them select which integration to use with your LinkApp.

File Upload

Upload images, documents, or other file types.

Properties

Property	Type	Description
`id`	`string`	Unique identifier
`inputType`	`'file'`	Must be `'file'`
`title`	`string`	Field title
`description`	`string`	Help text
`label`	`string`	Input label
`accept`	`string[]`	Accepted file types
`multiple`	`boolean`	Allow multiple files
`validation`	`object`	Validation rules

Example

linkapp.config.ts

{
  id: "bannerImage",
  inputType: "file",
  title: "Banner Image",
  description: "Upload a banner image for your LinkApp",
  label: "Choose image",
  accept: ["image/png", "image/jpeg", "image/webp"],
  multiple: false,
  validation: {
    required: true
  }
}

Embed Option

Configure how embedded content should display. Specialized for LinkApps that embed third-party content.

Properties

Property	Type	Description
`id`	`string`	Unique identifier
`inputType`	`'embedOption'`	Must be `'embedOption'`
`title`	`string`	Field title
`description`	`string`	Help text
`defaultValue`	`string`	Default embed option

Example

linkapp.config.ts

{
  id: "embedDisplay",
  inputType: "embedOption",
  title: "Embed Display",
  description: "Choose how to display embedded content",
  defaultValue: "full"
}

Button

Interactive button element that triggers actions.

Properties

Property	Type	Description
`id`	`string`	Unique identifier
`inputType`	`'button'`	Must be `'button'`
`label`	`string`	Button text
`action`	`object`	Action configuration

Action Properties

Property	Type	Description
`on`	`'click'`	Interaction event
`type`	`'update-link'`	Action type
`data.link_type`	`string`	Link type to update to

Example

linkapp.config.ts

{
  id: "upgradeButton",
  inputType: "button",
  label: "Upgrade to Pro Version",
  action: {
    on: "click",
    type: "update-link",
    data: {
      link_type: "pro-version-app"
    }
  }
}

Complete Example: Advanced FAQ App

Here’s a complete example using arrays and conditional display:

linkapp.config.ts

export default {
  settings: {
    title: "FAQ Manager",
    icon: "question",
    uses_url: false,
    elements: [
      // Array of FAQ items
      {
        id: "questions_list",
        inputType: "array",
        validation: {
          required: true,
          maxSize: 20
        },
        array_options: {
          add_item_button_text: "Add a question",
          add_item_title: "Add question",
          item_format: "{{question}}"
        },
        array_elements: [
          {
            id: "question",
            title: "Question",
            inputType: "text",
            validation: { required: true, maxLength: 200 }
          },
          {
            id: "answer",
            title: "Answer",
            inputType: "textarea",
            validation: { required: true, maxLength: 800 }
          }
        ]
      },

      // Enable search toggle
      {
        id: "enableSearch",
        inputType: "switch",
        title: "Search Options",
        label: "Enable question search",
        defaultValue: false
      },

      // Search placeholder (conditional)
      {
        id: "searchPlaceholder",
        inputType: "text",
        title: "Search Placeholder",
        label: "Placeholder text",
        defaultValue: "Search questions...",
        conditionalDisplay: {
          dependsOn: "enableSearch",
          value: true
        }
      },

      // Enable categories toggle
      {
        id: "enableCategories",
        inputType: "switch",
        title: "Organization",
        label: "Group questions by category",
        defaultValue: false
      },

      // Category list (conditional)
      {
        id: "categories",
        inputType: "array",
        title: "Categories",
        description: "Define question categories",
        conditionalDisplay: {
          dependsOn: "enableCategories",
          value: true
        },
        array_options: {
          add_item_button_text: "Add category",
          item_format: "{{name}}"
        },
        array_elements: [
          {
            id: "name",
            inputType: "text",
            title: "Category Name",
            validation: { required: true, maxLength: 50 }
          }
        ]
      }
    ]
  }
}

Validation Strategies

Required Arrays

{
  id: "items",
  inputType: "array",
  validation: {
    required: true  // At least one item required
  }
}

Array Size Limits

{
  id: "items",
  inputType: "array",
  array_options: {
    min: 1,   // Minimum items
    max: 10   // Maximum items
  }
}

Or use validation.maxSize:

{
  id: "items",
  inputType: "array",
  validation: {
    maxSize: 10
  }
}

Nested Validation

Array elements can have their own validation:

array_elements: [
  {
    id: "email",
    inputType: "text",
    validation: {
      required: true,
      pattern: "^[^@]+@[^@]+\\.[^@]+$"  // Email format
    }
  }
]

Best Practices

Array Design

// ✅ Good - clear item format
array_options: {
  item_format: "{{question}}"  // Shows question text
}

// ✅ Good - descriptive button text
array_options: {
  add_item_button_text: "Add a social link",
  add_second_item_button_text: "Add another social link"
}

Conditional Display

// ✅ Good - progressive disclosure
{
  id: "advancedMode",
  inputType: "switch",
  label: "Show advanced options"
},
{
  id: "advancedSettings",
  inputType: "text",
  conditionalDisplay: {
    dependsOn: "advancedMode",
    value: true
  }
}

Array Element Names

// ✅ Good - descriptive IDs
array_elements: [
  { id: "question", inputType: "text" },
  { id: "answer", inputType: "textarea" }
]

// ❌ Avoid - unclear
array_elements: [
  { id: "q", inputType: "text" },
  { id: "a", inputType: "textarea" }
]

Type Safety

Define array item types:

type Question = {
  question: string
  answer: string
}

type SocialLink = {
  platform: string
  url: string
}

type Settings = {
  questions_list: Question[]
  socialLinks: SocialLink[]
  enableSearch: boolean
  searchPlaceholder: string  // Only shown if enableSearch is true
}

export default function ClassicLayout(props: AppProps<Settings>) {
  const { questions_list, socialLinks, enableSearch, searchPlaceholder } = props

  return <div>...</div>
}

Next Steps

Text Inputs

Text, textarea, URL, and number inputs

Selection Controls

Select, radio, and checkbox elements

Toggles

Switch and link behavior elements

Back to Reference

Return to settings reference overview

Getting Started

Essentials

​Overview

​Array

​Properties

​Array Options

​Validation

​Example: Social Links

​Example: FAQ List

​Conditional Display

​Properties

​Example: Conditional Email Input

​Example: Conditional Based on Select

​Operators

​Integration

​Properties

​Example

​File Upload

​Properties

​Example

​Embed Option

​Properties

​Example

​Button

​Properties

​Action Properties

​Example

​Complete Example: Advanced FAQ App

​Validation Strategies

​Required Arrays

​Array Size Limits

​Nested Validation

​Best Practices

​Array Design

​Conditional Display

​Array Element Names

​Type Safety

​Next Steps

Text Inputs

Selection Controls

Toggles

Back to Reference

Overview

Array

Properties

Array Options

Validation

Example: Social Links

Example: FAQ List

Conditional Display

Properties

Example: Conditional Email Input

Example: Conditional Based on Select

Operators

Integration

Properties

Example

File Upload

Properties

Example

Embed Option

Properties

Example

Button

Properties

Action Properties

Example

Complete Example: Advanced FAQ App

Validation Strategies

Required Arrays

Array Size Limits

Nested Validation

Best Practices

Array Design

Conditional Display

Array Element Names

Type Safety

Next Steps