` carrying a `data-carpose-component` attribute and your API key. The library loads the component, renders it inside an isolated [Shadow DOM](/misc-modules/01_shadow-dom-architecture), and initialises it automatically. First, load the integration script once: ```html ``` Then drop in any component: ```html

``` Refer to each component's page for its specific configuration options. ## Colors & theming Every component accepts the same four theming attributes on its mount element — they are read centrally, so this works for each `data-carpose-component` without exception: | Attribute | Description | | ---------------------- | -------------------------------------------------- | | `data-primary-color` | Overrides the primary theme color for this mount | | `data-secondary-color` | Overrides the secondary theme color for this mount | | `data-accent-color` | Overrides the accent theme color for this mount | | `data-color-scheme` | `light`, `dark`, or `auto` (default) | The color values must be hex colors (`#31122d`); an invalid value is ignored with a console warning and the color configured in your Carposé account settings is used instead. Each override applies only to the component it is set on — other components on the same page keep the account colors. With `data-color-scheme="auto"` (or the attribute omitted), the widget follows the host page's theme: the `` element's `data-bs-theme`, `data-theme`, or `data-mui-color-scheme` attribute, or a `light`/`dark` class. The operating system's `prefers-color-scheme` is intentionally ignored — the widget follows your page, not the visitor's OS. Explicit `light` or `dark` pins the scheme. ```html

``` ## Components * [**Display & info components**](https://gitlab.com/carpose-de/dev-docs/-/tree/main/01_components/README.md) — image and 360° viewers, vehicle sliders, CO2 and consumption labels, wishlist, comparison, the budget calculator, and the floating-buttons overlay * [**Vehicle search modules**](https://gitlab.com/carpose-de/dev-docs/-/tree/main/02_vehicle-search-modules/README.md) — the full search form, compact and AI search, the configurator, types browser, and vehicle groups * [**Offer modules**](https://gitlab.com/carpose-de/dev-docs/-/tree/main/03_offer-modules/README.md) — promotional offer sliders and detail items * [**Events**](https://gitlab.com/carpose-de/dev-docs/-/tree/main/04_events/README.md) — the DOM events components emit, with integration examples, plus the built-in Google Tag Manager bridge and its [consent gate](/events/09_consent) * [**Misc modules**](https://gitlab.com/carpose-de/dev-docs/-/tree/main/05_misc-modules/README.md) — Shadow DOM architecture, [URL structure](/misc-modules/08_url-structure), static form values, stores (list, map, single), and employees ## Integrations * [**Inventory fragment**](/misc-modules/09_server-rendered-inventory) — the inventory as ready-made HTML a CMS plugin or template embeds server-side * [**React integration**](https://gitlab.com/carpose-de/dev-docs/-/tree/main/06_react-integration/README.md) — the standard script integration * [**Wix integration**](https://gitlab.com/carpose-de/dev-docs/-/tree/main/08_wix-integration/README.md) — embedding the vehicle search on Wix via a Custom Element * [**Model Context Protocol**](https://gitlab.com/carpose-de/dev-docs/-/tree/main/07_model-context-protocol/README.md) — exposing inventory data to AI assistants (experimental) # Image Slider Viewer ### Overview The `Image Slider` component displays a collection of images in an interactive carousel with thumbnail navigation and lightbox functionality. It provides a responsive and touch-friendly way to browse through multiple images of a vehicle or property. ### Installation The component is part of the Carpose application and requires no separate installation. ### Usage To use the Image Slider component in a standard HTML page: ```html

``` ### Configuration Attributes 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 "image-slider" | | `data-api-key` | string | - | API key for authentication with the Carpose backend services if images are fetched dynamically. | | `data-images` | string | - | Comma-separated list of image URLs to display in the slider. | | `data-slides-per-view` | number | 4 | Number of thumbnail slides to display per view. Adjust based on available space. | ### Features * Main image carousel with navigation controls * Thumbnail navigation below the main carousel * Lightbox gallery for fullscreen image viewing * Touch-friendly navigation for mobile devices * Pagination indicator showing current slide position * Responsive design that adapts to different screen sizes ### Example ```html

``` ### Behavior 1. **Image Display**: * The main carousel displays one image at a time with navigation arrows * Images can be navigated by swiping or using the navigation arrows * A pagination indicator shows the current position (e.g., "1/5") 2. **Thumbnail Navigation**: * Thumbnails are displayed below the main carousel * Clicking a thumbnail jumps directly to that image * The number of visible thumbnails is controlled by the `data-slides-per-view` attribute 3. **Lightbox Gallery**: * Clicking on the main image opens a fullscreen lightbox gallery * The lightbox allows for additional navigation and zoom functionality * Users can close the lightbox by clicking outside the image or using the close button 4. **Responsive Behavior**: * The component adapts to the container size * On smaller screens, the thumbnail view may show fewer thumbnails * Touch gestures are supported for navigation on mobile devices # 360° Interior Viewer ### Overview The `Interior Viewer` component displays an interactive 360° panoramic view of a vehicle's interior. It provides navigation controls for panning, zooming, and fullscreen viewing, allowing users to explore the interior of a vehicle in detail. ### Installation The component is part of the Carpose application and requires no separate installation. ### Usage To use the Interior Viewer component in a standard HTML page: ```html

``` ### Configuration Attributes 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 "interior-viewer" | | `data-api-key` | string | - | API key for authentication with the Carpose backend services. Required for data fetching. | | `data-identifier` | string | - | Identifier for the interior panorama image. Required if car-id is not provided. | | `data-vehicle-id` | string | - | ID of the car to display interior panorama for. Required if identifier is not provided. | ### Features * Interactive 360° panoramic view of vehicle interiors * Navigation controls for: * Panning up, down, left, and right * Zooming in and out * Fullscreen viewing (on non-mobile devices) * Loading indicator while panorama is being fetched * Fallback screen when no interior panorama is available * Overlay with usage hints ### Example ```html

