vue-osm-autocomplete

A Vue 3 autocomplete component for location search using OpenStreetMap's Nominatim API. This component provides a user-friendly interface for searching locations with debounced API calls, keyboard navigation, and customizable styling.

Features

• Autocomplete search for locations using the Nominatim API.
• Supports keyboard navigation (ArrowUp, ArrowDown, Enter, Escape, Tab).
• Accessible with ARIA attributes for screen reader support.
• Customizable styles and classes for flexible integration.
• Debounced API requests to optimize performance.
• Emits events for selection and errors.

Installation

Install the component and its dependency:

npm install vue-osm-autocomplete

Usage

Import and use the component in your Vue 3 application:

<template>
  <OpenStreetMapAutocomplete
    v-model="selectedLocation"
    placeholder="Search for a place"
    @search-error="handleError"
  />
</template>

<script setup>
import { ref } from "vue";
import OpenStreetMapAutocomplete from "vue-osm-autocomplete";

const selectedLocation = ref(null);
const handleError = (error) => console.error("Search error:", error);
</script>

Props

Prop	Type	Default	Description
modelValue	OpenStreetMapLocation | null	null	The selected location object (v-model).
debounce	number	300	Debounce time for API requests (in milliseconds).
placeholder	string	"Search location"	Placeholder text for the input field.
noResultsText	string	"No locations found"	Text displayed when no search results are found.
endpoint	string	"https://nominatim.openstreetmap.org/search"	Nominatim API endpoint URL.
language	string	"en"	Language for API results (e.g., "en", "fr").
classes	OpenStreetMapAutocompleteClasses	undefined	Custom CSS classes for component elements (see below).
styles	OpenStreetMapAutocompleteStyles	undefined	Inline styles for component elements (see below).

OpenStreetMapLocation Interface

interface OpenStreetMapLocation {
  place_id: number;
  licence: string;
  osm_type: string;
  osm_id: number;
  lat: string;
  lon: string;
  category: string;
  type: string;
  place_rank: number;
  importance: number;
  addresstype: string;
  name: string;
  display_name: string;
  boundingbox: string[];
}

OpenStreetMapAutocompleteClasses Interface

interface OpenStreetMapAutocompleteClasses {
  root?: string;
  form?: string;
  inputWrapper?: string;
  input?: string;
  divider?: string;
  button?: string;
  dropdown?: string;
  options?: string;
  option?: string;
  empty?: string;
  loading?: string;
}

OpenStreetMapAutocompleteStyles Interface

interface OpenStreetMapAutocompleteStyles {
  root?: Record<string, string>;
  form?: Record<string, string>;
  inputWrapper?: Record<string, string>;
  input?: Record<string, string>;
  divider?: Record<string, string>;
  button?: Record<string, string>;
  dropdown?: Record<string, string>;
  options?: Record<string, string>;
  option?: Record<string, string>;
  empty?: Record<string, string>;
  loading?: Record<string, string>;
}

Events

Event	Payload	Description
update:modelValue	OpenStreetMapLocation | null	Emitted when a location is selected.
search-error	unknown	Emitted when an API error occurs.

Slots

Slot	Description
icon	Custom icon for the search button.

Example with Custom Icon

<template>
  <OpenStreetMapAutocomplete v-model="selectedLocation">
    <template #icon>
      <svg viewBox="0 0 24 24">
        <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" />
      </svg>
    </template>
  </OpenStreetMapAutocomplete>
</template>

Styling

The component uses scoped CSS with the following class structure:

• .autocomplete: Root container.
• .autocomplete-form: Form element.
• .autocomplete-input-wrapper: Input wrapper.
• .autocomplete-input: Input element.
• .autocomplete-divider: Divider between input and button.
• .autocomplete-button: Search button.
• .autocomplete-dropdown: Dropdown container.
• .autocomplete-options: Options list.
• .autocomplete-option: Individual option (with .is-highlighted and .is-selected modifiers).
• .autocomplete-empty: No results message.
• .autocomplete-loading: Loading spinner.

You can override styles using the classes or styles props:

<template>
  <OpenStreetMapAutocomplete
    v-model="selectedLocation"
    :classes="{ root: 'custom-autocomplete', input: 'custom-input' }"
    :styles="{ root: { backgroundColor: 'lightgray' } }"
  />
</template>

<style>
.custom-autocomplete {
  border-radius: 8px;
}
.custom-input {
  border: 2px solid blue;
}
</style>

Accessibility

• Supports ARIA attributes (role="combobox", aria-expanded, aria-controls, etc.).
• Keyboard navigation with ArrowUp, ArrowDown, Enter, Escape, and Tab.
• Dropdown closes on outside click or Escape key.

Notes

• Nominatim Usage Policy: The component uses OpenStreetMap's Nominatim API, which has strict usage limits (max 1 request per second, no heavy load). For production applications, consider:
  • Using a custom endpoint with a Nominatim instance or proxy.
  • Implementing client-side caching or rate-limiting on your end.
  • Reviewing the Nominatim usage policy.
• Dependencies: Requires @vueuse/core for debouncing API requests.
• Minimum Query Length: The component requires a minimum of 3 characters before making API requests.
• Error Handling: Errors are emitted via the search-error event. Implement custom error handling in your application if needed.

Example with Error Handling

<template>
  <OpenStreetMapAutocomplete
    v-model="selectedLocation"
    @search-error="handleError"
  />
</template>

<script setup>
import { ref } from "vue";
import OpenStreetMapAutocomplete from "vue-osm-autocomplete";

const selectedLocation = ref(null);
const handleError = (error) => {
  alert("Failed to load locations: " + error.message);
};
</script>

Contributing

Contributions are welcome! Please submit issues or pull requests to the GitHub repository.

License

MIT License