Field Guide | Next UI Components Guide

Field

Field / form layout

Field는 label, description, message와 입력 요소를 한 흐름으로 묶고, Field.Item과 Field.Grid로 행/열 레이아웃을 조합하는 폼 레이아웃 컴포넌트입니다.

Prop

inputId | direction | align | infoMessage | errorMessage | Field.Label | Field.Description | Field.Message

string | "row" | "column" | "start" | "center"

Field root는 하나의 폼 블록 스코프입니다. inputId로 label 연결을 고정하고, infoMessage/errorMessage 또는 Field.Message로 안내 문구를 배치할 수 있습니다. error 상태는 내부 입력 컴포넌트와 자동으로 공유됩니다.

라벨 영역

Label은 htmlFor를 자동 연결하고, Field에 errorMessage가 있으면 Textfield도 같은 에러 스타일을 받습니다.

Field 레벨 에러 메시지입니다.

라벨 영역

Field.Message를 직접 두면 현재 스코프 아래에 안내 문구를 별도로 배치할 수 있습니다.

Prop

Field.Item

direction?: "row" | "column"align?: "start" | "center"infoMessage?: stringerrorMessage?: string

Field.Item은 하나의 행 스코프입니다. 독립적으로 써도 되고 Field 안에 넣어도 되며, 자신의 infoMessage/errorMessage만으로도 내부 input이 동일한 상태를 받습니다.

label의 텍스트가 길 때 예시입니다. 약관 제목이나 긴 안내 문구처럼 두 줄 이상으로 내려가더라도 체크박스와 label, description이 같은 행 스코프 안에서 자연스럽게 정렬되는지 확인하기 위한 샘플 문구입니다.

align=start는 label의 텍스트와 input의 레이아웃을 상단으로 수정합니다.

Field.Item 레벨 안내 메시지입니다.Field.Item 레벨 에러 메시지입니다.

span label

Radio 1

Radio 2

Radio 3

as=span은 input과 label의 id, htmlFor 연결이 불필요한 그룹 제목이나 보조 라벨에 사용합니다.

Prop

Field.Grid

columns?: 1 | 2 | 3 | 4

좌우 배치는 별도 div 대신 Field.Grid으로 처리합니다. Field.Grid은 레이아웃만 담당하고, 각 자식 Field/Field.Item의 inputId 스코프는 건드리지 않습니다.

카테고리

카테고리를 선택해주세요

작업 날짜

Prop

form composition

layout example

지금까지 만든 입력 컴포넌트를 Field로 묶어 실제 폼 흐름으로 배치한 예시입니다. label, description, message를 함께 보면서도 레이아웃은 Field, Field.Item, Field.Grid만으로 구성합니다.

담당자 검색

최근 검색 키워드: 최찬식

프로젝트 제목

비밀번호

카테고리

카테고리를 선택해주세요

작업 날짜

공개 범위

전체 공개

링크 공개

비공개

링크 공유기능 켜기

해당 프로젝트는 포트폴리오 용도로만 사용됨을 확인하였습니다.

요약 메모

필수 입력란입니다.

Props Table

Field props 한눈에 보기

Field root 스코프가 제공하는 레이아웃과 메시지 공유 규칙을 표로 정리했습니다.

Prop	Type	Default	Required	Description
`children`	`React.ReactNode`	-	Required	Field.Label, 입력 컴포넌트, Field.Description, Field.Message 같은 하위 요소를 한 스코프로 묶습니다.
`inputId`	`string`	`auto generated id`	Optional	Field.Label의 htmlFor와 내부 입력 컴포넌트의 id를 강제로 고정하고 싶을 때 사용합니다.
`direction`	`"row" \| "column"`	`"column"`	Optional	라벨/입력/설명 흐름의 기본 배치를 결정합니다. 일반 폼 블록은 column이 기본입니다.
`align`	`"start" \| "center"`	`"start"`	Optional	자식 요소의 교차축 정렬을 제어합니다. checkbox/switch 행 정렬과 함께 자주 씁니다.
`infoMessage \| errorMessage`	`string`	`""`	Optional	Field 하단 메시지 슬롯에 안내/에러 문구를 출력합니다. errorMessage가 있으면 현재 스코프 전체가 에러 상태가 됩니다.
`isError`	`boolean`	`false`	Optional	메시지 없이 시각 에러 상태만 강제로 줄 때 사용합니다. errorMessage가 있으면 자동으로 true처럼 동작합니다.
`className`	`string`	`undefined`	Optional	Field root wrapper에 커스텀 클래스를 추가합니다.
`id \| style \| role \| data-* ...`	`native div props`	`inherited`	Optional	Field가 직접 제어하지 않는 div 속성은 루트 wrapper에 그대로 전달됩니다.

Field는 현재 스코프의 inputId, labelId, describedByIds, isError를 context로 공유합니다. 그래서 내부 입력 컴포넌트와 Field.Label, Field.Description, Field.Message가 자동으로 연결됩니다.

Props Table

Field.Item props 한눈에 보기

한 행 단위 입력 스코프를 만드는 Field.Item의 정렬과 메시지 규칙을 정리했습니다.

