Popover

트리거를 누르면 그 옆에 열리는 작은 창이에요. 안에 값을 고르거나 켜고 끄는 컨트롤을 둬요. 필터 조건이나 공유 범위처럼 늘 보일 필요가 없는 설정에 써요. 안에 누를 것 없이 짧은 글만 보일 때는 Tooltip을 써요.

사용 예시

설정 모음

자주 바꾸는 설정을 모아 둘 때 써요. 트리거 버튼에는 열리는 내용의 이름을 적어요.

tsx

<Popover>  <PopoverTrigger render={<Button color="neutral" emphasis="outline" />}>    <ListFilter />    필터  </PopoverTrigger>  <PopoverContent className="w-56" aria-label="필터">    <div className="flex flex-col gap-stack">      <Field>        <FieldLabel>최근 며칠</FieldLabel>        <NumberField value={days} onValueChange={setDays} decrementLabel="기간 줄이기" incrementLabel="기간 늘리기" min={1} max={30} size="sm" />      </Field>      <Field layout="split">        <FieldLabel>완료한 항목 포함</FieldLabel>        <Switch checked={withDone} onCheckedChange={setWithDone} />      </Field>    </div>  </PopoverContent></Popover>

권장

안에서 값을 고르거나 바꿀 때 써요.

지양

글만 보일 때는 Tooltip을 써요. Popover는 열리면 포커스가 안으로 이동해서 읽기만 하는 내용에는 맞지 않아요.

고르면 닫기

고른 값이 바로 적용될 때 써요. 버튼을 PopoverClose로 감싸면 onClick이 실행된 뒤 Popover가 닫혀요.

tsx

<Popover>  <PopoverTrigger render={<Button color="neutral" emphasis="outline" className="w-36" />}>    <Users />    {scope}  </PopoverTrigger>  <PopoverContent className="w-56" aria-label="보이는 범위">    <div className="flex flex-col gap-stack">      <div className="grid grid-cols-2 gap-2">        {scopes.map(s => (          <PopoverClose            key={s}            render={(              <Button                color="neutral" emphasis="outline"                size="sm"                className="w-full"                onClick={() => setScope(s)}              />            )}          >            {s}          </PopoverClose>        ))}      </div>      <Field>        <FieldLabel>만료일</FieldLabel>        <Input value={expiry} onChange={e => setExpiry(e.target.value)} placeholder="9월 30일" size="sm" />      </Field>    </div>  </PopoverContent></Popover>

PopoverAnchor

PopoverContent를 트리거보다 넓은 영역에 맞춰 열 때 써요. PopoverContent가 PopoverAnchor만큼 넓으면 화살표가 가리킬 곳이 없어서 arrow를 false로 둬요.

tsx

<Popover>  <PopoverAnchor className="flex w-full max-w-80 items-center gap-2">    <Input value={keyword} onChange={e => setKeyword(e.target.value)} placeholder="이름으로 찾기" />    <PopoverTrigger render={<Button color="neutral" emphasis="outline" shape="square" aria-label="필터 조건" />}>      <SlidersHorizontal />    </PopoverTrigger>  </PopoverAnchor>  <PopoverContent align="start" arrow={false} className="w-80" aria-label="필터 조건">    <div className="flex flex-col gap-stack">      <Field layout="split">        <FieldLabel>보관함 포함</FieldLabel>        <Switch checked={withArchived} onCheckedChange={setWithArchived} />      </Field>    </div>  </PopoverContent></Popover>

권장

버튼이 나란히 있어도 화살표를 보면 어느 버튼에서 열렸는지 알 수 있어요.

지양

화살표가 없으면 어느 버튼에서 열렸는지 알기 어려워요.

뜨는 방향

tsx

<Popover>  <PopoverTrigger render={<Button color="neutral" emphasis="outline" size="sm" />}>top</PopoverTrigger>  <PopoverContent side="top" className="w-44" aria-label="뜨는 방향">    <Field layout="split">      <FieldLabel>즐겨찾기만</FieldLabel>      <Switch checked={starredOnly} onCheckedChange={setStarredOnly} />    </Field>  </PopoverContent></Popover>

권장

