> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 상품 애드온 블록

> Aftersell Cart의 상품 애드온(Product add-on) 블록: 드로어 안에서 특정 상품 하나를 빠른 추가로 제안하세요.

> **상품 애드온(Product add-on)** 블록은 여러분이 선택한 특정 상품 하나를 장바구니 안에서 애드온으로 제안해, 알려진 상품 하나(보증, 샘플, 베스트셀러)를 장바구니에서 바로 빠르게 추가할 수 있도록 홍보해요.

<Info>
  전략에 따라 선택된 상품을 표시하는 [**업셀**](/ko/aftersell/cart/upsells-block)과 달리, 상품 애드온은 항상 여러분이 선택한 정확히 그 상품을 보여줘요.
</Info>

<Frame>
  <img src="https://mintcdn.com/aftersell/1Y3gBpUfxv16VGSW/images/aftersell/cart-product-add-on-block-additional-product.png?fit=max&auto=format&n=1Y3gBpUfxv16VGSW&q=85&s=29c7598c41c78f6503af7f9cd7ec084a" alt="쇼핑객이 장바구니에 함께 담을 수 있는 추가 상품을 제안하는 상품 애드온 블록" width="678" height="125" data-path="images/aftersell/cart-product-add-on-block-additional-product.png" />
</Frame>

<div id="behavior">
  ## 동작 방식
</div>

* **활성 변형(variant)이 확인되지 않으면** — 상품이 설정되지 않았거나, 보관 처리되었거나, 품절인 경우 — 블록은 작동하지 않는 버튼 대신 **아무것도** 렌더링하지 않아요.
* 컨트롤은 *이 블록 자체의* 애드온 라인이 장바구니에 있는지를 반영하므로, 끄면 이 블록이 추가한 라인만 제거돼요(다른 곳에서 추가된 같은 상품에는 영향을 주지 않아요).
* 실제 할인이 있을 때 정가(compare-at price)에 취소선이 표시되며, 할인율이 반올림해서 1% 미만이면 "% off" 레이블이 숨겨져요.
* 선택한 변형에 이미지가 없으면 애드온 이미지는 상품의 대표 이미지로 대체돼요.

<div id="settings">
  ## 설정
</div>

| 설정               | 제어하는 항목                                                | 기본값                                   |
| ---------------- | ------------------------------------------------------ | ------------------------------------- |
| **Display type** | 추가 컨트롤의 표시 방식: **Toggle** 또는 **Checkbox**.             | Toggle                                |
| **Product**      | 제안할 상품 변형 — 하나의 선택기로 둘 다 처리해요. 이미지와 가격은 선택한 변형에서 가져와요. | 없음                                    |
| **Title**        | 서식 있는 텍스트 제목.                                          | `<strong>{{product_title}}</strong>`  |
| **Price label**  | 가격 표시 줄.                                               | `{{price}}`                           |
| **Description**  | 보조 문구.                                                 | `Add {{product_title}} to your order` |

**Title**, **Price label**, **Description**은 모두 같은 네 가지 토큰을 지원해요: `{{product_title}}`, `{{price}}`, `{{compare_at_price}}`, `{{savings}}`.

<div id="placement-and-limits">
  ## 배치 및 제한
</div>

* **영역:** 본문(body) 또는 하단(bottom).
* **최대:** 장바구니 상태당 3개 — 채워진 장바구니와 빈 장바구니 각각 별도의 허용량이 있어요.
* **상태:** 채워진 장바구니와 빈 장바구니 모두.
* 기본으로 추가되지 않아요. 잠겨 있지 않으므로 제거하거나 숨길 수 있어요.

<div id="custom-template">
  ## 커스텀 템플릿
</div>

코드(Code) 탭에서 [커스텀 템플릿](/ko/aftersell/cart/custom-templates)을 지원하며, 이 블록의 기본 마크업을 여러분의 JSX로 대체해요. 이 블록이 받는 props는 다음과 같아요.

<div id="content">
  ### 콘텐츠
</div>

| Prop                      | 타입               | 용도                                                               |
| ------------------------- | ---------------- | ---------------------------------------------------------------- |
| `addonTitle`              | `string`         | 일반 텍스트 제목. 대체 텍스트와 `aria-label`에 사용하고, 서식 있는 제목이 없을 때 대체로 사용하세요. |
| `addonTitleHtml`          | `string`         | 살균 처리된 서식 있는 텍스트 제목 HTML. 없으면 비어 있어요.                            |
| `descriptionHtml`         | `string`         | 살균 처리된 서식 있는 텍스트 설명 HTML. 없으면 비어 있어요.                            |
| `formattedPrice`          | `string`         | 통화 형식이 적용된 가격 레이블. 표시되지 않을 때는 비어 있어요.                            |
| `formattedCompareAtPrice` | `string`         | 형식이 적용된 변형의 정가(MSRP). 실제 할인이 없으면 비어 있어요.                         |
| `savings`                 | `string`         | 정수 퍼센트 할인 레이블. 예: `25%`. 할인이 없으면 비어 있어요.                         |
| `priceHtml`               | `string \| null` | 전용 가격 필드의 살균 처리된 서식 있는 텍스트 가격 HTML. 비어 있으면 `null`이에요.            |
| `ctaText`                 | `string`         | `button` 형식용 버튼 레이블이에요.                                          |
| `imageUrl`                | `string`         | 상품 이미지. 없으면 비어 있어요.                                              |
| `productUrl`              | `string`         | 상품 페이지 URL. 없으면 비어 있으며, 이 경우 이미지나 제목에 링크를 걸지 마세요.                |