``` ### Behavior 1. **Data Loading**: * On initialization, the component fetches the interior panorama data from the API using either the provided identifier or car ID. * A loading screen is displayed while the image is being loaded. * If no panorama is available, a message is displayed indicating that no 360° interior view is available. 2. **Navigation Controls**: * Arrow buttons allow panning up, down, left, and right * Plus/minus buttons control zoom level * Fullscreen button toggles fullscreen mode (not available on mobile devices) * Users can also navigate by dragging the panorama with their mouse or touch gestures 3. **Responsive Behavior**: * The component adapts to the container size * Controls are accessible on both desktop and mobile devices * Fullscreen option is automatically disabled on mobile devices # 360° Exterior Viewer ### Overview The `Exterior Viewer` component displays an interactive 360° view of a vehicle's exterior. It provides navigation controls for rotating the vehicle, autoplay functionality, and fullscreen viewing, allowing users to examine the exterior of a vehicle from all angles. ### Installation The component is part of the Carpose application and requires no separate installation. ### Usage To use the Exterior Viewer component in a standard HTML page: ```html

``` ### Configuration Attributes 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 "exterior-viewer" | | `data-api-key` | string | - | API key for authentication with the Carpose backend services. Required for data fetching. | | `data-identifier` | string | - | Identifier for the exterior images. Required if car-id is not provided. | | `data-vehicle-id` | string | - | ID of the car to display exterior view for. Required if identifier is not provided. | ### Features * Interactive 360° view of vehicle exteriors * Navigation controls for: * Rotating left and right * Autoplay with play/pause functionality * Fullscreen viewing (on non-mobile devices) * Loading indicator while images are being fetched * Fallback screen when no exterior images are available * Overlay with usage hints * Event notifications when viewer loads successfully or encounters errors ### Example ```html

``` ### Behavior 1. **Data Loading**: * On initialization, the component fetches the exterior images from the API using either the provided identifier or car ID. * A loading screen is displayed while the images are being loaded. * If no images are available, a message is displayed indicating that no 360° exterior view is available. * The component triggers custom events to notify parent components of successful loading or errors. 2. **Navigation Controls**: * Left/right arrow buttons allow rotating the vehicle view * Play/pause button toggles automatic rotation * Fullscreen button toggles fullscreen mode (not available on mobile devices) * Users can also navigate by dragging the view with their mouse or touch gestures 3. **Responsive Behavior**: * The component adapts to the container size * Controls are accessible on both desktop and mobile devices * Fullscreen option is automatically disabled on mobile devices 4. **Events**: * `carpose-vehicle-viewer-load`: Triggered when the viewer loads successfully. `data.viewer` is `"exterior"`. * `carpose-vehicle-viewer-unavailable`: Triggered when no exterior images are available, or when the media fetch fails. `data.viewer` is `"exterior"`; `data.reason` distinguishes "no media at all" (`no-media`) from "fetch failed" (`fetch-failed`). `detail.component` reports whichever widget this viewer is mounted inside (e.g. `exterior-viewer` when mounted standalone as above, or `vehicle-detail` when it's nested inside the vehicle detail view) — it no longer doubles as the failure-mode discriminator. See [Vehicle Search: Viewer](/events/02_vehicle-search#viewer) for the full event reference. # Vehicle Slider {% hint style="info" %} The Vehicle Slider displays a carousel of inventory vehicles, ordered randomly or by newest first. {% endhint %} ## Introduction The `vehicle-slider` component renders an interactive carousel of vehicles from your inventory. It is ideal for showcasing featured vehicles on landing pages or highlighting specific stock. ## Basic Usage ```html

``` ## Attributes | Attribute | Required | Description | | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | | `data-carpose-component` | Yes | Must be `vehicle-slider` | | `data-api-key` | Yes | Your Carposé API key | | `data-ordering` | No | Order of vehicles, `random` or `latest` (default `random`) | | `data-search-url-forward` | No | Search page a vehicle opens on when clicked. Overrides the `vehicleSearchMainPageUrl` setting for this slider only. | | `data-primary-color` | No | Per-mount color override | | `data-secondary-color` | No | Per-mount color override | | `data-accent-color` | No | Per-mount color override | The slider always shows up to 10 vehicles. ## Forwarding to a Search Page The slider is meant for pages that carry no vehicle search of their own — a homepage, a landing page. Clicking a card there cannot open the vehicle in place, so the browser is sent to your search page with the vehicle deep-linked (`?vehicle=…`), which opens it directly. That target is normally the **Vehicle Search Main Page URL** configured in your Carposé settings. `data-search-url-forward` overrides it for a single slider — useful when a landing page should lead into a specific search page rather than the default one. ```html

``` The value may be absolute (`https://example.de/fahrzeugsuche`) or site-relative (`/fahrzeugsuche`); a relative path is resolved against the page the slider sits on. Only `http` and `https` targets are accepted — anything else is ignored, and the configured setting is used instead. The attribute affects this slider's cards only. Other Carposé components on the same page keep following the configured setting. ## Behavior * Fetches vehicles from your inventory based on the configuration * Carousel with touch/swipe support and navigation arrows * Responsive and lazy-loads images ## Notes * Hidden if no vehicles match the criteria * See also Vehicle Similarity Slider for "you may also like" carousels # Vehicle Similarity Slider {% hint style="info" %} The Vehicle Similarity Slider shows vehicles similar to a given vehicle — a "you may also like" carousel. {% endhint %} ## Introduction The `vehicle-similarity-slider` component fetches vehicles similar to a reference vehicle (based on its specifications) and renders them in a responsive carousel with bullet pagination. ## Basic Usage ```html

``` ## Attributes | Attribute | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------ | | `data-carpose-component` | Yes | Must be `vehicle-similarity-slider` | | `data-api-key` | Yes | API key for authentication with the Carposé backend services | | `data-id` | Yes | ID of the reference vehicle to find similar vehicles for | ## Behavior * Fetches similar vehicles from the API based on the reference vehicle's specifications * Renders a carousel with bullet pagination — 3 slides per view on desktop, 1 on mobile * Each card links to the corresponding vehicle detail page ## Notes * Requires a valid `data-id`; nothing is shown if there are no similar vehicles * Pairs well with a vehicle detail page # CO2 Class Label ### Overview The `CO2 Class Label` component displays a vehicle's CO2 efficiency classification using a standardized energy label. It fetches the CO2 class data from the API and presents it with an explanatory headline and description. ### Installation The component is part of the Carpose application and requires no separate installation. ### Usage To use the CO2 Class Label component in a standard HTML page: ```html

