# Image Frame
URL: /lynx/components/image-frame
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/components/image-frame.mdx

사용자가 업로드한 이미지를 표시하기 위한 컴포넌트입니다.

Lynx Engine 최소 버전: 3.9

사용 가능 버전: @seed-design/lynx-react@1.0.0, @seed-design/lynx-css@1.0.0

## Preview

```tsx
import "./styles";
import { ImageFrame } from "@seed-design/lynx-react";

export default function ImageFramePreview() {
  return (
    <ImageFrame
      ratio={4 / 3}
      borderRadius="r2"
      stroke
      src="https://avatars.githubusercontent.com/u/54893898?v=4"
      alt="프로필 이미지"
      width="300px"
      fallback={
        <view className="image-frame-fallback">
          <text className="image-frame-fallback-label">이미지</text>
        </view>
      }
    />
  );
}
```

## Installation

- npm: npm install @seed-design/lynx-react @seed-design/lynx-css
- pnpm: pnpm add @seed-design/lynx-react @seed-design/lynx-css
- yarn: yarn add @seed-design/lynx-react @seed-design/lynx-css
- bun: bun add @seed-design/lynx-react @seed-design/lynx-css

## Usage

```tsx
import { ImageFrame } from "@seed-design/lynx-react";
```

```tsx
<ImageFrame
  ratio={4 / 3}
  width="200px"
  borderRadius="r2"
  stroke
  src="..."
  alt="..."
  fallback={<view><text>이미지를 불러올 수 없습니다.</text></view>}
/>
```

`width`·`height`·`margin` 등 공통 레이아웃 prop을 받습니다. `margin`과 `bleed`는 함께 사용하지 않으며, `bleed`는 Lynx Box와 같이 px 길이·`0`·`"safeArea"`를 사용합니다.

## Props

## Lynx에서의 동작

Lynx Engine 3.9 이상을 지원합니다.

- 로딩 중에도 이미지를 마운트합니다. `src`가 바뀌면 이전 요청의 이벤트를 새 상태에 반영하지 않습니다.
- `alt`는 `accessibility-label`로 전달합니다. 장식용 이미지는 빈 문자열을 사용합니다.
- `onLoad`와 `onError` 대신 `bindload`와 `binderror`를 사용합니다. `onLoadingStatusChange`로 로딩 상태를 관찰할 수 있습니다.
- `ratio`의 기본값은 `4 / 3`, `borderRadius`의 기본값은 `"r2"`입니다.
- `ImageFrameIcon`의 `svg`에는 Lynx 아이콘 컴포넌트를 전달합니다.
- `ImageFrameReactionButton`은 토글 버튼입니다. `pressed`, `defaultPressed`, `onPressedChange`, `disabled`를 제공하며 접근성 이름은 `accessibility-label`로 지정합니다.
- 좋아요 버튼은 `hit-slop`으로 터치 영역을 기본 8px씩 확장합니다. 부모가 콘텐츠를 자르면 확장 영역도 제한될 수 있습니다.
- `as`, `asChild`, DOM 속성, 이미지의 `loading`, `decoding`, `crossOrigin`, `referrerPolicy`, `sizes`, `srcSet`은 지원하지 않습니다.

## Examples

### Ratio

`ratio`로 이미지 영역의 비율을 지정합니다.

```tsx
import "./styles";
import { ImageFrame, HStack, VStack, Text } from "@seed-design/lynx-react";

export default function ImageFrameRatio() {
  return (
    <HStack gap="x2" wrap="wrap" align="flex-end">
      <VStack gap="x2" align="center">
        <ImageFrame
          ratio={1}
          borderRadius="r2"
          stroke
          src="https://avatars.githubusercontent.com/u/54893898?v=4"
          alt="1:1"
          style={{ width: "120px" }}
          fallback={
            <view className="image-frame-fallback">
              <text className="image-frame-fallback-label">이미지</text>
            </view>
          }
        />
        <Text color="palette.gray700" textStyle="t1Regular">
          1:1
        </Text>
      </VStack>
      <VStack gap="x2" align="center">
        <ImageFrame
          ratio={4 / 3}
          borderRadius="r2"
          stroke
          src="https://avatars.githubusercontent.com/u/54893898?v=4"
          alt="4:3"
          style={{ width: "160px" }}
          fallback={
            <view className="image-frame-fallback">
              <text className="image-frame-fallback-label">이미지</text>
            </view>
          }
        />
        <Text color="palette.gray700" textStyle="t1Regular">
          4:3
        </Text>
      </VStack>
      <VStack gap="x2" align="center">
        <ImageFrame
          ratio={16 / 9}
          borderRadius="r2"
          stroke
          src="https://avatars.githubusercontent.com/u/54893898?v=4"
          alt="16:9"
          style={{ width: "200px" }}
          fallback={
            <view className="image-frame-fallback">
              <text className="image-frame-fallback-label">이미지</text>
            </view>
          }
        />
        <Text color="palette.gray700" textStyle="t1Regular">
          16:9
        </Text>
      </VStack>
    </HStack>
  );
}
```