설정이 몇 개뿐이라 열면 스크롤 없이 전부 보여요.

지양

길어지면 PopoverContent가 화면 밖으로 넘어가서 잘려요. 설정이 많으면 Dialog를 써요.

호출하는 쪽에서 여닫기

트리거 말고 다른 버튼으로도 열어야 할 때 써요. 트리거를 눌러도 그대로 열려요.

보이는 항목이 없어요

필터 조건을 확인해 보세요.

tsx

<Popover open={filterOpen} onOpenChange={setFilterOpen}>  <PopoverTrigger render={<Button color="neutral" emphasis="outline" />}>    <ListFilter />    필터  </PopoverTrigger>  <PopoverContent className="w-56" aria-label="필터">    <Field>      <FieldLabel>최근 며칠</FieldLabel>      <NumberField value={days} onValueChange={setDays} decrementLabel="기간 줄이기" incrementLabel="기간 늘리기" min={1} max={30} size="sm" />    </Field>  </PopoverContent></Popover><Callout color="warning" title="보이는 항목이 없어요">  필터 조건을 확인해 보세요.  <Button color="neutral" emphasis="ghost" size="sm" onClick={() => setFilterOpen(true)}>    필터 열기  </Button></Callout>

Trigger 없이 열기

달력의 날짜, 표의 셀처럼 누른 곳마다 기준이 다르면 open과 anchor로 열어요. anchor에는 요소, ref, getBoundingClientRect를 가진 가상 요소, 그 값을 돌려주는 함수를 넘길 수 있어요. 바깥을 누르거나 Esc를 누르면 닫혀요.

tsx

const [picked, setPicked] = useState<{ el: HTMLElement, date: number } | null>(null){week.map(d => (  <button key={d.date} type="button" onClick={e => setPicked({ el: e.currentTarget, date: d.date })}>    {d.day} {d.date}  </button>))}<Popover open={picked !== null} onOpenChange={open => !open && setPicked(null)}>  <PopoverContent anchor={picked?.el} side="bottom" aria-label="일정">…</PopoverContent></Popover><PopoverContent anchor={{ getBoundingClientRect: () => DOMRect.fromRect({ x, y, width: 0, height: 0 }) }}>  …</PopoverContent>

컨트롤

side

align

arrow

값7

tsx

<Popover>  <PopoverTrigger render={<Button color="neutral" emphasis="outline" />}>필터</PopoverTrigger>  <PopoverContent className="w-44" aria-label="필터">    <Field>      <FieldLabel>최근 며칠</FieldLabel>      <NumberField value={days} onValueChange={setDays} decrementLabel="기간 줄이기" incrementLabel="기간 늘리기" min={1} max={30} size="sm" />    </Field>  </PopoverContent></Popover>

명세

이름
이름	값	기본
Popover
open	boolean	-
호출하는 쪽에서 열림 상태를 관리해요.
defaultOpen	boolean	false
처음에 열어 둘지 정해요.
onOpenChange	(open: boolean, eventDetails) => void	-
열리거나 닫히면 호출돼요.
render	ReactElement	-
기본 요소 대신 그릴 요소예요. PopoverTrigger와 PopoverClose에 Button을 넘길 때 써요.
className	string	-
PopoverContent
side	top, right, bottom, left	bottom
지정한 쪽에 공간이 없으면 반대쪽에 떠요.
align	start, center, end	center
트리거를 기준으로 PopoverContent를 맞추는 위치예요.
arrow	boolean	true
트리거나 PopoverAnchor를 가리키는 화살표를 보여요.
anchor	Element, ref, 가상 요소, 함수	-
트리거 대신 기준으로 삼을 곳이에요. getBoundingClientRect를 가진 객체를 넘기면 화면 좌표 사각형을 기준으로 열어요. PopoverAnchor보다 먼저예요.
sideOffset	number, 함수	14, arrow가 없으면 8
기준과 떨어진 거리예요. 단위는 px이에요.
alignOffset	number, 함수	0
align 방향으로 옮기는 거리예요. 단위는 px이에요.
collisionAvoidance	object	-
화면 가장자리에 닿을 때 뒤집을지, 밀어 넣을지 정해요. Base UI Positioner의 값을 그대로 받아요.