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

# Location Element

> Google Places location picker for collecting place data

## Overview

The location element provides a Google Places search interface for users to select a location. It stores the full place data including coordinates, name, address, and optional metadata like ratings and photos.

| Element    | Best For                      | Value Type   |
| ---------- | ----------------------------- | ------------ |
| `location` | Store addresses, venues, POIs | `PlaceValue` |

## Properties

| Property       | Type         | Description                           |
| -------------- | ------------ | ------------------------------------- |
| `id`           | `string`     | Unique identifier (becomes prop name) |
| `inputType`    | `'location'` | Must be `'location'`                  |
| `title`        | `string`     | Field title                           |
| `description`  | `string`     | Help text                             |
| `placeholder`  | `string`     | Search input placeholder text         |
| `defaultValue` | `PlaceValue` | Initial selected location             |
| `validation`   | `object`     | Validation rules                      |

### Validation

| Rule       | Type      | Description                 |
| ---------- | --------- | --------------------------- |
| `required` | `boolean` | A location must be selected |

### PlaceValue Structure

The selected location value has this structure:

```ts theme={"system"}
interface PlaceValue {
  placeId: string        // Google Places ID
  name: string           // Place name
  address: string        // Formatted address
  lat: number            // Latitude
  lng: number            // Longitude
  photos?: string[]      // Photo URLs (optional)
  rating?: number        // Place rating 1-5 (optional)
  userRatingsTotal?: number // Number of reviews (optional)
  types?: string[]       // Place types (optional)
  website?: string       // Website URL (optional)
  phoneNumber?: string   // Phone number (optional)
}
```

## Example

### Basic Location

```ts linkapp.config.ts theme={"system"}
{
  id: "storeLocation",
  inputType: "location",
  title: "Store Location",
  description: "Select your store location",
  validation: {
    required: true
  }
}
```

### With Custom Placeholder

```ts linkapp.config.ts theme={"system"}
{
  id: "venue",
  inputType: "location",
  title: "Event Venue",
  description: "Search for the venue",
  placeholder: "Search for a venue...",
  validation: {
    required: true
  }
}
```

## Usage in Layout

```tsx app/expanded.tsx theme={"system"}
import type { AppProps, PlaceValue } from "@linktr.ee/linkapp/types"

type Settings = {
  storeLocation: PlaceValue
}

export default function ClassicLayout({ storeLocation }: AppProps<Settings>) {
  return (
    <div className="p-4">
      <h2 className="text-xl font-bold">{storeLocation.name}</h2>
      <p className="text-gray-600">{storeLocation.address}</p>

      {storeLocation.rating && (
        <p className="text-sm text-yellow-600">
          Rating: {storeLocation.rating}/5 ({storeLocation.userRatingsTotal} reviews)
        </p>
      )}

      <a
        href={`https://www.google.com/maps/place/?q=place_id:${storeLocation.placeId}`}
        target="_blank"
        rel="noopener noreferrer"
        className="text-blue-600 hover:underline"
      >
        View on Google Maps
      </a>
    </div>
  )
}
```

## Using with Arrays

Location elements work inside arrays for collecting multiple locations:

```ts linkapp.config.ts theme={"system"}
{
  id: "locations",
  inputType: "array",
  title: "Store Locations",
  description: "Add your store locations",
  array_options: {
    min: 1,
    max: 10,
    add_item_button_text: "Add location",
    add_second_item_button_text: "Add another location",
    edit_item_title: "Edit location",
    add_item_title: "Add location",
    item_format: "{{name}}"
  },
  array_elements: [
    {
      id: "name",
      inputType: "text",
      title: "Location Name",
      placeholder: "e.g., Downtown Store",
      validation: { required: true, maxLength: 50 }
    },
    {
      id: "place",
      inputType: "location",
      title: "Address",
      description: "Search for the store address",
      validation: { required: true }
    }
  ]
}
```

**Usage in Layout:**

```tsx app/expanded.tsx theme={"system"}
import type { AppProps, PlaceValue } from "@linktr.ee/linkapp/types"

type StoreLocation = {
  name: string
  place: PlaceValue
}

type Settings = {
  locations: StoreLocation[]
}

export default function ClassicLayout({ locations }: AppProps<Settings>) {
  return (
    <div className="space-y-4">
      {locations.map((location, index) => (
        <div key={index} className="p-4 border rounded-lg">
          <h3 className="font-bold">{location.name}</h3>
          <p className="text-gray-600">{location.place.address}</p>
          {location.place.rating && (
            <span className="text-sm text-yellow-600">
              Rating: {location.place.rating}/5
            </span>
          )}
        </div>
      ))}
    </div>
  )
}
```

## Common Patterns

**Business location:**

```ts theme={"system"}
{
  id: "businessAddress",
  inputType: "location",
  title: "Business Address",
  description: "Your business location for customers to find you",
  placeholder: "Search for your business...",
  validation: { required: true }
}
```

**Event venue:**

```ts theme={"system"}
{
  id: "venue",
  inputType: "location",
  title: "Event Venue",
  description: "Where the event will be held",
  placeholder: "Search for a venue...",
  validation: { required: true }
}
```

<Note>
  The actual Google Places picker is rendered in the Linktree admin (frontyard).
  The dev server shows a preview placeholder.
</Note>

## Best Practices

1. **Provide clear descriptions** explaining what type of location is expected
2. **Use custom placeholders** to guide users on what to search for
3. **Consider using arrays** when users need to add multiple locations
4. **Handle optional fields** - rating, photos, etc. may not be available for all places

## Next Steps

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

  <Card title="Advanced Elements" icon="layer-group" href="/essentials/settings/advanced">
    Arrays, integrations, and conditional display
  </Card>

  <Card title="Selection Controls" icon="list-check" href="/essentials/settings/selections">
    Select, radio, and checkbox elements
  </Card>

  <Card title="Back to Reference" icon="arrow-left" href="/essentials/settings-reference">
    Return to settings reference overview
  </Card>
</CardGroup>