``` ### Configuration Attributes 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 "co2-class-label" | | `data-api-key` | string | - | API key for authentication with the Carpose backend services. Required for data fetching. | | `data-vehicle-id` | string | - | ID of the car for which to display the CO2 class. | | `data-type` | string | - | Which CO2 class to show: `combined`, `weightedCombined` (plug-in hybrids, weighted combined) or `emptyBattery` (plug-in hybrids, discharged battery). Required; an unknown value renders nothing and logs an error. | | `data-headline` | string | "CO2-Effizienzklasse" | Headline text displayed above the efficiency label. | ### Features * Displays a vehicle's CO2 efficiency class (A+, A, B, C, D, E, F, G) * Shows explanatory text about how the classification is determined * Fetches data dynamically from the Carpose API * Responsive layout that adapts to different screen sizes ### Example ```html

``` ### Behavior 1. **Data Loading**: * On initialization, the component fetches the CO2 class data from the API using the provided car ID and type. * If the specified type doesn't exist in the API response, an error is logged to the console. * The component doesn't render anything if the CO2 class data cannot be retrieved. 2. **Display**: * When data is successfully loaded, the component displays: * The headline specified in the `data-headline` attribute * A standard explanatory text about how the CO2 class is determined * The energy efficiency label (A+ to G) based on the fetched data 3. **Responsive Behavior**: * The component adapts to different screen sizes * On larger screens, it typically occupies one-third of the available width * On smaller screens, it takes up half or full width depending on the viewport size # Consumption Box ### Overview The `Consumption Box` component displays comprehensive fuel consumption, emission, and efficiency information for vehicles. It dynamically adapts the displayed information based on the vehicle's powertrain type (combustion, electric, or plug-in hybrid). ### Installation The component is part of the Carpose application and requires no separate installation. ### Usage To use the Consumption Box component in a standard HTML page: ```html

``` ### Configuration Attributes 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 "consumption-box" | | `data-api-key` | string | - | API key for authentication with the Carpose backend services. Required for data fetching. | | `data-vehicle-id` | string | - | ID of the car for which to display consumption information. | ### Features * Dynamically displays different consumption information based on the vehicle type * For combustion engine vehicles: * CO₂ class (combined) * Emission class information * Fuel consumption values * For plug-in hybrid vehicles: * CO₂ class (combined, weighted combined, and with empty battery) * Emission class information * Fuel consumption with empty battery * Electric range * For electric vehicles: * CO₂ class (combined) * Emission class information * Power consumption * Electric range * Includes standardized legal disclaimer about consumption measurement methods ### Example ```html

``` ### Behavior 1. **Data Loading**: * On initialization, the component fetches the car details from the API using the provided car ID. * The component only renders if the car has consumption data available. 2. **Dynamic Content**: * The component determines the powertrain type (combustion, electric, or plug-in hybrid) of the vehicle. * Based on the powertrain type, it displays the appropriate consumption information components. * Each sub-component fetches its specific data as needed. 3. **Component Structure**: * The component displays a header "Detaillierte Verbrauchswerte" (Detailed Consumption Values). * It then renders different combinations of sub-components based on the vehicle type. * A standardized legal disclaimer is displayed at the bottom with information about the measurement methods. 4. **Responsive Behavior**: * The component adapts to different screen sizes. * On larger screens, information is displayed in a multi-column layout. * On smaller screens, information stacks vertically for better readability. # Wishlist {% hint style="warning" %} The Wishlist is a **feature of the** [**Vehicle Search Form**](/vehicle-search-modules/01_vehicle-search-form), not a standalone embeddable component. There is no `data-carpose-component="wishlist"` — it is enabled with the `data-wishlist` attribute on the search form. {% endhint %} ## Introduction When wishlist functionality is enabled, visitors can save vehicles to a favourites list that persists between sessions (stored in the browser's `localStorage`). A floating wishlist button gives access to a slide-out drawer of saved vehicles, from which the visitor can send an inquiry, remove vehicles, or open a vehicle's detail page. ## Enabling the Wishlist ```html

``` ## Behavior * A wishlist button appears on each vehicle card, and a floating wishlist button gives access to the saved-vehicles drawer * Wishlist state persists across sessions via `localStorage` * Visitors can send inquiries for multiple saved vehicles at once * Success messages are shown when adding or removing vehicles ## Notes * The wishlist is stored per-browser; no account is required * See also [Vehicle Comparison](/components/09_vehicle-comparison), which can be enabled alongside the wishlist * For the full list of search-form options, see the [Vehicle Search Form](/vehicle-search-modules/01_vehicle-search-form) # Vehicle Comparison {% hint style="warning" %} Vehicle Comparison is a **feature of the** [**Vehicle Search Form**](/vehicle-search-modules/01_vehicle-search-form), not a standalone embeddable component. There is no `data-carpose-component="comparison"` — it is enabled with the `data-compare` attribute on the search form. {% endhint %} ## Introduction When comparison is enabled, visitors can add up to **3 vehicles** to a comparison list (persisted in `localStorage`) and view them side by side in a modal. The comparison shows key specifications — price and VAT, registration date and mileage, power and engine, transmission and fuel type, and additional specs. ## Enabling Comparison ```html

``` ## Behavior * A comparison button appears on vehicle cards and detail pages (including an icon overlay on thumbnails), and a floating comparison button opens the side-by-side view * Comparison state persists across sessions via `localStorage` * Responsive layout: 1 vehicle (full width), 2 vehicles (50/50), 3 vehicles (equal thirds); mobile uses a horizontal scroll view * A warning is shown when trying to add more than 3 vehicles ## Notes * Can be combined with the [Wishlist](/components/08_wishlist) (`data-wishlist="true"`) * For the full list of search-form options, see the [Vehicle Search Form](/vehicle-search-modules/01_vehicle-search-form) # Budget Calculator {% hint style="warning" %} The Budget Calculator is a **feature of the** [**Vehicle Search Form**](/vehicle-search-modules/01_vehicle-search-form), not a standalone embeddable component. There is no `data-carpose-component="budget-calculator"` — it is enabled with the `data-budget-calculator` attribute on the search form. {% endhint %} ## Introduction When the budget calculator is enabled, a floating button gives visitors access to a financing calculator. It lets a visitor work out an estimated monthly rate while browsing search results. ## Enabling the Budget Calculator ```html

