Field

Field (필드)

폼 필드에 라벨, 도움말 텍스트, 오류 메시지를 추가할 때 사용하는 컴포넌트예요. 폼 입력 요소를 감싸서 접근성 좋은 구조를 만들어 줘요.

출처: 문서

본문

사용법 (Usage)

import { Field } from "@chakra-ui/react"

<Field.Root>
  <Field.Label>
    <Field.RequiredIndicator />
  </Field.Label>
  <Input />
  <Field.HelperText />
  <Field.ErrorText />
</Field.Root>

:::info

닫힌 컴포넌트 조합(closed component composition)을 선호한다면 아래 스니펫을 확인해 보세요.

:::

예제 (Examples)

오류 텍스트 (Error Text)

Field.Root에 invalid prop을 넘기고 Field.ErrorText를 사용해서 필드가 잘못되었음을 나타낼 수 있어요.

| 예제 (field-with-error-text) |

오류 아이콘 (Error Icon)

Field.ErrorIcon은 주변 텍스트 색상을 상속받고 기본값이 1em이라서, Field.ErrorText가 전체 너비로 늘어나도 크기가 일관되게 유지돼요.

| 예제 (field-with-error-icon) |

도움말 텍스트 (Helper Text)

Field.HelperText를 사용해서 필드에 도움말 텍스트를 추가할 수 있어요.

| 예제 (field-with-helper-text) |

가로 배치 (Horizontal)

orientation="horizontal" prop을 사용해서 라벨과 입력을 가로로 정렬할 수 있어요.

| 예제 (field-horizontal) |

비활성화 (Disabled)

disabled prop을 사용해서 필드를 비활성화할 수 있어요.

| 예제 (field-with-disabled) |

텍스트 영역 (Textarea)

field 컴포넌트를 텍스트 영역과 함께 사용하는 방법이에요.

| 예제 (field-with-textarea) |

네이티브 셀렉트 (Native Select)

field 컴포넌트를 네이티브 셀렉트와 함께 사용하는 방법이에요.

| 예제 (field-with-native-select) |

대상 컨트롤 (Target Control)

Field.Root의 target prop을 라벨이 가리켜야 할 항목으로 설정할 수 있어요.

| 예제 (field-with-target-control) |

필수 (Required)

Field.Root에 required prop을 넘기고 Field.RequiredIndicator를 사용해서 필드가 필수임을 나타낼 수 있어요.

| 예제 (field-with-required) |

선택 사항 (Optional)

Field.RequiredIndicator에 fallback prop을 넘겨서 선택 사항 텍스트를 추가할 수 있어요.

| 예제 (field-with-optional) |

닫힌 컴포넌트 (Closed Component)

닫힌 컴포넌트 조합을 위해 Field를 구성하는 방법이에요.

| 예제 코드 (field-closed-component) |

프로젝트에 닫힌 컴포넌트를 자동으로 추가하고 싶다면 다음 명령을 실행하세요.

npx @chakra-ui/cli snippet add field

커스터마이즈 (Customization)

슬롯 커스터마이즈 (Customizing slots)

Field 컴포넌트에는 커스터마이즈할 수 있는 여러 슬롯이 있어요. 아래 Explorer에서 사용 가능한 모든 슬롯을 확인할 수 있어요.

import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
import { fieldSlotRecipe } from "@chakra-ui/react/recipes"

const customFieldRecipe = fieldSlotRecipe.extend({
  base: {
    label: {
      color: "blue.600",
      fontWeight: "bold",
    },
    errorText: {
      bg: "red.50",
      p: "2",
      borderRadius: "md",
    },
    helperText: {
      fontStyle: "italic",
    },
    requiredIndicator: {
      color: "orange.500",
    },
  },
})

const config = defineConfig({
  theme: {
    slotRecipes: {
      field: customFieldRecipe,
    },
  },
})

export const system = createSystem(defaultConfig, config)

새 변형 추가 (Adding new variants)

Field 레시피를 확장해서 새로운 레이아웃이나 스타일 변형(variant)을 추가할 수 있어요.

const customFieldRecipe = fieldSlotRecipe.extend({
  variants: {
    variant: {
      // 새 스타일 변형 추가
      outlined: {
        root: {
          border: "1px solid",
          borderColor: "border",
          borderRadius: "md",
          p: "3",
        },
        label: {
          bg: "bg",
          px: "2",
          position: "absolute",
          top: "-2",
          left: "3",
        },
      },
    },
    size: {
      // 새 크기 변형 추가
      lg: {
        root: {
          gap: "3",
        },
        label: {
          textStyle: "md",
        },
      },
    },
  },
})

커스터마이즈한 후에는 typegen 명령을 실행해서 타입을 다시 생성하세요. postinstall, CI, monorepo에서 typegen을 실행하는 방법은 CLI 문서에서 확인할 수 있어요.

npx @chakra-ui/cli typegen ./theme.ts

Props

Root

| PropTable (Field / Root) |

탐색 (Explorer)

Field 컴포넌트의 각 부분을 인터랙티브하게 살펴볼 수 있어요. 사이드바에서 부분을 클릭하면 미리보기에서 강조 표시돼요.

| 예제 (field-explorer-demo) |