<div id="state-and-actions">
  ### 상태 및 액션
</div>

| Prop           | 타입                                   | 용도                                                |
| -------------- | ------------------------------------ | ------------------------------------------------- |
| `variantId`    | `number \| null`                     | 확인된 변형. 상품이 설정되지 않았거나 품절이어서 활성 변형이 없으면 `null`이에요. |
| `format`       | `'button' \| 'checkbox' \| 'toggle'` | 구매자가 애드온을 추가하는 방식. 이 값으로 마크업을 분기하세요.              |
| `isEnabled`    | `boolean`                            | 애드온이 현재 장바구니에 있는지 여부예요.                           |
| `isAdding`     | `boolean`                            | 추가 또는 제거가 진행 중인 동안 `true`예요. 이 값으로 컨트롤을 비활성화하세요.  |
| `handleAdd`    | `() => void`                         | 애드온을 추가해요. `button` 형식용이에요.                       |
| `handleToggle` | `() => void`                         | 애드온을 장바구니에서 추가하거나 제거해요. `checkbox`와 `toggle`용이에요. |
| `isLoading`    | `boolean`                            | 장바구니가 첫 번째 가져오기를 아직 진행 중인 동안 `true`예요.            |

<Warning>
  `format`이 어떤 핸들러가 적용되는지 결정해요: `button`은 `handleAdd`, `checkbox`와 `toggle`은 `handleToggle`이에요. `variantId`가 `null`이면 추가할 것이 없다는 뜻이므로, 성공할 수 없는 핸들러를 호출하기보다 이 값으로 컨트롤을 제한하세요.
</Warning>

<div id="design">
  ## 디자인
</div>

설정 패널의 **Design** 섹션에서 이 블록의 스타일을 지정하세요. 이는 전역 디자인 위에 적용되는 블록별 재정의이며, 비워 두면 전역 디자인으로 대체돼요.

<div id="text">
  ### 텍스트
</div>

Design의 **Text** 섹션에서 세 요소의 타이포그래피를 제어할 수 있어요. **Text element** 선택기로 요소를 전환하세요.

**Title** — 상품명이에요. 커스텀 글꼴 패밀리도 지원해요. 굵기와 텍스트 색상은 (Settings 탭의) 위쪽 리치 텍스트 에디터에서 설정하며, 이곳에서 설정하지 않아요.

| 설정                 | 제어하는 항목       | 기본값     |
| ------------------ | ------------- | ------- |
| **Font**           | 제목의 글꼴 패밀리예요. | 테마에서 상속 |
| **Size**           | 글꼴 크기예요.      | `15px`  |
| **Line height**    | 줄 높이 배수예요.    | `1.33`  |
| **Letter spacing** | 문자 간 간격이에요.   | Normal  |

**Price** — 가격 표시 줄이에요. 굵기와 텍스트 색상은 위쪽 리치 텍스트 에디터에서 설정해요.

| 설정                 | 제어하는 항목     | 기본값    |
| ------------------ | ----------- | ------ |
| **Size**           | 글꼴 크기예요.    | `15px` |
| **Line height**    | 줄 높이 배수예요.  | `1.33` |
| **Letter spacing** | 문자 간 간격이에요. | Normal |

**Description** — 보조 문구예요. 굵기와 텍스트 색상은 위쪽 리치 텍스트 에디터에서 설정해요.

| 설정                 | 제어하는 항목     | 기본값    |
| ------------------ | ----------- | ------ |
| **Size**           | 글꼴 크기예요.    | `14px` |
| **Line height**    | 줄 높이 배수예요.  | `1.29` |
| **Letter spacing** | 문자 간 간격이에요. | Normal |

<Tip>
  장바구니 미리보기에서 텍스트 요소를 직접 클릭하면 해당 요소가 강조되고, 패널에서 해당 컨트롤이 자동으로 열려요.
</Tip>

디자인 설정이 무엇인가요? 자세한 내용은 여기에서 확인하세요: [디자인 설정](/ko/aftersell/cart/design-settings).