Car Search Form

Overview

The CarSearchForm 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

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

Usage

To use the CarSearchForm component in a standard HTML page, you only need two required attributes:

<div
  data-carpose-component="car-search-form"
  data-api-key="your-api-key"
></div>

This minimal setup will display a search form with inline results. See the Examples section below for more advanced configurations including wishlist, comparison, and redirect functionality.

Configuration Attributes

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

Required Attributes

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

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").

Features

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

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:

Search for vehicles using natural language descriptions (e.g., "red car with leather seats", "add panoramic sunroof")
Build upon previous searches conversationally (e.g., first "BMW with automatic transmission", then "add navigation system")
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
View their search history with timestamps
Remove individual search queries from history
Clear entire search history
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

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

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

Wishlist Functionality

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

Save vehicles to a wishlist that persists between sessions (stored in browser localStorage)
Access saved vehicles through a floating wishlist button that appears in the UI
View all saved vehicles in a slide-out drawer
Select vehicles from their wishlist to send an inquiry
Remove vehicles from their wishlist
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

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

Comparison Functionality

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

Add up to 3 vehicles to a comparison list that persists between sessions (stored in browser localStorage)
Access the comparison view through a floating comparison button that appears in the UI
View all selected vehicles side by side in a modal for easy comparison
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)
Remove vehicles from the comparison
Navigate directly to vehicle detail pages from the comparison view
Responsive layout: 1 car (full width), 2 cars (50/50 split), 3 cars (equal thirds)
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

<div
  data-carpose-component="car-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

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

History Functionality

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

Automatically track all visited car detail pages (stored in browser localStorage)
Access visit history through a floating history button that appears in the UI
View all recently visited vehicles in a slide-out drawer (most recent first)
Navigate back to previously viewed vehicle detail pages
Clear the entire visit history
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

<div
  data-carpose-component="car-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)

<div
  data-carpose-component="car-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

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

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

Example with All Features Including Rates

<div
  data-carpose-component="car-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

Basic Example

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

Full Example with All Options

<div
  data-carpose-component="car-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

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

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

<!-- Form only - redirects to results page on submit -->
<div
  data-carpose-component="car-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)

<!-- Form + Results - displays results inline based on localStorage -->
<div
  data-carpose-component="car-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

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)

<!-- Only AI input - no filters shown, redirects to results page -->
<div
  data-carpose-component="car-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)

<!-- Full form + AI + Results - displays results with AI history available -->
<div
  data-carpose-component="car-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

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.
Form State Persistence:
- Form state is stored in browser localStorage with page-specific keys.
- State persists across page reloads and browser sessions.
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.
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.
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.
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.
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).
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.
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.
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.

PreviousDemo NextCar Search Small

Last updated 23 days ago