# Scroll Auto Hide
URL: /breeze/components/scroll-auto-hide
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/breeze/components/scroll-auto-hide.mdx

스크롤 방향에 따라 고정 영역을 숨기고 드러내는 컴포넌트

`ScrollAutoHide`는 아래로 스크롤할 때 고정 영역을 숨깁니다. 위로 스크롤하면 같은 거리만큼 다시 드러납니다. 필터, 탭, 보조 헤더처럼 콘텐츠 공간을 더 넓게 쓰고 싶은 영역에 적합합니다.

## Preview

```tsx
"use client";

import { IconChevronDownFill } from "@karrotmarket/react-monochrome-icon";
import { Badge, Box, Flex, HStack, Icon, Text, VStack } from "@seed-design/react";
import { useRef } from "react";
import { ScrollAutoHide } from "seed-design/breeze/scroll-auto-hide/scroll-auto-hide";
import { Avatar } from "seed-design/ui/avatar";
import { Chip } from "seed-design/ui/chip";
import { IdentityPlaceholder } from "seed-design/ui/identity-placeholder";
import { TabsList, TabsRoot, TabsTrigger } from "seed-design/ui/tabs";
import { TagGroupItem, TagGroupRoot } from "seed-design/ui/tag-group";

type Article = {
  author: string;
  title: string;
  content: string;
  category: string;
  date: string;
  popular?: boolean;
};

const ARTICLES = [
  {
    author: "magna",
    title: "독서 습관 만들기",
    content: "하루 10페이지부터 시작하자. 취침 전 20분 독서는 수면의 질도 높여줘요.",
    category: "라이프스타일",
    date: "12월 4일",
    popular: true,
  },
  {
    author: "ullamco",
    title: "알프스 하이킹 가이드",
    content: "그린델발트에서 시작해 아이거 북벽을 감상하는 초보자용 코스를 소개해요.",
    category: "여행",
    date: "10월 15일",
  },
  {
    author: "consectetur",
    title: "커피 브루잉 팁",
    content: "물 온도 92도, 중간 분쇄도와 3분의 추출 시간이 기본이에요.",
    category: "음식",
    date: "9월 25일",
  },
  {
    author: "exercitation",
    title: "실내 공기 정화 식물",
    content: "관리하기 쉽고 공기 정화 능력이 뛰어난 식물을 모아봤어요.",
    category: "라이프스타일",
    date: "8월 7일",
  },
  {
    author: "elit",
    title: "아침 루틴의 힘",
    content: "따뜻한 물 한 잔과 가벼운 스트레칭으로 하루를 시작해보세요.",
    category: "라이프스타일",
    date: "7월 28일",
    popular: true,
  },
] satisfies Article[];

const FILTERS = ["카테고리", "동네", "작성자", "작성 시간"];

export default function ScrollAutoHidePreview() {
  const scrollContainerRef = useRef<HTMLDivElement>(null);

  return (
    <Box
      width="360px"
      borderWidth={1}
      borderColor="stroke.neutralMuted"
      borderRadius="r3"
      bg="bg.layerDefault"
      overflowX="hidden"
      overflowY="hidden"
    >
      <Box as="header" px="spacingX.globalGutter" py="x4">
        <Text textStyle="t6Bold" color="fg.neutral">
          Demo
        </Text>
      </Box>

      <TabsRoot defaultValue="recommendations" size="medium" triggerLayout="fill">
        <TabsList>
          <TabsTrigger value="recommendations">추천</TabsTrigger>
          <TabsTrigger value="subscriptions">구독</TabsTrigger>
        </TabsList>
      </TabsRoot>

      <Box
        ref={scrollContainerRef}
        data-testid="scroll-auto-hide-container"
        height="360px"
        overflowY="auto"
      >
        <ScrollAutoHide
          scrollContainerRef={scrollContainerRef}
          data-testid="scroll-auto-hide-root"
          asChild
        >
          <Flex
            gap="spacingX.betweenChips"
            px="spacingX.globalGutter"
            py="x4"
            bg="bg.layerDefault"
            overflowX="auto"
            style={{ zIndex: 1 }}
          >
            {FILTERS.map((filter) => (
              <Chip.Button key={filter} size="small">
                <Chip.Label>{filter}</Chip.Label>
                <Chip.SuffixIcon>
                  <Icon svg={<IconChevronDownFill />} />
                </Chip.SuffixIcon>
              </Chip.Button>
            ))}
          </Flex>
        </ScrollAutoHide>

        <VStack as="ul" gap="x5" px="spacingX.globalGutter" py="x4">
          {ARTICLES.map((article) => (
            <Box as="li" key={article.title}>
              <VStack gap="x2_5">
                <HStack gap="x1_5" align="center">
                  <Avatar fallback={<IdentityPlaceholder identity="person" />} size="20" />
                  <Text textStyle="t4Medium" color="fg.neutral">
                    {article.author}
                  </Text>
                </HStack>

                <VStack gap="x2">
                  <VStack gap="x1">
                    <Text as="h3" textStyle="t5Bold" color="fg.neutral" maxLines={1}>
                      {article.title}
                    </Text>
                    <Text as="p" textStyle="t4Regular" color="fg.neutralMuted" maxLines={2}>
                      {article.content}
                    </Text>
                  </VStack>

                  <HStack align="center" gap="x2">
                    {article.popular && (
                      <Badge variant="outline" tone="brand">
                        인기
                      </Badge>
                    )}
                    <TagGroupRoot size="t4" tone="neutralSubtle">
                      <TagGroupItem label={article.category} />
                      <TagGroupItem label="서초2동" />
                      <TagGroupItem label={article.date} />
                    </TagGroupRoot>
                  </HStack>
                </VStack>
              </VStack>
            </Box>
          ))}
        </VStack>
      </Box>
    </Box>
  );
}
```

