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

# Featured Vehicles

{% hint style="info" %}
Featured Vehicles presents a vehicle group as a promotion — a slider or tile grid whose cards lead into your vehicle search.
{% endhint %}

## Introduction

The `featured-vehicles` component reads the same groups as the [Vehicle Group](/vehicle-search-modules/06_vehicle-group.md) component but behaves the opposite way: it shows no sorting or payment-type controls, and clicking a card opens the vehicle on your search page instead of resolving it in place. The closed group is a destination — this is a doorway. Use it for a "deals of the month" strip on the homepage or a promotional section on a landing page.

## Basic Usage

```html
<div
  data-carpose-component="featured-vehicles"
  data-api-key="your-api-key"
  data-purpose="monthly-offers"
></div>
```

## Attributes

| Attribute                 | Required                          | Description                                                                                                                                                                                         |
| ------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-carpose-component`  | Yes                               | Must be `featured-vehicles`                                                                                                                                                                         |
| `data-api-key`            | Yes                               | Your Carposé API key                                                                                                                                                                                |
| `data-id`                 | One of `data-id` / `data-purpose` | ID of the vehicle group to display. Wins over `data-purpose` when both are set.                                                                                                                     |
| `data-purpose`            | One of `data-id` / `data-purpose` | Website placement to resolve to a group, e.g. `monthly-offers`. See [Addressing by purpose](#addressing-by-purpose).                                                                                |
| `data-variant`            | No                                | Layout: `slider` (default) or `tiles`                                                                                                                                                               |
| `data-card-variant`       | No                                | Card layout: `classic` (default), `compact` or `horizontal` — see [Card Variants](#card-variants)                                                                                                   |
| `data-headline`           | No                                | Headline rendered above the vehicles                                                                                                                                                                |
| `data-heading-level`      | No                                | Heading level the vehicle names render at: `"2"`, `"3"` or `"4"` (an `h` prefix is accepted). Defaults to `h2`, or `h3` when `data-headline` is set — the headline then acts as the section's `h2`. |
| `data-search-url-forward` | No                                | Search page a card opens the vehicle on. Overrides the `vehicleSearchMainPageUrl` setting for this mount only.                                                                                      |
| `data-rates`              | No                                | When `true`, cards show leasing and financing payment options. Defaults to your account setting.                                                                                                    |

Like every component, it also accepts the [global color overrides](/readme.md#colors--theming) (`data-primary-color`, `data-secondary-color`, `data-accent-color`, `data-color-scheme`).

If neither `data-id` nor `data-purpose` is set, the component renders nothing and logs a console warning.

## Addressing by purpose

`data-purpose` names a website *placement* instead of a fixed group. The dealer marks a vehicle group with that purpose in the Carposé admin and can move the purpose to another group later — without touching the embed on the website. A purpose is unique within a company, so it resolves to at most one group.

```html
<!-- Always shows whichever group currently carries the 'monthly-offers' purpose -->
<div
  data-carpose-component="featured-vehicles"
  data-api-key="your-api-key"
  data-purpose="monthly-offers"
  data-headline="Angebote des Monats"
></div>
```

While no group carries the purpose, the component renders nothing — that is not an error, the dealer simply has not marked a group yet.

Use `data-id` instead when the embed should stay pinned to one specific group:

```html
<div
  data-carpose-component="featured-vehicles"
  data-api-key="your-api-key"
  data-id="550e8400-e29b-41d4-a716-446655440000"
  data-variant="tiles"
></div>
```

## Layouts

* `slider` (default) — a swipeable carousel, for a homepage strip that must not push the page down. Shows up to 3 vehicles at a time on desktop, 1 on mobile.
* `tiles` — a responsive grid that shows the whole set at once.

## Card Variants

`data-card-variant` picks the card itself, independent of the layout:

* `classic` (default) — portrait card, image on top, spec chips, price and a "Mehr Details" button
* `compact` — dense portrait card with label/value spec rows, for high-density grids
* `horizontal` — full-width list row, image left, price right

## Forwarding into the Search

Featured Vehicles sits on pages that carry no vehicle search of their own, so a card cannot open the vehicle in place. Clicking a card sends the browser 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 mount. The value may be absolute or site-relative; only `http` and `https` targets are accepted — anything else is ignored and the configured setting is used instead.

## Behavior

* Shows a skeleton grid while loading
* Renders nothing when the group is empty or the purpose is unassigned — no headline over a blank strip
* Vehicles follow the group's configured ordering
* Includes the WLTP information notice resolving the `*` behind consumption values (Pkw-EnVKV)

## Notes

* See [Vehicle Group](/vehicle-search-modules/06_vehicle-group.md) for the closed listing with sorting controls
* See [Vehicle Slider](/components/04_vehicle-slider.md) for a carousel of general inventory rather than a curated group