``` ## Behavior * A floating button gives access to the calculator from anywhere in the search results * Opens the calculator without leaving the search results * The calculation is an estimate only and is not a binding financing offer ## Notes * Can be combined with other search-form features (wishlist, comparison, history, rates) * For the full list of search-form options, see the [Vehicle Search Form](/vehicle-search-modules/01_vehicle-search-form) # Floating Buttons {% hint style="info" %} The floating buttons are a page-level overlay (in a corner of the screen) that gives visitors quick access to actions such as live chat, your custom links, the purchase-request and test-drive wizards, and — where a vehicle search is on the page — wishlist, comparison, history, and the AI assistant. {% endhint %} ## Overview The floating-buttons overlay can show: * **Custom menu entries** — links and grouped buttons that you configure in the Carposé dashboard (label, icon, URL). * **Live chat** — a chat button backed by Brevo, when enabled for your account. * **Built-in feature buttons** — wishlist, history, comparison, budget calculator, and the AI assistant, shown according to your account settings and what is present on the page. * **Wizard buttons** — "Fahrzeug verkaufen" opens the [Purchase Request Form](/components/12_purchase-request-form) and "Probefahrt buchen" opens the [Test Drive Form](/components/13_test-drive-form), each in a dialog. See [Wizard buttons](#wizard-buttons) below. What appears in the overlay is configured by the dealer in the Carposé dashboard. On the page you only enable the overlay and, optionally, override the theme colors. ## Adding the overlay There are two ways to add the overlay to a page. ### Option 1 — from the integration script (recommended) Add the `data-carpose-floating-buttons` attribute (and your API key) directly to the integration script tag. The overlay is then mounted automatically — no extra element is needed: ```html ``` ### Option 2 — as a mount element Like any other component, you can also place an explicit mount `

`: ```html

``` Only one floating-buttons overlay is shown per page. ## Configuration Attributes | Attribute | Where | Required | Default | Description | | ------------------------------- | -------------------- | -------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `data-api-key` | script tag / element | Yes | — | Your Carposé API key | | `data-carpose-floating-buttons` | script tag | Yes (Option 1) | — | Its presence mounts the overlay. Set it to `"false"` to force the overlay off (for example on pages where you don't want it). | | `data-primary-color` | script tag / element | No | account default | Override the primary theme color | | `data-secondary-color` | script tag / element | No | account default | Override the secondary theme color | | `data-accent-color` | script tag / element | No | account default | Override the accent theme color | | `data-color-scheme` | script tag / element | No | account default | `"light"` or `"dark"` | | `data-purchase-request` | script tag / element | No | account default | `"true"` / `"false"` — show the "Fahrzeug verkaufen" button. See [Wizard buttons](#wizard-buttons) | | `data-test-drive` | script tag / element | No | `false` | `"true"` / `"false"` — show the "Probefahrt buchen" button. See [Wizard buttons](#wizard-buttons) | ## Wizard buttons Two of the wizards can be reached from the overlay instead of, or in addition to, an embed of their own. Opened this way they always use their default copy, every optional step switched on, and no success redirect, and they take the privacy link from your account settings — there is no mount element whose attributes they could read. | Attribute | Button | Default | | ----------------------- | -------------------- | -------------------- | | `data-purchase-request` | "Fahrzeug verkaufen" | Your account setting | | `data-test-drive` | "Probefahrt buchen" | Off | Both go on the floating-buttons script tag or element and take `"true"` or `"false"`, overriding the account setting for that page: ```html ``` Events from a wizard opened here carry `component: "floating-buttons"` rather than the wizard's own component name. ## Live chat Live chat is provided through **Brevo**. It is enabled and configured (provider and account ID) by the dealer in the Carposé dashboard. When enabled, a chat button appears in the overlay; clicking it opens the Brevo chat widget. No extra code is required on your side — including the integration script is enough. ## Notes * Custom menu entries (links and groups) are managed entirely in the Carposé dashboard; only `http://` and `https://` links are allowed. * The wishlist, comparison, history, budget calculator, and AI assistant buttons appear based on your account settings (and, for some, whether a vehicle search component is on the page). See the [Vehicle Search Form](/vehicle-search-modules/01_vehicle-search-form) for those features. # Purchase Request Form {% hint style="info" %} The purchase request form ("Ankaufanfrage") is a four-step wizard in which a visitor offers you their own vehicle. They describe the car, its condition, optionally upload photos, and leave their contact details — you receive the enquiry as a lead. {% endhint %} ## Overview This is the reverse of a vehicle enquiry: the visitor is the seller and you are the buyer. The wizard collects, step by step: 1. **Fahrzeug** — make, model, first registration and mileage, plus optional details behind a "Weitere Angaben" disclosure (variant, fuel type, transmission, power, engine displacement, body type, colour, doors, seats, VIN, HSN/TSN, licence plate, previous owners). 2. **Zustand** — accident damage and, if affirmed, a free-text damage description; exterior and technical condition, next inspection, service history, tyre set, roadworthiness, non-smoker, and equipment features. 3. **Fotos** — optional photo upload (can be switched off entirely). 4. **Kontakt** — price expectation, desired selling period, any outstanding financing, the location selector, a free-text message, and the seller's contact details. Only eight fields are mandatory: make, model, month **and** year of first registration, mileage, first name, last name, e-mail address, and the privacy consent checkbox. Everything else is optional, so a visitor can send a usable enquiry in under a minute. The wizard will not let a visitor skip forward past a step whose required fields are incomplete. Going back is always possible via the "Zurück" button; on viewports of 768px and wider the progress bar additionally renders as a stepper whose completed steps are clickable. Below that width it is a plain progress bar with a "Schritt n von m" caption, so "Zurück" is the only way back. ## Adding the form ### Option 1 — inline The wizard renders directly in the page: ```html

``` ### Option 2 — behind a button Set `data-variant="modal"` and the page shows only a button; the wizard opens in a dialog: ```html