## Installation

Dependency:

- npm: npm install @radix-ui/react-compose-refs @radix-ui/react-slot
- pnpm: pnpm add @radix-ui/react-compose-refs @radix-ui/react-slot
- yarn: yarn add @radix-ui/react-compose-refs @radix-ui/react-slot
- bun: bun add @radix-ui/react-compose-refs @radix-ui/react-slot

Snippet:

- npm: npx @seed-design/cli@latest add breeze:scroll-auto-hide
- pnpm: pnpm dlx @seed-design/cli@latest add breeze:scroll-auto-hide
- yarn: yarn dlx @seed-design/cli@latest add breeze:scroll-auto-hide
- bun: bun x @seed-design/cli@latest add breeze:scroll-auto-hide

## Usage

스크롤이 일어나는 요소의 ref를 `scrollContainerRef`로 전달합니다. 컴포넌트가 `position: sticky`와 `top: 0`을 적용하므로 스크롤 컨테이너 안에 배치해야 합니다.

```tsx
const scrollContainerRef = useRef<HTMLDivElement>(null);

return (
  <div ref={scrollContainerRef} style={{ height: 480, overflowY: "auto" }}>
    <ScrollAutoHide scrollContainerRef={scrollContainerRef}>
      <nav>필터</nav>
    </ScrollAutoHide>
    <main>{/* 스크롤할 콘텐츠 */}</main>
  </div>
);
```

### 다른 요소를 루트로 사용하기

`asChild`를 사용하면 불필요한 래퍼 없이 자식 요소를 루트로 사용합니다. 자식은 하나의 React 요소여야 합니다.

```tsx
<ScrollAutoHide scrollContainerRef={scrollContainerRef} asChild>
  <header>필터</header>
</ScrollAutoHide>
```

## 동작과 스타일

- 스크롤 중에는 이동 거리를 그대로 따라갑니다. 스크롤이 끝나면 50% 지점을 기준으로 완전히 숨거나 드러납니다.
- 스냅은 200ms 동안 SEED의 `enter` 타이밍 함수인 `cubic-bezier(0, 0, 0.15, 1)`을 사용합니다.
- 모션 감소 설정에서는 위치 이동을 피하기 위해 자동 숨김을 비활성화합니다.
- 숨겨진 영역 안으로 키보드 포커스가 이동하면 내용을 즉시 드러냅니다.
- 컴포넌트는 넓은 웹뷰 버전에서 합성할 수 있도록 `translate3d()`를 사용합니다. `ScrollTimeline`을 지원하는 브라우저에서는 스크롤과 이동을 브라우저가 직접 연결하고, 그 외 환경에서는 같은 동작을 스크롤 이벤트로 처리합니다.
- 루트 요소의 `transform`은 내부 이동에 사용합니다. 별도의 `transform`이 필요하면 자식 요소에 적용합니다.
- 배경색과 `z-index`는 사용 환경에 맞게 직접 지정합니다. 배경색이 없으면 숨겨지는 동안 아래 콘텐츠가 비칠 수 있습니다.

## Props