# Geocoder

An accessible location search backed by the Mapbox geocoding API, debounced to limit billed calls; returns the chosen place's coordinates.

**Category:** Components/Controls/Geocoder

**Import:** `import { Geocoder } from '@reuters-graphics/graphics-components'`

## Props

| Prop | Type | Default | Required | Description |
|------|------|---------|:--------:|-------------|
| `accessToken` | `string` | — | ✓ | Mapbox public access token. |
| `searchPlaceholder` | `string` | `'Search for a location'` |  | Placeholder text shown in the search input. |
| `onselect` | `(location: { lng: number; lat: number; name: string }) => void` | — |  | Callback fired when a location is selected from the results. |
| `minLength` | `number` | `2` |  | Minimum number of characters before a request is made. Raising this cuts the number of paid geocoding requests per search. Defaults to 2. |
| `debounceMs` | `number` | `300` |  | Debounce window in milliseconds between the last keystroke and the request. Raising this fires fewer requests while the user is still typing (each request is billed). Defaults to 300. |

## Examples

### Demo

```svelte
<div style="min-height: 330px; padding-top: 1rem;">
  <Geocoder {accessToken} onselect={handleSelect} />
</div>
```

## Documentation

# Geocoder

The `Geocoder` component provides an autocomplete location search powered by the [Mapbox Geocoding v6 API](https://docs.mapbox.com/api/search/geocoding-v6/). It returns coordinates and a place name via the `onselect` callback.

```svelte
<script>
  import { Geocoder } from '@reuters-graphics/graphics-components';

  const MAPBOX_TOKEN = 'your_mapbox_token';

  function handleSelect(location) {
    console.log(location.name, location.lng, location.lat);
  }
</script>

<Geocoder accessToken={MAPBOX_TOKEN} onselect={handleSelect} />
```

The `accessToken` prop is required. Look up the Reuters Mapbox token in the team's 1Password vault. All [Mapbox forward geocoding options](https://docs.mapbox.com/api/search/geocoding-v6/#forward-geocoding) are available as props, including `country`, `language`, `types`, `bbox`, `proximity`, `limit`, and `worldview`.

To reduce the number of paid geocoding requests, use `minLength` (minimum characters before searching, default `2`) and `debounceMs` (delay after the last keystroke before requesting, default `300`). Raising them fires fewer requests while the user is still typing.