``` ### Option 3 — from the floating buttons The wizard can also be reached from the [floating-buttons overlay](/components/11_floating-buttons) as a "Fahrzeug verkaufen" button. Enable it for your account in the Carposé dashboard, or override that per page by putting `data-purchase-request="true"` (or `"false"`) on the floating-buttons script tag or element — see [Wizard buttons](/components/11_floating-buttons#wizard-buttons). Opened this way the wizard uses its default copy and takes the privacy link from your account settings, since there is no mount element to read attributes from. ## Configuration Attributes | Attribute | Required | Default | Description | | ------------------- | -------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `data-api-key` | Yes | — | Your Carposé API key | | `data-variant` | No | `inline` | `inline` renders the wizard in place; `modal` renders a button that opens it in a dialog | | `data-title` | No | `Fahrzeug verkaufen` | Headline above the wizard | | `data-subtitle` | No | `Sagen Sie uns, was Sie fahren — wir melden uns mit einem Angebot.` | Intro line. Set it to an empty value (`data-subtitle=""`) to hide it — that is different from omitting the attribute, which keeps the default | | `data-button-label` | No | `Fahrzeug verkaufen` | Caption of the trigger button, for `data-variant="modal"`. Note this falls back to the built-in default, **not** to your `data-title` — set both if you want a custom caption on the button as well | | `data-photo-upload` | No | `true` | `"false"` removes the photo step entirely, leaving a three-step wizard | | `data-store-select` | No | `true` | `"false"` hides the location selector. With the selector on, a single location is assigned silently and only two or more locations produce a visible choice | | `data-success-url` | No | — | Redirect here after a successful submission instead of showing the confirmation panel. Only `http://` and `https://` URLs are accepted | | `data-privacy-url` | No | — | Target of the link in the privacy consent checkbox. Only `http://` and `https://` URLs are accepted. Omitting it does not remove the checkbox — consent stays mandatory — but its label then renders as plain text with nothing to click, so set it on every embed | ## Photos When the photo step is enabled, the visitor can attach images of the vehicle by picking them or dropping them onto the step. The wizard checks each file before anything is sent and names the ones it turns away: | Limit | Value | | ---------------- | ------------------ | | Formats | JPEG, PNG and WebP | | Size per file | 10 MB | | Number of images | 12 | The server applies its own ceiling on top of that and may accept fewer. Photos are uploaded **after** the enquiry itself has been stored, so a failed upload never costs you the lead — the confirmation tells the visitor which images did not go through and that you will be in touch regardless. Because the upload runs before the wizard reports success, it also delays the success event and any `data-success-url` redirect; see [the success event](/events/02_vehicle-search#vehicle-purchase-form-success-event). ## After submission On success the visitor sees a confirmation panel and receives an e-mail acknowledgement; the enquiry appears among your leads in the Carposé dashboard. If you set `data-success-url`, the visitor is redirected there instead. If the same visitor sends many requests in a short time, the server rate-limits them and the wizard shows a message asking them to try again in a few minutes. ## Events The wizard dispatches `carpose-vehicle-purchase-form-*` events for open, step, submit, success and error. See [Vehicle Search events](/events/02_vehicle-search#purchase) for the payloads. ## Notes * All wizard copy is German. * The form renders inside a Shadow DOM, so your page styles cannot affect it and its styles cannot leak out. It does inherit your page's font family on purpose, so it blends into your typography. See [Shadow DOM Architecture](/misc-modules/01_shadow-dom-architecture). * More than one purchase request form can be placed on the same page — for example an inline one and a modal trigger. # Test Drive Booking {% hint style="info" %} The test-drive booking wizard lets a visitor pick a car from your test-drive fleet, choose a free day and time, and leave their contact details. You receive the appointment as a booking request and confirm it. {% endhint %} ## Overview The wizard has three steps: 1. **Fahrzeug** — a tile grid of every vehicle in your test-drive fleet, each with its photo and name. The visitor picks one. 2. **Termin** — the days that still have free slots for that vehicle, and the free times on the chosen day. The first bookable day is preselected, and the expected duration is shown next to the times. 3. **Kontakt** — salutation, first and last name, e-mail, optional phone number and message, and the privacy consent checkbox. First name, last name, a valid e-mail address and the consent checkbox are mandatory; everything else is optional. Availability is loaded per vehicle from your fleet's real calendar, so a visitor only ever sees times that are genuinely free. If someone books a slot while another visitor is filling in the form, the second visitor is returned to the appointment step with a refreshed list of times rather than losing what they typed. A new booking is created with the status **pending** — it is a request, not a confirmed appointment. The visitor sees a summary of the vehicle, date and time, plus a note that you will confirm by e-mail. ## Adding the wizard ### Option 1 — inline ```html

``` ### Option 2 — behind a button ```html

``` ### Option 3 — from the floating buttons The wizard can also open from the [floating-buttons overlay](/components/11_floating-buttons) as a "Probefahrt buchen" button. Put `data-test-drive="true"` on the floating-buttons script tag or element to switch it on for a page — see [Wizard buttons](/components/11_floating-buttons#wizard-buttons). Opened this way the wizard uses its default copy and takes the privacy link from your account settings, since there is no mount element to read attributes from. ## Configuration Attributes | Attribute | Required | Default | Description | | --------------------- | -------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data-api-key` | Yes | — | Your Carposé API key | | `data-variant` | No | `inline` | `inline` renders the wizard in place; `modal` renders a button that opens it in a dialog | | `data-title` | No | `Probefahrt buchen` | Headline above the wizard | | `data-subtitle` | No | `Wählen Sie ein Fahrzeug und einen Termin — wir bestätigen Ihnen die Probefahrt.` | Intro line. Set it to an empty value (`data-subtitle=""`) to hide it — that is different from omitting the attribute, which keeps the default | | `data-button-label` | No | `Probefahrt buchen` | Caption of the trigger button, for `data-variant="modal"`. Note this falls back to the built-in default, **not** to your `data-title` — set both if you want a custom caption on the button as well | | `data-vehicle-layout` | No | `tiles` inline, `list` in the modal | How the first step presents the fleet: `tiles` (photo-led cards) or `list` (one row per vehicle). The dialog defaults to a list because tiles need more width than it offers; set the attribute to force either layout. An unknown value falls back to the variant's default | | `data-success-url` | No | — | Redirect here after a successful booking instead of showing the confirmation. Only `http://` and `https://` URLs are accepted | | `data-privacy-url` | No | — | Target of the link in the privacy consent checkbox. Only `http://` and `https://` URLs are accepted | ## Your fleet The vehicles shown are the **active** vehicles in your test-drive fleet, managed in the Carposé dashboard — this is a separate list from your vehicle inventory. Their photos and booking calendars come from the same place. Two states are worth knowing, because neither is an error: * **No vehicles at all** — the wizard says that no cars are currently available for a test drive. Check that your fleet has at least one active vehicle. * **A vehicle with no free slots** — picking it reaches the appointment step and reports that no dates are currently available. The visitor can go back and choose another car. If the fleet itself cannot be loaded, the wizard shows an error with a retry button. ## Events The wizard dispatches `carpose-vehicle-test-drive-*` events for open, step, submit, success and error. See [Vehicle Search events](/events/02_vehicle-search#test-drive) for the payloads. ## Notes * All wizard copy is German. * The wizard renders inside a Shadow DOM, so your page styles cannot affect it and its styles cannot leak out. It does inherit your page's font family on purpose, so it blends into your typography. See [Shadow DOM Architecture](/misc-modules/01_shadow-dom-architecture). * This is the standalone fleet wizard. Booking a test drive for one specific vehicle from an offer page is a separate flow — see [Offer Item](/offer-modules/02_offer-item). * More than one test-drive wizard can be placed on the same page — for example an inline one and a modal trigger. # 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 The component is part of the Carpose application and requires no separate installation. ### Usage To use the VehicleSearchForm component in a standard HTML page, you only need two required attributes: ```html

