# Offer Slider

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

The `Offer Slider` component displays promotional offers from a specified offer group. It provides three display variants: a carousel slider (default), a tile grid using Ant Design Cards, or a vertical list layout.

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

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

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

To use the Offer Slider component in a standard HTML page:

```html
<div
  data-carpose-component="offer-slider"
  data-api-key="your-api-key"
  data-id="your-offer-group-id"
></div>
```

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

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

| Attribute                | Type   | Default | Description                                                                                                                                                                                                      |
| ------------------------ | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-carpose-component` | string | -       | Identifies the component type, must be set to "offer-slider"                                                                                                                                                     |
| `data-api-key`           | string | -       | API key for authentication with the Carpose backend services. Required for data fetching.                                                                                                                        |
| `data-id`                | string | -       | ID of the offer group to display. Required to fetch the specific collection of offers.                                                                                                                           |
| `data-offer-urls`        | JSON   | -       | Optional map of offer IDs to redirect configuration. When a user clicks "zum Angebot" for a matched offer ID, the browser navigates to the configured URL instead of opening the detail modal. See format below. |

#### `data-offer-urls` Format <a href="#data-offer-urls-format" id="data-offer-urls-format"></a>

```json
{
  "offer-id-1": { "url": "https://example.com/offer/1", "target": "_blank" },
  "offer-id-2": { "url": "https://example.com/offer/2", "target": "_self" }
}
```

| Field    | Type   | Description                                              |
| -------- | ------ | -------------------------------------------------------- |
| `url`    | string | The URL to navigate to when the offer button is clicked  |
| `target` | string | Browser target: `_blank` (new tab) or `_self` (same tab) |

Offers not listed in the map fall back to the default modal behavior.

### Display Variants <a href="#display-variants" id="display-variants"></a>

#### Slider Variant (Default) <a href="#slider-variant-default" id="slider-variant-default"></a>

The default carousel view with navigation controls:

* Displays one offer at a time with navigation arrows and pagination dots
* Shows image on the left and content on the right on desktop
* Stacks image above content on mobile

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

* Multiple display variants (slider, tile, list)
* Responsive layout that adapts to different screen sizes
* Navigation controls for slider variant
* For each offer displays:
  * Headline and subheadline
  * Offer image
  * Details list
  * Condition information
  * Link to the full offer page

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

1. **Data Loading**:
   * On initialization, the component fetches offer group data from the API using the provided offer group ID and API key.
   * The component loads all offers associated with the specified offer group.
2. **Display Variant**:
   * The component renders according to the specified variant (slider, tile, or list).
   * If no variant is specified, it defaults to the slider view.
3. **Slider Navigation** (Slider variant only):
   * Users can navigate between offers using the arrow buttons or pagination dots.
   * The slider transitions smoothly between offers.
4. **Offer Display**:
   * Each offer is displayed with its headline, subheadline, and image.
   * Detailed information is shown in a list format.
   * Each offer includes a link to view the full offer details.
   * If available, image captions and consumption text are displayed.
   * Images are displayed with consistent heights (350px for slider and list, adjustable for tiles).
5. **Responsive Layout**:
   * All variants are fully responsive and adapt to different screen sizes.
   * Layout adjusts automatically based on the device viewport.

### Custom Events <a href="#custom-events" id="custom-events"></a>

The Offer Slider component dispatches custom events for tracking user interactions and component state changes.

For detailed information about the event system, event types, analytics integration, and best practices, see the [Custom Events System documentation](file:///home/alex/Projects/_carpose/carpose-de-app/docs/Events.md).

#### Quick Event Reference <a href="#quick-event-reference" id="quick-event-reference"></a>

* `carpose-offer-selected`: When user clicks "zum Angebot" button
* `carpose-offer-contact`: When user initiates contact about an offer
* `carpose-error`: When API requests fail or errors occur

**Note**: The event prefix has been updated from `carpose-de-` to `carpose-` and the component loaded event has been removed in the latest version.


---

# Agent Instructions: Querying This Documentation

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

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

```
GET https://docs.carpose.de/offer-modules/offer-slider.md?ask=<question>
```

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

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