### Border Radius

`borderRadius`에는 토큰, `0`, CSS 길이를 전달합니다. 개별 모서리는 `borderTopLeftRadius` 같은 prop으로 지정합니다.

```tsx
<ImageFrame
  src={imageUrl}
  alt="상품 이미지"
  width="160px"
  ratio={1}
  borderRadius="r1"
  borderTopLeftRadius="r4"
  borderBottomRightRadius="24px"
  stroke
/>
```

```tsx
import "./styles";
import { ImageFrame, HStack, VStack, Text } from "@seed-design/lynx-react";

export default function ImageFrameBorderRadius() {
  return (
    <VStack gap="x6" align="flex-start">
      <HStack gap="x4" wrap="wrap" align="flex-end">
        <VStack gap="x2" align="center">
          <ImageFrame
            ratio={4 / 3}
            borderRadius="r1"
            src="https://avatars.githubusercontent.com/u/54893898?v=4"
            alt="size 20 borderRadius=r1"
            style={{ width: "20px" }}
            fallback={
              <view className="image-frame-fallback">
                <text className="image-frame-fallback-label">이미지</text>
              </view>
            }
          />
          <Text color="palette.gray700" textStyle="t1Regular">
            20 / r1 (4px)
          </Text>
        </VStack>
        <VStack gap="x2" align="center">
          <ImageFrame
            ratio={4 / 3}
            borderRadius="r1"
            src="https://avatars.githubusercontent.com/u/54893898?v=4"
            alt="size 24 borderRadius r1"
            style={{ width: "24px" }}
            fallback={
              <view className="image-frame-fallback">
                <text className="image-frame-fallback-label">이미지</text>
              </view>
            }
          />
          <Text color="palette.gray700" textStyle="t1Regular">
            24 / r1 (4px)
          </Text>
        </VStack>
        <VStack gap="x2" align="center">
          <ImageFrame
            ratio={4 / 3}
            borderRadius="r1_5"
            src="https://avatars.githubusercontent.com/u/54893898?v=4"
            alt="size 36 borderRadius r1_5"
            style={{ width: "36px" }}
            fallback={
              <view className="image-frame-fallback">
                <text className="image-frame-fallback-label">이미지</text>
              </view>
            }
          />
          <Text color="palette.gray700" textStyle="t1Regular">
            36 / r1_5 (6px)
          </Text>
        </VStack>
        <VStack gap="x2" align="center">
          <ImageFrame
            ratio={4 / 3}
            borderRadius="r1_5"
            src="https://avatars.githubusercontent.com/u/54893898?v=4"
            alt="size 42 borderRadius r1_5"
            style={{ width: "42px" }}
            fallback={
              <view className="image-frame-fallback">
                <text className="image-frame-fallback-label">이미지</text>
              </view>
            }
          />
          <Text color="palette.gray700" textStyle="t1Regular">
            42 / r1_5 (6px)
          </Text>
        </VStack>
        <VStack gap="x2" align="center">
          <ImageFrame
            ratio={4 / 3}
            borderRadius="r1_5"
            src="https://avatars.githubusercontent.com/u/54893898?v=4"
            alt="size 48 borderRadius r1_5"
            style={{ width: "48px" }}
            fallback={
              <view className="image-frame-fallback">
                <text className="image-frame-fallback-label">이미지</text>
              </view>
            }
          />
          <Text color="palette.gray700" textStyle="t1Regular">
            48 / r1_5 (6px)
          </Text>
        </VStack>
        <VStack gap="x2" align="center">
          <ImageFrame
            ratio={4 / 3}
            borderRadius="r2"
            src="https://avatars.githubusercontent.com/u/54893898?v=4"
            alt="size 64 borderRadius r2"
            style={{ width: "64px" }}
            fallback={
              <view className="image-frame-fallback">
                <text className="image-frame-fallback-label">이미지</text>
              </view>
            }
          />
          <Text color="palette.gray700" textStyle="t1Regular">
            64+ / r2 (8px)
          </Text>
        </VStack>
      </HStack>
    </VStack>
  );
}
```