``` This minimal setup will display a search form with inline results. See the [Examples](#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 "vehicle-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"). | | `data-ai-only` | boolean | false | When true (and `data-ai-assistant="true"`), collapses the form to show only the AI natural-language input — all filter selects, buttons, and the floating AI button are hidden. Ideal for a dedicated AI search landing page. Has no effect unless the AI assistant is enabled. | | `data-contextual-count` | boolean | false | When true, each filter dropdown (manufacturer, model, fuel type, condition, vehicle type, engine type, colour, store) shows a live count of how many vehicles match each option given the other currently active filters. When false, options are shown without counts. | | `data-infinite-scroll` | boolean | false | When true, replaces the numbered pagination control with infinite scroll: the next page of results loads automatically as the user scrolls near the bottom of the list. Already-loaded cards stay interactive while the next page loads. When false (default), results use numbered pagination. | | `data-price-alert` | boolean | false | When true, enables the price-alert feature: visitors can subscribe with their name and email to be notified when a vehicle's price changes. | | `data-used-car-energy-costs` | boolean | false | When true, the estimated yearly energy/fuel cost box is also shown for used cars. By default this box is only displayed for new cars. | | `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`. | | `data-url-mode` | string | `query` | URL form the listing writes: `query` (`?vehicle=…`, `?cp-page=2`) or `path` (`/fahrzeug/…/`, `/seite/2/`). Only an explicit `path` switches the form; every other value is `query`. Overrides the account setting. The path form requires sub-path routing on your website — see [URL Structure](/misc-modules/08_url-structure). | | `data-base-path` | string | derived | Base path the listing URLs are built on. Derived from the current URL when omitted, which is correct whenever the widget sits on the page its links point at. Set it only for an embed whose links have to lead to a different search page. | | `data-url-slug-only` | boolean | false | When true, vehicles are addressed by their slug alone (`?vehicle=audi-q3-s-line`) instead of `{slug}--{uuid}`. Requires former slugs to stay resolvable — see [URL Structure](/misc-modules/08_url-structure). | | `data-card-variant` | string | `classic` | Card layout for result cards: `classic` (portrait card, image on top), `compact` (dense portrait card for high-density grids) or `horizontal` (full-width row, image left, price right). | | `data-heading-level` | string | `2` | Heading level the vehicle names render at: `"2"`, `"3"` or `"4"` (an `h` prefix is accepted). No card ever emits an `h1` — pick the level that continues your page outline without skipping one. | {% hint style="info" %} **Account-level defaults.** The boolean feature flags (`data-rates`, `data-ai-assistant`, `data-ai-only`, `data-contextual-count`, `data-wishlist`, `data-compare`, `data-history`, `data-price-alert`, `data-used-car-energy-costs`, `data-infinite-scroll`) can also be enabled centrally for your account. When the corresponding `data-*` attribute is present on the element it always wins; when it is omitted, the value configured on your Carpose account is used instead. Set the attribute explicitly to `"false"` to force a feature off even when it is enabled account-wide. {% endhint %} ### 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 * Contextual per-option result counts on filters (when enabled) * Reset button to clear all filters * Pagination for search results, or infinite scroll as an alternative (when enabled) * 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) * Price-alert subscriptions for individual vehicles (when enabled) * Estimated yearly energy/fuel costs shown for used cars (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: 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 After a successful AI search, the matching filters are applied to the form automatically and the page scrolls to the results. #### 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 ```html

``` ### Wishlist Functionality 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 A floating wishlist button gives access to the saved-vehicles drawer whenever the wishlist is enabled. #### Example with Wishlist Enabled ```html

``` ### Comparison Functionality 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 A floating comparison button opens the side-by-side comparison modal whenever comparison is enabled. #### Example with Comparison Enabled ```html

``` #### Example with Both Wishlist and Comparison Enabled ```html

``` ### History Functionality 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 Visited vehicles are tracked automatically, and a floating history button opens the recently-viewed drawer whenever history is enabled. #### Example with History Enabled ```html

``` #### Example with All Features Enabled (AI Assistant, Wishlist, Comparison, and History) ```html

``` ### 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 ```html

``` #### Example with All Features Including Rates ```html

``` ### Contextual Counts Functionality When contextual counts are enabled via the `data-contextual-count="true"` attribute, each filter option shows how many vehicles would match if it were selected, taking the other active filters into account: * Counts are displayed next to the options in the manufacturer, model, fuel type, condition, vehicle type, engine type, colour, and store filters. * Counts update as the user changes other filters, so they always reflect the current search context. * The count for a given filter ignores that filter's own current selection (so the user can see all available options), but respects every other active filter. * Helps users avoid selecting combinations that would return zero results. #### Example with Contextual Counts Enabled ```html