Prop	Type	Default	Required	Description
`children`	`React.ReactNode`	-	Required	checkbox, radio, switch처럼 한 행 단위로 묶고 싶은 입력과 라벨/설명 조합을 넣습니다.
`inputId`	`string`	`auto generated id`	Optional	현재 Item 스코프 안에서 사용할 입력 id를 고정합니다. 중첩 Field 안에서도 독립적으로 동작합니다.
`direction`	`"row" \| "column"`	`"row"`	Optional	Item 내부 요소의 흐름 방향입니다. 라벨-입력 한 줄 배치는 row가 기본입니다.
`align`	`"start" \| "center"`	`"center"`	Optional	row 배치에서 입력과 긴 라벨 텍스트의 수직 정렬을 맞출 때 주로 사용합니다.
`infoMessage \| errorMessage`	`string`	`""`	Optional	현재 Item 스코프 하단 메시지를 출력합니다. Field root 안에 중첩해도 자기 범위 메시지만 처리합니다.
`isError`	`boolean`	`false`	Optional	메시지 없이 시각 에러 상태만 강제로 줄 때 사용합니다. 부모 Field의 에러 상태와 합쳐집니다.
`className`	`string`	`undefined`	Optional	Field.Item wrapper에 커스텀 클래스를 추가합니다.
`id \| style \| role \| data-* ...`	`native div props`	`inherited`	Optional	Field.Item이 직접 제어하지 않는 div 속성은 wrapper에 그대로 전달됩니다.

Field.Item도 독립적인 Field scope를 새로 만듭니다. 그래서 부모 Field 안에 있어도 자신만의 inputId, describedByIds, isError를 가질 수 있습니다.

Props Table

Field.Grid props 한눈에 보기

Field.Grid은 레이아웃만 담당하고, 자식 Field 스코프는 건드리지 않습니다.

Prop	Type	Default	Required	Description
`children`	`React.ReactNode`	-	Required	보통 여러 개의 Field 또는 Field.Item 블록을 grid 레이아웃으로 배치합니다.
`columns`	`1 \| 2 \| 3 \| 4`	`2`	Optional	CSS custom property로 grid 열 수를 제어합니다. 모바일 대응은 스타일 정의를 따릅니다.
`className`	`string`	`undefined`	Optional	Field.Grid wrapper에 커스텀 클래스를 추가합니다.

Field.Grid은 단순 layout wrapper입니다. 내부에서 context를 새로 만들지 않으므로, 각 자식 Field 또는 Field.Item이 자신의 scope를 그대로 유지합니다.

Props Table

Field.Label props 한눈에 보기

Field.Label은 label/span 이중 모드를 지원하며, 기본적으로 현재 Field scope의 inputId와 연결됩니다.

Prop	Type	Default	Required	Description
`children`	`React.ReactNode`	`undefined`	Optional	라벨 텍스트나 커스텀 inline 내용을 표시합니다.
`as`	`"label" \| "span"`	`"label"`	Optional	기본은 실제 label 태그이고, 그룹 제목처럼 입력 연결이 필요 없으면 span으로 바꿉니다.
`htmlFor`	`string`	`field inputId`	Optional	as='label'일 때만 사용할 수 있습니다. 생략하면 현재 Field scope의 inputId를 자동 연결합니다.
`id`	`string`	`field labelId`	Optional	생략하면 현재 Field scope에서 생성한 label id를 사용합니다.
`className`	`string`	`undefined`	Optional	Field.Label element에 커스텀 클래스를 추가합니다.
`title \| onClick \| aria-* ...`	`native label/span props`	`inherited`	Optional	as 값에 따라 label 또는 span의 native 속성을 그대로 전달할 수 있습니다.

Field.LabelProps는 as="label"과 as="span" 유니온 타입입니다. span 모드에서는 htmlFor를 받을 수 없고, 그룹 제목처럼 input과 직접 연결되지 않는 라벨에 사용합니다.

Props Table

Field.Description props 한눈에 보기

Field.Description은 보조 설명 문구를 출력하면서 현재 스코프의 describedBy에 자동 등록됩니다.

Prop	Type	Default	Required	Description
`children`	`React.ReactNode`	`undefined`	Optional	입력 아래에 붙는 보조 설명 문구나 추가 가이드를 출력합니다.
`id`	`string`	`auto generated description id`	Optional	생략하면 자동 id를 만들고 현재 Field scope에 등록해 aria-describedby에 연결합니다.
`className`	`string`	`undefined`	Optional	Field.Description element에 커스텀 클래스를 추가합니다.
`title \| aria-* ...`	`native p props`	`inherited`	Optional	Field.Description이 직접 제어하지 않는 p 속성은 그대로 전달됩니다.

Field.Description은 렌더 시 자신의 id를 현재 Field scope에 등록합니다. 그래서 내부 입력 컴포넌트가 aria-describedby를 자동으로 이어받을 수 있습니다.

Props Table

Field.Message props 한눈에 보기

Field.Message는 현재 스코프 아래에 메시지 슬롯을 직접 배치하고 싶을 때 사용합니다.

Prop	Type	Default	Required	Description
`infoMessage`	`string`	`""`	Optional	보조 안내 메시지를 출력합니다.
`errorMessage`	`string`	`""`	Optional	에러 메시지를 출력합니다. 내부 Message 컴포넌트 규칙에 따라 infoMessage보다 우선적으로 보일 수 있습니다.
`id`	`string`	`auto generated message id`	Optional	생략하면 자동 id를 만들고, 실제 메시지 내용이 있을 때만 현재 Field scope에 등록합니다.
`className`	`string`	`undefined`	Optional	Field.Message wrapper에 커스텀 클래스를 추가합니다.

Field.Message는 내용이 있을 때만 현재 Field scope에 자신의 id를 등록합니다. 따라서 빈 상태에서는 불필요한 aria-describedby 연결을 만들지 않습니다.