### Stroke

`stroke` prop으로 테두리 스타일을 적용할 수 있습니다.

```tsx
import "./styles";
import { ImageFrame, HStack, VStack, Text } from "@seed-design/lynx-react";

export default function ImageFrameStroke() {
  return (
    <HStack gap="x4" wrap="wrap" align="flex-end">
      <VStack gap="x2" align="center">
        <ImageFrame
          ratio={4 / 3}
          stroke={false}
          src="https://avatars.githubusercontent.com/u/54893898?v=4"
          alt="stroke=false"
          style={{ width: "150px" }}
          fallback={
            <view className="image-frame-fallback">
              <text className="image-frame-fallback-label">이미지</text>
            </view>
          }
        />
        <Text color="palette.gray700" textStyle="t1Regular">
          stroke=false
        </Text>
      </VStack>
      <VStack gap="x2" align="center">
        <ImageFrame
          ratio={4 / 3}
          stroke={true}
          src="https://avatars.githubusercontent.com/u/54893898?v=4"
          alt="stroke=true"
          style={{ width: "150px" }}
          fallback={
            <view className="image-frame-fallback">
              <text className="image-frame-fallback-label">이미지</text>
            </view>
          }
        />
        <Text color="palette.gray700" textStyle="t1Regular">
          stroke=true
        </Text>
      </VStack>
    </HStack>
  );
}
```

### Fallback Image

`fallback`은 로딩 중이거나 오류가 발생했을 때 표시하고, 로딩에 성공하면 언마운트합니다. 다시 표시할 때 유지해야 하는 상태는 부모에서 관리하세요.

```tsx
import "./styles";
import { ImageFrame, HStack } from "@seed-design/lynx-react";

export default function ImageFrameFallbackExample() {
  return (
    <HStack gap="x3" wrap="wrap" align="flex-end">
      <ImageFrame
        ratio={1}
        borderRadius="r2"
        stroke
        src="https://invalid-url"
        alt="이미지를 불러올 수 없습니다"
        style={{ width: "120px" }}
        fallback={
          <view className="image-frame-fallback">
            <text className="image-frame-fallback-label">이미지</text>
          </view>
        }
      />
      <ImageFrame
        ratio={1}
        borderRadius="r2"
        stroke
        src="https://invalid-url"
        alt="이미지를 불러올 수 없습니다"
        style={{ width: "120px" }}
        fallback={
          <view className="image-frame-fallback">
            <text className="image-frame-fallback-label">이미지</text>
          </view>
        }
      />
      <ImageFrame
        ratio={1}
        borderRadius="r2"
        stroke
        src="https://invalid-url"
        alt="이미지를 불러올 수 없습니다"
        style={{ width: "120px" }}
        fallback={
          <view className="image-frame-fallback">
            <text className="image-frame-fallback-label">이미지</text>
          </view>
        }
      />
    </HStack>
  );
}
```

### Overlay

`ImageFrameFloater`를 자식으로 넣고 `placement`로 위치를 지정합니다. 세로와 가로 위치를 조합한 9개 값을 사용할 수 있습니다.

