> For the complete documentation index, see [llms.txt](https://docs.carpose.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carpose.de/vehicle-search-modules/04_vehicle-search-ai.md).

# Vehicle Search (AI)

### Overview <a href="#overview" id="overview"></a>

The `Vehicle Search AI` component provides a natural language search interface for vehicles. It allows users to search for cars using conversational queries rather than structured filters, making it more intuitive and user-friendly.

### Installation <a href="#installation" id="installation"></a>

The component is part of the Carpose application and requires no separate installation.

### Usage <a href="#usage" id="usage"></a>

To use the Vehicle Search AI component in a standard HTML page:

```html
<div
  data-carpose-component="vehicle-search-ai"
  data-api-key="your-api-key"
></div>
```

### Configuration Attributes <a href="#configuration-attributes" id="configuration-attributes"></a>

The component reads configuration from data attributes on the provided element:

| Attribute                | Type   | Default | Description                                                                               |
| ------------------------ | ------ | ------- | ----------------------------------------------------------------------------------------- |
| `data-carpose-component` | string | -       | Identifies the component type, must be set to "car-search-ai"                             |
| `data-api-key`           | string | -       | API key for authentication with the Carpose backend services. Required for data fetching. |

### Features <a href="#features" id="features"></a>

* Natural language search input for intuitive queries
* Results displayed as car cards with vehicle details
* Sorting options for search results:
  * Price (ascending/descending)
  * Mileage (ascending/descending)
  * Power (ascending/descending)
* Pagination for navigating through search results
* Loading indicators during search
* "No results" message when no matching vehicles are found
* Session storage persistence for search state (query, page, sorting)

### Example <a href="#example" id="example"></a>

```html
<div
  data-carpose-component="vehicle-search-ai"
  data-api-key="your-api-key"
></div>
```

### Behavior <a href="#behavior" id="behavior"></a>

1. **Search Interface**:
   * The component displays a prominent search input with a placeholder suggesting example queries.
   * Users can type natural language queries like "I'm looking for a city car" or "Show me SUVs with less than 50,000 km".
   * The search button triggers the query and displays loading indicators during the search process.
2. **Results Display**:
   * Search results are displayed as car cards below the search interface.
   * Each car card shows key information about the vehicle.
   * A count of total matching vehicles is displayed above the results.
   * If no matching vehicles are found, a friendly message is displayed.
3. **Sorting and Pagination**:
   * Once results are displayed, a sorting dropdown appears allowing users to sort by price, mileage, or power.
   * If there are more than 30 results, pagination controls appear at the bottom of the page.
   * Changing the sort order resets to the first page of results.
   * Clicking a pagination number fetches the corresponding page of results.
4. **State Persistence**:
   * The component stores the current search query, page number, and sorting preference in session storage.
   * If the user leaves and returns to the page, their previous search state is restored.
   * This allows users to continue browsing from where they left off.
5. **Responsive Behavior**:
   * The component adapts to different screen sizes.
   * On mobile devices, the sorting control appears above the results count for better usability.