Text Field

버튼과 아이콘을 위한 선택적 슬롯(slot)을 가진 입력 컴포넌트예요.

출처: 문서

본문

단일 행 텍스트를 입력받는 필드로, 앞뒤에 아이콘이나 버튼을 배치할 수 있어요.

<TextField.Root placeholder="Search the docs…">
  <TextField.Slot>
    <MagnifyingGlassIcon height="16" width="16" />
  </TextField.Slot>
</TextField.Root>

Root

Slot과 Input 부분을 묶어요. 이 컴포넌트는 div 요소를 기반으로 하며, 공통 margin props를 지원해요.

Prop	Type	Default
`size`	`Responsive<"1" \| "2" \| "3">`	`"2"`
`variant`	`"classic" \| "surface" \| "soft"`	`"surface"`
`color`	`enum`	No default value
`radius`	`"none" \| "small" \| "medium" \| "large" \| "full"`	No default value

Slot

Input과 연결된 아이콘이나 버튼을 담아요.

Prop	Type	Default
`side`	`"left" \| "right"`	No default value
`color`	`enum`	No default value
`gap`	`Responsive<enum \| string>`	No default value
`px`	`Responsive<enum \| string>`	No default value
`pl`	`Responsive<enum \| string>`	No default value
`pr`	`Responsive<enum \| string>`	No default value

예시 (Examples)

Size

size prop으로 크기를 제어할 수 있어요.

<Flex direction="column" gap="3">
  <Box maxWidth="200px">
    <TextField.Root size="1" placeholder="Search the docs…" />
  </Box>

  <Box maxWidth="250px">
    <TextField.Root size="2" placeholder="Search the docs…" />
  </Box>

  <Box maxWidth="300px">
    <TextField.Root size="3" placeholder="Search the docs…" />
  </Box>
</Flex>

TextField를 버튼과 조합할 때는 서로 일치하는 컴포넌트 크기를 사용해 주세요. 다만 size 1 입력은 버튼과 함께 쓰지 않는 게 좋아요. 이 크기에서는 다른 상호작용 요소를 중첩할 세로 공간이 충분하지 않거든요.

<Flex direction="column" gap="3" maxWidth="400px">
  <Box maxWidth="200px">
    <TextField.Root placeholder="Search the docs…" size="1">
      <TextField.Slot>
        <MagnifyingGlassIcon height="16" width="16" />
      </TextField.Slot>
    </TextField.Root>
  </Box>

  <Box maxWidth="250px">
    <TextField.Root placeholder="Search the docs…" size="2">
      <TextField.Slot>
        <MagnifyingGlassIcon height="16" width="16" />
      </TextField.Slot>

      <TextField.Slot>
        <IconButton size="1" variant="ghost">
          <DotsHorizontalIcon height="14" width="14" />
        </IconButton>
      </TextField.Slot>
    </TextField.Root>
  </Box>

  <Box maxWidth="300px">
    <TextField.Root placeholder="Search the docs…" size="3">
      <TextField.Slot>
        <MagnifyingGlassIcon height="16" width="16" />
      </TextField.Slot>

      <TextField.Slot pr="3">
        <IconButton size="2" variant="ghost">
          <DotsHorizontalIcon height="16" width="16" />
        </IconButton>
      </TextField.Slot>
    </TextField.Root>
  </Box>
</Flex>

Variant

variant prop으로 시각적 스타일을 제어할 수 있어요.

<Flex direction="column" gap="3" maxWidth="250px">
  <TextField.Root variant="surface" placeholder="Search the docs…" />

  <TextField.Root variant="classic" placeholder="Search the docs…" />

  <TextField.Root variant="soft" placeholder="Search the docs…" />
</Flex>

Color

color prop으로 특정 색상을 지정할 수 있어요.

<Flex direction="column" gap="3" maxWidth="250px">
  <TextField.Root color="indigo" variant="soft" placeholder="Search the docs…" />

  <TextField.Root color="green" variant="soft" placeholder="Search the docs…" />

  <TextField.Root color="red" variant="soft" placeholder="Search the docs…" />
</Flex>

Radius

radius prop으로 특정 둥근 모서리 값을 지정할 수 있어요.

<Flex direction="column" gap="3" maxWidth="250px">
  <TextField.Root radius="none" placeholder="Search the docs…" />

  <TextField.Root radius="large" placeholder="Search the docs…" />

  <TextField.Root radius="full" placeholder="Search the docs…" />
</Flex>

더 알아보기 (Learn more)

TextField.Slot를 사용해 검색 아이콘 같은 요소를 필드 안에 자연스럽게 배치할 수 있어요.