```tsx
import "./styles";
import IconCarrotFill from "@karrotmarket/lynx-monochrome-icon/IconCarrotFill";
import {
  ImageFrame,
  ImageFrameFloater,
  ImageFrameBadge,
  ImageFrameIcon,
  ImageFrameIndicator,
  ImageFrameReactionButton,
  HStack,
  VStack,
  Text,
} from "@seed-design/lynx-react";
import { useState } from "@lynx-js/react";

export default function ImageFrameOverlayExample() {
  const [liked, setLiked] = useState(false);

  return (
    <HStack gap="x3" wrap="wrap" align="flex-end">
      <VStack gap="x2" align="center">
        <ImageFrame
          ratio={1}
          borderRadius="r2"
          stroke
          src="https://avatars.githubusercontent.com/u/54893898?v=4"
          alt="Profile with badge overlay"
          style={{ width: "120px" }}
          fallback={
            <view className="image-frame-fallback">
              <text className="image-frame-fallback-label">이미지</text>
            </view>
          }
        >
          <ImageFrameFloater placement="bottom-end">
            <ImageFrameBadge tone="brand" variant="solid">
              NEW
            </ImageFrameBadge>
          </ImageFrameFloater>
        </ImageFrame>
        <Text color="palette.gray700" textStyle="t1Regular">
          ImageFrameBadge
        </Text>
      </VStack>

      <VStack gap="x2" align="center">
        <ImageFrame
          ratio={1}
          borderRadius="r2"
          stroke
          src="https://avatars.githubusercontent.com/u/54893898?v=4"
          alt="Profile with icon overlay"
          style={{ width: "120px" }}
          fallback={
            <view className="image-frame-fallback">
              <text className="image-frame-fallback-label">이미지</text>
            </view>
          }
        >
          <ImageFrameFloater placement="bottom-end">
            <ImageFrameIcon svg={<IconCarrotFill />} />
          </ImageFrameFloater>
        </ImageFrame>
        <Text color="palette.gray700" textStyle="t1Regular">
          ImageFrameIcon
        </Text>
      </VStack>

      <VStack gap="x2" align="center">
        <ImageFrame
          ratio={1}
          borderRadius="r2"
          stroke
          src="https://avatars.githubusercontent.com/u/54893898?v=4"
          alt="Profile with indicator overlay"
          style={{ width: "120px" }}
          fallback={
            <view className="image-frame-fallback">
              <text className="image-frame-fallback-label">이미지</text>
            </view>
          }
        >
          <ImageFrameFloater placement="bottom-end">
            <ImageFrameIndicator>+9</ImageFrameIndicator>
          </ImageFrameFloater>
        </ImageFrame>
        <Text color="palette.gray700" textStyle="t1Regular">
          ImageFrameIndicator
        </Text>
      </VStack>

      <VStack gap="x2" align="center">
        <ImageFrame
          ratio={1}
          borderRadius="r2"
          stroke
          src="https://avatars.githubusercontent.com/u/54893898?v=4"
          alt="Profile with reaction button overlay"
          style={{ width: "120px" }}
          fallback={
            <view className="image-frame-fallback">
              <text className="image-frame-fallback-label">이미지</text>
            </view>
          }
        >
          <ImageFrameFloater placement="bottom-end">
            <ImageFrameReactionButton
              pressed={liked}
              onPressedChange={setLiked}
              accessibility-label="좋아요"
            />
          </ImageFrameFloater>
        </ImageFrame>
        <Text color="palette.gray700" textStyle="t1Regular">
          ImageFrameReactionButton
        </Text>
      </VStack>
    </HStack>
  );
}
```

#### Multiple Overlays

여러 위치에 오버레이를 동시에 배치할 수 있습니다.

```tsx
import "./styles";
import {
  ImageFrame,
  ImageFrameFloater,
  ImageFrameBadge,
  ImageFrameReactionButton,
} from "@seed-design/lynx-react";
import { useState } from "@lynx-js/react";

export default function ImageFrameOverlayMultipleExample() {
  const [liked, setLiked] = useState(false);

  return (
    <ImageFrame
      ratio={1}
      borderRadius="r2"
      stroke
      src="https://avatars.githubusercontent.com/u/54893898?v=4"
      alt="Profile with multiple overlays"
      style={{ width: "200px" }}
      fallback={
        <view className="image-frame-fallback">
          <text className="image-frame-fallback-label">이미지</text>
        </view>
      }
    >
      <ImageFrameFloater placement="top-start">
        <ImageFrameBadge tone="brand" variant="solid">
          NEW
        </ImageFrameBadge>
      </ImageFrameFloater>
      <ImageFrameFloater placement="bottom-end">
        <ImageFrameReactionButton
          pressed={liked}
          onPressedChange={setLiked}
          accessibility-label="좋아요"
        />
      </ImageFrameFloater>
    </ImageFrame>
  );
}
```

