# Vehicle Search Form

The `VehicleSearchForm` component is a comprehensive vehicle search form that allows users to filter cars by various criteria and display matching results. It includes pagination, filtering options, and the ability to redirect to a search results page.

### 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 VehicleSearchForm component in a standard HTML page, you only need two required attributes:

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

This minimal setup will display a search form with inline results. See the [Examples](http://localhost:63342/markdownPreview/1564344665/markdown-preview-index-m6q59oqq3tls8r71d98vtp3h3m.html#examples) section below for more advanced configurations including wishlist, comparison, and redirect functionality.

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

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

#### Required Attributes <a href="#required-attributes" id="required-attributes"></a>

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

#### Optional Attributes <a href="#optional-attributes" id="optional-attributes"></a>

| Attribute                      | Type    | Default | Description                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------ | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-search-url-forward`      | string  | null    | URL to redirect to when search button is clicked. When set, no results are shown inline - instead saves form state to localStorage and redirects to the specified URL. The target page must have another car-search-form component to read the localStorage state and display the results. When null, results are displayed inline below the form.                    |
| `data-force-scroll-to-top`     | boolean | false   | When true, forces window to scroll to the top when changing pages or filters.                                                                                                                                                                                                                                                                                         |
| `data-enable-page-load-focus`  | boolean | false   | When true, enables focus behavior when a page loads.                                                                                                                                                                                                                                                                                                                  |
| `data-default-form-state-hash` | string  | null    | Default form state (base64-encoded) to use when resetting the form. If not provided, a new empty form state will be created.                                                                                                                                                                                                                                          |
| `data-wishlist`                | boolean | false   | When true, enables wishlist functionality allowing users to save cars to a favorites list.                                                                                                                                                                                                                                                                            |
| `data-compare`                 | boolean | false   | When true, enables comparison functionality allowing users to compare up to 3 cars side by side.                                                                                                                                                                                                                                                                      |
| `data-history`                 | boolean | false   | When true, enables visit history functionality allowing users to see their recently viewed car detail pages.                                                                                                                                                                                                                                                          |
| `data-rates`                   | boolean | false   | When true, enables display of leasing and financing payment options with an interactive dropdown selector. When false, only cash price is displayed.                                                                                                                                                                                                                  |
| `data-ai-assistant`            | boolean | false   | When true, enables AI-powered natural language search functionality allowing users to describe their desired car in plain text (e.g., "red car with leather seats").                                                                                                                                                                                                  |
| `data-description-mode`        | string  | auto    | Controls how the equipment/description section is rendered on the vehicle detail page. Values: `formatted` (collapsible accordion groups parsed from HTML), `features` (structured feature tag list), `plain` (raw HTML rendered with basic list styling). When omitted, uses `formatted` if the vehicle has an HTML description, otherwise falls back to `features`. |

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

* Filtering by manufacturer, model, condition, mileage, construction year, engine type, vehicle type, fuel type, store, and price
* Additional detailed filters accessible via "weitere Filter anzeigen" button
* Real-time vehicle count display
* Reset button to clear all filters
* Pagination for search results
* Responsive layout that adapts to different screen sizes
* AI-powered natural language search with conversational interface (when enabled)
* Wishlist functionality for saving favorite vehicles (when enabled)
* Comparison functionality for comparing up to 3 cars side by side (when enabled)
* Visit history functionality for tracking recently viewed car detail pages (when enabled)
* Leasing and financing rate display with interactive payment type selector (when enabled)
* Icon-overlay buttons on car thumbnails for quick wishlist and comparison actions
* Floating action buttons for easy access to AI assistant, wishlist, comparison, and history (when enabled)

### AI Assistant Functionality <a href="#ai-assistant-functionality" id="ai-assistant-functionality"></a>

**Important:** The AI Assistant feature requires the AI Module License to be active on your account. Without this license, the AI assistant will not provide results and searches will fail. Contact your Carpose representative to enable the AI Module License.

When AI assistant functionality is enabled via the `data-ai-assistant="true"` attribute, users can:

1. Search for vehicles using natural language descriptions (e.g., "red car with leather seats", "add panoramic sunroof")
2. Build upon previous searches conversationally (e.g., first "BMW with automatic transmission", then "add navigation system")
3. Access the AI assistant through:

* An input field directly in the search form (when enabled to show in form)
* A floating AI button that opens a slide-out drawer with full history

4. View their search history with timestamps
5. Remove individual search queries from history
6. Clear entire search history
7. Toggle AI assistant visibility in the form via a switch in the drawer

The AI assistant integration consists of:

* `AiAssistantInput` component with typing animation and conversational interface
* `AiCarSearchAssistantFloatingButton` component displayed as a floating action button
* `AiCarSearchAssistantContext` provider that manages the AI state and history across the application
* Automatic form state updates and scroll-to-results behavior after successful searches

#### How It Works <a href="#how-it-works" id="how-it-works"></a>

* Users describe their desired vehicle in natural language (German)
* The AI processes the query and returns filter settings
* Filter settings are automatically applied to the search form
* Results are displayed and the page scrolls to the car list
* Context is maintained across multiple queries for refinement
* When using the drawer, it automatically closes after a successful search

#### Example with AI Assistant Enabled <a href="#example-with-ai-assistant-enabled" id="example-with-ai-assistant-enabled"></a>

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

### Wishlist Functionality <a href="#wishlist-functionality" id="wishlist-functionality"></a>

When wishlist functionality is enabled via the `data-wishlist="true"` attribute, users can:

1. Save vehicles to a wishlist that persists between sessions (stored in browser localStorage)
2. Access saved vehicles through a floating wishlist button that appears in the UI
3. View all saved vehicles in a slide-out drawer
4. Select vehicles from their wishlist to send an inquiry
5. Remove vehicles from their wishlist
6. Navigate directly to vehicle detail pages from the wishlist

The wishlist integration consists of:

* `WishlistButton` component added to each car card
* `WishlistFloatingButton` component displayed in the UI when wishlist is enabled
* `WishlistContext` provider that manages the wishlist state across the application

#### Example with Wishlist Enabled <a href="#example-with-wishlist-enabled" id="example-with-wishlist-enabled"></a>

```html
<div
data-carpose-component="vehicle-search-form"
data-api-key="your-api-key"
data-search-url-forward="/search-results"
data-wishlist="true"
></div>
```

### Comparison Functionality <a href="#comparison-functionality" id="comparison-functionality"></a>

When comparison functionality is enabled via the `data-compare="true"` attribute, users can:

1. Add up to 3 vehicles to a comparison list that persists between sessions (stored in browser localStorage)
2. Access the comparison view through a floating comparison button that appears in the UI
3. View all selected vehicles side by side in a modal for easy comparison
4. Compare key vehicle specifications including:

* Price and VAT information
* Registration date and mileage
* Power and engine specifications
* Transmission and fuel type
* Additional specifications (cubic capacity, seats, doors, colors)

5. Remove vehicles from the comparison
6. Navigate directly to vehicle detail pages from the comparison view
7. Responsive layout: 1 car (full width), 2 cars (50/50 split), 3 cars (equal thirds)
8. Mobile-optimized horizontal scroll view for comparing vehicles on smaller screens

The comparison integration consists of:

* `ComparisonButton` component added to car cards and detail pages
* `ComparisonIconButton` component displayed as overlay on car thumbnails
* `ComparisonFloatingButton` component displayed in the UI when comparison is enabled
* `ComparisonContext` provider that manages the comparison state across the application

#### Example with Comparison Enabled <a href="#example-with-comparison-enabled" id="example-with-comparison-enabled"></a>

```html
<div
data-carpose-component="vehicle-search-form"
data-api-key="your-api-key"
data-search-url-forward="/search-results"
data-compare="true"
></div>
```

#### Example with Both Wishlist and Comparison Enabled <a href="#example-with-both-wishlist-and-comparison-enabled" id="example-with-both-wishlist-and-comparison-enabled"></a>

```html
<div
data-carpose-component="vehicle-search-form"
data-api-key="your-api-key"
data-search-url-forward="/search-results"
data-wishlist="true"
data-compare="true"
></div>
```

### History Functionality <a href="#history-functionality" id="history-functionality"></a>

When history functionality is enabled via the `data-history="true"` attribute, users can:

1. Automatically track all visited car detail pages (stored in browser localStorage)
2. Access visit history through a floating history button that appears in the UI
3. View all recently visited vehicles in a slide-out drawer (most recent first)
4. Navigate back to previously viewed vehicle detail pages
5. Clear the entire visit history
6. History is limited to the last 50 visited vehicles

The history integration consists of:

* Automatic tracking when users view car detail pages
* `HistoryFloatingButton` component displayed in the UI when history is enabled
* `HistoryContext` provider that manages the history state across the application

#### Example with History Enabled <a href="#example-with-history-enabled" id="example-with-history-enabled"></a>

```html
<div
data-carpose-component="vehicle-search-form"
data-api-key="your-api-key"
data-search-url-forward="/search-results"
data-history="true"
></div>
```

#### Example with All Features Enabled (AI Assistant, Wishlist, Comparison, and History) <a href="#example-with-all-features-enabled-ai-assistant-wishlist-comparison-and-history" id="example-with-all-features-enabled-ai-assistant-wishlist-comparison-and-history"></a>

```html
<div
data-carpose-component="vehicle-search-form"
data-api-key="your-api-key"
data-search-url-forward="/search-results"
data-ai-assistant="true"
data-wishlist="true"
data-compare="true"
data-history="true"
></div>
```

### Rates Functionality <a href="#rates-functionality" id="rates-functionality"></a>

When rates functionality is enabled via the `data-rates="true"` attribute, the price display changes to show financing options:

**Without `data-rates` (default behavior):**

* Only the cash price is displayed
* Simple static price presentation
* Shows "MwSt. ausweisbar" for VAT deductible vehicles

**With `data-rates="true"`:**

* Interactive payment type selector with dropdown menu
* Users can switch between payment options:
* **Barpreis** (Cash price)
* **Leasing** (Monthly lease payment - shown if available)
* **Finanzierung** (Monthly financing payment - shown if available)
* Dropdown button shows the currently selected payment type
* Price display updates dynamically when switching payment types
* Tax information shown based on selected payment type

#### Example with Rates Enabled <a href="#example-with-rates-enabled" id="example-with-rates-enabled"></a>

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

#### Example with All Features Including Rates <a href="#example-with-all-features-including-rates" id="example-with-all-features-including-rates"></a>

```html
<div
data-carpose-component="vehicle-search-form"
data-api-key="your-api-key"
data-search-url-forward="/search-results"
data-ai-assistant="true"
data-wishlist="true"
data-compare="true"
data-history="true"
data-rates="true"
></div>
```

### Examples <a href="#examples" id="examples"></a>

#### Basic Example <a href="#basic-example" id="basic-example"></a>

```html
<div
data-carpose-component="vehicle-search-form"
data-api-key="your-api-key"
data-search-url-forward="/search-results"
></div>
```

#### Full Example with All Options <a href="#full-example-with-all-options" id="full-example-with-all-options"></a>

```html
<div
data-carpose-component="vehicle-search-form"
data-api-key="your-api-key"
data-search-url-forward="/search-results"
data-force-scroll-to-top="true"
data-enable-page-load-focus="true"
data-default-form-state-hash="eyJtYW51ZmFjdHVyZXIiOiIifQ=="
data-ai-assistant="true"
data-wishlist="true"
data-compare="true"
data-history="true"
data-rates="true"
></div>
```

#### Two-Page Setup Example <a href="#two-page-setup-example" id="two-page-setup-example"></a>

When using `data-search-url-forward`, you need two pages:

**Page 1: Search Form (e.g., /index.html)**

```html
<!-- Form only - redirects to results page on submit -->
<div
data-carpose-component="vehicle-search-form"
data-api-key="your-api-key"
data-search-url-forward="/search-results"
data-ai-assistant="true"
data-wishlist="true"
data-compare="true"
data-history="true"
data-rates="true"
></div>
```

**Page 2: Results Page (e.g., /search-results.html)**

```html
<!-- Form + Results - displays results inline based on localStorage -->
<div
data-carpose-component="vehicle-search-form"
data-api-key="your-api-key"
data-ai-assistant="true"
data-wishlist="true"
data-compare="true"
data-history="true"
data-rates="true"
></div>
```

In this setup:

* The form on Page 1 saves the form state to localStorage and redirects to `/search-results`
* The form on Page 2 reads the form state from localStorage and displays the results inline

#### AI-Only Landing Page Setup <a href="#ai-only-landing-page-setup" id="ai-only-landing-page-setup"></a>

For a dedicated AI search landing page that shows only the AI input and redirects to results:

**Page 1: AI Search Landing Page (e.g., /ai-search.html)**

```html
<!-- Only AI input - no filters shown, redirects to results page -->
<div
data-carpose-component="vehicle-search-form"
data-api-key="your-api-key"
data-search-url-forward="/search-results"
data-ai-assistant="true"
></div>
```

**Page 2: Results Page (e.g., /search-results.html)**

```html
<!-- Full form + AI + Results - displays results with AI history available -->
<div
data-carpose-component="vehicle-search-form"
data-api-key="your-api-key"
data-ai-assistant="true"
data-wishlist="true"
data-compare="true"
data-history="true"
data-rates="true"
></div>
```

In this AI-only setup:

* Page 1 shows ONLY the AI input field (all filters, buttons hidden)
* Floating AI button is hidden
* After user enters their search query, the AI processes it
* AI query and hash are saved to localStorage for Page 2
* Form state is saved to localStorage for Page 2
* User is automatically redirected to `/search-results`
* Page 2 loads with the AI search history and results already available
* User can continue refining their search conversationally on Page 2

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

1. **Search Mode**:

* **With `data-search-url-forward` set**: Clicking the search button redirects to the specified URL. The form state is saved to localStorage for that specific page path. No results are shown inline. The target page must include another car-search-form component to read the localStorage state and display the results.
* **Without `data-search-url-forward` (or set to null)**: Search results are displayed inline directly below the form on the same page.

2. **Form State Persistence**:

* Form state is stored in browser localStorage with page-specific keys.
* State persists across page reloads and browser sessions.

3. **Form Reset**:

* The reset button restores form to default state.
* The default state is determined by `data-default-form-state-hash` if provided, otherwise a new empty state is created.

4. **Scrolling Behavior**:

* Control scroll behavior with `data-force-scroll-to-top` and `data-enable-page-load-focus`.
* After successful AI assistant searches, the page automatically scrolls to the car list results.

5. **AI Assistant Behavior**:

* Enable AI-powered natural language search with `data-ai-assistant="true"`.
* **Requires AI Module License** - Feature will not work without active license.
* Users can describe their desired vehicle in German natural language.

**Standard Mode (without `data-search-url-forward`):**

* AI assistant is accessible through:
  * Input field in the search form (can be toggled on/off via drawer switch)
  * Floating button with AI icon that opens a slide-out drawer
* Search history with timestamps is maintained and persists in browser localStorage.
* Conversational interface allows building upon previous searches.
* Context is maintained across multiple queries for refinement.
* After a successful search:
  * Filter settings are automatically applied to the form
  * If opened from drawer, the drawer automatically closes
  * Page scrolls smoothly to the car list results
* Users can:
  * View their full search history with relative timestamps
  * Remove individual queries from history (triggers re-processing of remaining queries)
  * Clear entire search history
  * Toggle visibility of AI input in the main form
* Typing animation in the placeholder text provides visual guidance on how to use the feature.

**AI-Only Mode (with both `data-ai-assistant="true"` AND `data-search-url-forward`):**

* Only the AI input field is shown (all filter selects, buttons, and controls are hidden)
* Floating AI button is hidden
* Each search is independent (no conversational context between queries)
* After a successful search:
  * Form state is saved to localStorage for the target page
  * AI query and hash are saved to localStorage for the target page
  * User is redirected to the URL specified in `data-search-url-forward`
  * Target page loads with the AI history and results already available
* This mode is designed for a dedicated AI search landing page that redirects to results.

6. **Wishlist Behavior**:

* Enable wishlist functionality with `data-wishlist="true"`.
* Wishlist state persists between sessions through localStorage.
* Users can send inquiries for multiple vehicles at once from their wishlist.
* Success messages are shown when adding or removing vehicles from the wishlist.

7. **Comparison Behavior**:

* Enable comparison functionality with `data-compare="true"`.
* Comparison state persists between sessions through localStorage.
* Users can compare up to 3 vehicles side by side.
* Warning message is shown when trying to add more than 3 vehicles.
* Success messages are shown when adding or removing vehicles from the comparison.
* Responsive column layout: 1 car (full width), 2 cars (50/50), 3 cars (equal thirds).

8. **History Behavior**:

* Enable visit history functionality with `data-history="true"`.
* History automatically tracks all visited car detail pages.
* History state persists between sessions through localStorage.
* Most recently visited vehicles appear at the top of the list.
* History is automatically limited to the last 50 visited vehicles.
* Users can clear their entire visit history.
* No individual delete - history is meant for tracking, not managing.
* Floating history button displays with a clock icon.

9. **Rates Behavior**:

* Enable payment rate options with `data-rates="true"`.
* When disabled (default): Only cash price is shown with a simple static display.
* When enabled: Interactive payment selector appears with dropdown menu.
* Available payment types:
  * Cash price (Barpreis) - always available
  * Monthly leasing rate - shown only if vehicle has leasing data
  * Monthly financing rate - shown only if vehicle has financing data
* Users can switch between payment types using the dropdown button.
* Selected payment type is displayed on the button label.
* Price display dynamically updates when switching payment types.
* Tax information (VAT deductible status) is shown based on payment type.

10. **Pagination**:

* When inline search results are displayed, results are paginated with 30 items per page.
* Pagination controls are shown at the bottom of the results when there are multiple pages.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.carpose.de/vehicle-search-modules/vehicle-search-form.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.