``` ### Infinite Scroll Functionality When infinite scroll is enabled via the `data-infinite-scroll="true"` attribute, the numbered pagination control is replaced by automatic loading: * As the user scrolls toward the bottom of the results list, the next page is fetched and appended automatically. * Already-loaded cards stay fully interactive while the next page loads; a loading spinner is shown at the bottom of the list. * Loading stops once the last page has been reached. * On a full page reload the list resets to the first page. When the attribute is omitted or set to `"false"` (default), results use the standard numbered pagination control instead. #### Example with Infinite Scroll Enabled ```html

``` ### Price Alert Functionality When the price-alert feature is enabled via the `data-price-alert="true"` attribute, visitors can subscribe to price-change notifications for a specific vehicle: * A price-alert action opens a modal where the visitor enters their name and email address and accepts the privacy policy. * On submission, the subscription is registered with the Carpose backend. * The visitor is notified by email when the vehicle's price changes. #### Example with Price Alert Enabled ```html

``` ### Used Car Energy Costs Functionality The estimated yearly energy/fuel cost box (part of the consumption display) is shown for new cars by default. When `data-used-car-energy-costs="true"` is set, the same estimate is also displayed for used cars: * Shows an estimated yearly energy or fuel cost based on the vehicle's consumption data. * Only affects used vehicles; new vehicles always show the estimate regardless of this attribute. * Has no effect on vehicles that do not have consumption data. #### Example with Used Car Energy Costs Enabled ```html

``` ### Examples #### Basic Example ```html

``` #### Full Example with All Options ```html

``` #### Two-Page Setup Example When using `data-search-url-forward`, you need two pages: **Page 1: Search Form (e.g., /index.html)** ```html

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

``` 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, add `data-ai-only="true"` so the form collapses to just the AI input and (together with `data-search-url-forward`) redirects to a results page: **Page 1: AI Search Landing Page (e.g., /ai-search.html)** ```html

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