#### Custom Overlay

`ImageFrameFloater`는 커스텀 UI도 `children`으로 받습니다.

```tsx
import "./styles";
import { ImageFrame, ImageFrameFloater } from "@seed-design/lynx-react";

export default function ImageFrameOverlayCustomExample() {
  return (
    <ImageFrame
      ratio={1}
      borderRadius="r2"
      stroke
      src="https://avatars.githubusercontent.com/u/54893898?v=4"
      alt="Profile with custom overlay"
      style={{ width: "200px" }}
      fallback={
        <view className="image-frame-fallback">
          <text className="image-frame-fallback-label">이미지</text>
        </view>
      }
    >
      <ImageFrameFloater placement="bottom-end">
        <view
          style={{
            padding: "4px 8px",
            backgroundColor: "rgba(0, 0, 0, 0.6)",
            borderRadius: "4px",
            color: "white",
            fontSize: "12px",
          }}
        >
          <text className="image-frame-custom-label">Custom Element</text>
        </view>
      </ImageFrameFloater>
    </ImageFrame>
  );
}
```

#### Offset

`offsetX`와 `offsetY`로 가로와 세로 여백을 지정합니다. `0`, SEED 간격 토큰, CSS 길이를 사용할 수 있습니다. 가장자리의 기본 여백은 6px이며, 중앙 축의 기본 오프셋은 0입니다.

```tsx
import { ImageFrame, ImageFrameFloater, ImageFrameIndicator } from "@seed-design/lynx-react";

<ImageFrame src={imageUrl} alt="상품 이미지" width="150px" ratio={1}>
  <ImageFrameFloater placement="bottom-end" offsetX="12px" offsetY="12px">
    <ImageFrameIndicator>+9</ImageFrameIndicator>
  </ImageFrameFloater>
</ImageFrame>
```

```tsx
import "./styles";
import { ImageFrame, ImageFrameFloater, ImageFrameIndicator } from "@seed-design/lynx-react";

export default function ImageFrameOverlayInsetExample() {
  return (
    <view style={{ display: "flex", flexDirection: "row", flexWrap: "wrap", gap: "12px" }}>
      <ImageFrame
        ratio={1}
        borderRadius="r2"
        stroke
        src="https://avatars.githubusercontent.com/u/54893898?v=4"
        alt="Profile with default offset"
        style={{ width: "150px" }}
        fallback={
          <view className="image-frame-fallback">
            <text className="image-frame-fallback-label">이미지</text>
          </view>
        }
      >
        <ImageFrameFloater placement="bottom-end">
          <ImageFrameIndicator>default</ImageFrameIndicator>
        </ImageFrameFloater>
      </ImageFrame>

      <ImageFrame
        ratio={1}
        borderRadius="r2"
        stroke
        src="https://avatars.githubusercontent.com/u/54893898?v=4"
        alt="Profile with 0 offset"
        style={{ width: "150px" }}
        fallback={
          <view className="image-frame-fallback">
            <text className="image-frame-fallback-label">이미지</text>
          </view>
        }
      >
        <ImageFrameFloater placement="bottom-end" offsetX={0} offsetY={0}>
          <ImageFrameIndicator>offset=0</ImageFrameIndicator>
        </ImageFrameFloater>
      </ImageFrame>

      <ImageFrame
        ratio={1}
        borderRadius="r2"
        stroke
        src="https://avatars.githubusercontent.com/u/54893898?v=4"
        alt="Profile with 12 offset"
        style={{ width: "150px" }}
        fallback={
          <view className="image-frame-fallback">
            <text className="image-frame-fallback-label">이미지</text>
          </view>
        }
      >
        <ImageFrameFloater placement="bottom-end" offsetX="12px" offsetY="12px">
          <ImageFrameIndicator>offset=12</ImageFrameIndicator>
        </ImageFrameFloater>
      </ImageFrame>
    </view>
  );
}
```

## Overlay Props