``` 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 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 (`data-ai-only="true"` together with `data-ai-assistant="true"`):** * Only the AI input field is shown — all filter selects, buttons, and controls (including the floating AI button) are hidden. * Each search is independent (no conversational context between queries). * When combined with `data-search-url-forward`, a successful search saves the form state and AI query to localStorage and redirects to the target page, which loads with the AI history and results already available. * This mode is ideal for a dedicated AI search landing page that redirects to a results page. 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 9 items per page. * Pagination controls are shown at the bottom of the results when there are multiple pages. 11. **Contextual Counts Behavior**: * Enable per-option result counts with `data-contextual-count="true"`. * Each filter option shows how many vehicles match it given the other active filters. * A filter's own current selection is ignored when computing its counts; all other active filters are respected. * Counts refresh whenever the surrounding filters change. 12. **Infinite Scroll Behavior**: * Enable infinite scroll with `data-infinite-scroll="true"`. * Replaces the numbered pagination control; the next page loads automatically as the user nears the bottom of the list. * Already-loaded cards remain interactive while the next page loads. * Loading stops once the last page has been reached. * On a full page reload the list resets to the first page. 13. **Price Alert Behavior**: * Enable price-alert subscriptions with `data-price-alert="true"`. * Opens a modal where the visitor submits their name, email, and privacy consent. * The visitor is notified by email when the vehicle's price changes. 14. **Used Car Energy Costs Behavior**: * Enable used-car energy/fuel cost estimates with `data-used-car-energy-costs="true"`. * The estimated yearly energy/fuel cost box is shown for new cars by default; this attribute extends it to used cars. * Has no effect on vehicles without consumption data. ### Live Attribute Updates The search form watches its own `data-*` attributes after it has mounted. If you change an attribute at runtime — for example toggling `data-wishlist` from `"false"` to `"true"` from your own JavaScript — the form picks up the change and re-applies the affected feature without a page reload. ### Deep-Linking & SEO #### Linking directly to a vehicle The search reads a `vehicle` query parameter from the page URL and opens that vehicle's detail view automatically. Use it to link or share a direct link to a specific vehicle: ``` https://your-site.example/search?vehicle=audi-q3-s-line--efbb7d07-0101-11f0-8de6-960000658564 ``` The parameter value follows the `{slug}--{uuid}` pattern — a human-readable slug, two dashes, then the vehicle UUID. The bare UUID works on its own too (`?vehicle=efbb7d07-0101-11f0-8de6-960000658564`); the slug is optional and only improves readability and SEO. Any other query parameters already on the URL (such as `utm_*` tracking) are preserved. #### Linking to a result page The current page of the result list is written to the URL the same way, as `cp-page`: ``` https://your-site.example/search?cp-page=2 ``` Every page of the listing is a real link, so a crawler can follow the results past the first page and a shared link opens the page it names. Page 1 carries no parameter, so the first page keeps exactly one address. The parameter is namespaced as `cp-page` rather than `page` because content management systems commonly reserve `page` for their own pagination. #### Path URLs instead of query parameters Both states can also ride in the path instead of the query string — `/fahrzeug/{slug}--{uuid}/` and `/seite/2/`. This is an account setting, and can be overridden per embed with `data-url-mode="path"`. It requires your website to route those sub-paths back to the page holding the search; the query form works everywhere and stays the default. See [URL Structure](/misc-modules/08_url-structure) for both forms, the host requirements and the order to follow when switching an existing search over. #### Structured data (JSON-LD) When a vehicle's detail view is shown, the component automatically injects [schema.org](https://schema.org) vehicle structured data as a JSON-LD ` ``` ### How the two combine | `data-carpose-google-analytics-tracking` | Result | | ---------------------------------------- | ------------------------------------------------ | | `"true"` | Bridge active, whatever the account setting says | | `"false"` | Bridge off, whatever the account setting says | | present but empty, or absent | The account setting decides — off by default | {% hint style="info" %} "Active" means the bridge is listening — not that anything is sent. Every single push is additionally gated by consent. Tracking enabled plus no consent still means no tracking. {% endhint %} The attribute is namespaced per destination. Further tracking destinations will get their own setting and their own attribute, so they can be switched independently. ## How consent is handled The bridge **fails closed**. Under GDPR Art. 6(1)(a) and §25 TDDDG analytics requires prior opt-in, so no consent signal is treated as refusal, never as permission. * **Nothing is forwarded until analytics consent is granted.** The listeners attach immediately — they store nothing — but each forward is checked at the moment the event fires. * **Events fired before consent are dropped permanently.** They are never buffered and never replayed. A visitor who accepts halfway through a session is measured from that point on, not retroactively. * **Withdrawal takes effect immediately**, on the next event, without a page reload. * **The consent check itself writes no cookies and no storage.** It reads the consent state fresh on every page load. * **There is no bypass.** No attribute, setting or global switches the gate off. {% hint style="info" %} This is stricter than delegating to Google Consent Mode alone. With plain delegation the events land in `window.dataLayer` regardless — readable by every other tag on the page — and Consent Mode replays queued tags when consent is granted later, so a "reject, then accept" visitor would still be measured retroactively. The gate prevents both. {% endhint %} ## Scope: what the gate covers The consent gate governs **one thing**: whether Carposé events are forwarded to an analytics destination. It does not switch parts of the app off. Carposé keeps functional data in the browser to deliver the features the visitor is using. This storage is **not** affected by consent state and keeps working whether or not analytics consent was given: | Stored | Where | Purpose | | ------------------------------------------------------ | ---------------- | --------------------------------------------------------------- | | API response cache (5 min TTL) | `localStorage` | Avoids re-fetching vehicle and settings data on every page view | | Account settings and feature flags | `localStorage` | Configuration of the embedded modules | | Wishlist, comparison, recently viewed vehicles, budget | `localStorage` | Features the visitor actively uses | | Search form state, AI assistant history | `localStorage` | Restores the visitor's own inputs across page views | | Per-session UI state | `sessionStorage` | Cleared when the tab closes | None of this is transmitted to Google or any other analytics provider, and none of it is used for profiling or cross-site recognition — it stays in the visitor's browser and serves the module they are looking at. {% hint style="info" %} Whether this functional storage requires consent on your site — under §25 (2) TDDDG, storage strictly necessary for a service the user explicitly requested is exempt — is an assessment for you and your data protection officer, based on which modules you embed. Carposé does not make that determination for you, and the analytics gate described here does not depend on it. {% endhint %} ## Recognised consent signals Consent counts as granted when **any** of the following reports it. A source that never reports anything is treated as unknown, which is not a grant. ### 1. Google Consent Mode v2 `analytics_storage` is read from the `consent` `default` / `update` commands in `window.dataLayer`, including commands issued before Carposé loads and any later updates. The most recent command wins. ```javascript gtag('consent', 'update', { analytics_storage: 'granted' }); ``` Supported out of the box by Usercentrics, Cookiebot, Consentmanager, Borlabs and most other commercial CMPs. ### 2. IAB TCF v2.2 Read via `window.__tcfapi`. Consent counts as granted when `gdprApplies` is `false`, or when both purpose **1** (store and access information on a device) and purpose **8** (measure content performance) are consented. ### 3. The Carposé consent API For consent tools that speak neither of the above. Set the initial state before the Carposé script loads: ```javascript window.carposeConsent = { analytics: true }; ``` And report every change: ```javascript window.dispatchEvent(new CustomEvent('carpose-consent-update', { detail: { analytics: true } // false on withdrawal })); ``` The event goes on `window`, not `document.body`, so it can be dispatched before the body exists. Call it from your CMP's own consent callback, both when consent is given and when it is withdrawn. ## CMP compatibility | Consent tool | Covered by | | ------------------------ | ----------------------------------------------- | | Usercentrics | Consent Mode | | Cookiebot | Consent Mode | | Consentmanager | Consent Mode | | Borlabs Cookie | Consent Mode | | Complianz (WordPress) | Consent Mode **only if configured** — see below | | Custom / in-house banner | Carposé consent API | ### WordPress and Complianz WordPress consent plugins commonly implement the **WP Consent API** (`wp_has_consent('statistics')`), which Carposé does **not** read. This matters for Complianz, the most widespread WordPress CMP: its free version implements the WP Consent API natively, but places Google Consent Mode setup with Tag Manager behind Complianz Premium, and TCF behind a further paid add-on. A site on free Complianz may therefore emit none of the three recognised signals — in which case the gate stays shut and no analytics data is collected at all. Such sites need the Carposé consent API wired into the plugin's consent callback: ```javascript document.addEventListener('wp_listen_for_consent_change', function (e) { const changed = e.detail; if ('statistics' in changed) { window.dispatchEvent(new CustomEvent('carpose-consent-update', { detail: { analytics: changed.statistics === 'allow' } })); } }); ``` ## Troubleshooting: no data in Google Analytics Work through this in order: 1. **Is tracking enabled at all?** Check the **Google Analytics Tracking** setting in the dashboard, and make sure no `data-carpose-google-analytics-tracking="false"` on the script tag is overriding it. 2. **Did you consent yourself while testing?** Accept analytics in the banner, then reload. Events fired before you accepted are gone — they are not replayed. 3. **Does your CMP emit a recognised signal?** In the browser console, `window.dataLayer.filter(e => e[0] === 'consent')` should show a `consent` command containing `analytics_storage`. If it is empty and you are on WordPress, this is almost certainly the Complianz case above — wire the Carposé consent API. 4. **Is GTM itself configured?** The bridge fills `window.dataLayer`. Turning those pushes into GA4 hits is still your GTM container's job. ## Migrating from a custom tracking script If you previously forwarded Carposé events with your own listeners or a hosted bridge script: * **Remove the old script when you switch the toggle on.** Both will run, and every event will be counted twice. * **Check that the old script was consent-gated.** Hand-written bridges typically push unconditionally and rely on GTM. The built-in bridge does not, which is the reason to switch. * **Expect the numbers to drop.** After the switch you measure only consenting visitors. That is the intended outcome, not a regression, so compare periods with this in mind. # Shadow DOM Architecture {% hint style="info" %} All Carposé components render inside a Shadow DOM for complete style isolation from the host page. {% endhint %} ## Overview Every Carposé component is rendered within a Shadow DOM. This guarantees complete style isolation from the host page: component styles never leak out, and the host site's CSS never affects the components. ## Why Shadow DOM? * **Style isolation** — component styles don't leak to the host page, and host styles don't affect components * **Encapsulation** — components are self-contained units * **Consistency** — components render the same way across different websites * **No CSS conflicts** — avoids class-name collisions with the host page ## How It Works When a component is initialised, a shadow root is attached to the host element, the component's styles are injected into that shadow root, and the component is rendered inside it. Each component instance has its own style scope. ## Architecture Diagram ``` Host Page └──

└── #shadow-root ├──