React

Field Button

입력 필드 형태의 버튼으로, 선택창이나 피커를 열 때 사용합니다. 선택이 완료되면 버튼 라벨에 선택된 값이 표시됩니다.

Installation

npx @seed-design/cli@latest add ui:field-button

Props

FieldButton

Prop

Type

label?React.ReactNode
indicator?React.ReactNode
prefixIcon?React.ReactNode
prefix?React.ReactNode
suffixIcon?React.ReactNode
suffix?React.ReactNode
description?React.ReactNode
errorMessage?React.ReactNode
showRequiredIndicator?boolean | undefined
showClearButton?boolean | undefined
buttonProps?SeedFieldButton.ButtonProps | undefined
rootRef?React.Ref<HTMLDivElement> | undefined
name?string | undefined
values?string[] | undefined
onValuesChange?((values: string[]) => void) | undefined

FieldButtonValue

Prop

Type

FieldButtonPlaceholder

Prop

Type

Examples

Basic Usage

FieldButtonTextField와 유사한 외관을 갖지만, 근본적으로 내부에 <button> 요소를 포함하는 컴포넌트입니다. 사용자는 buttonProps prop을 통해 버튼의 속성을 제어할 수 있습니다.

  • buttonProps
    • onClick: 버튼 클릭 핸들러
    • aria-label: 버튼의 접근성 레이블
  • children
    • FieldButtonValue 또는 FieldButtonPlaceholder 등을 사용하여 구성
    • FieldButtonValueFieldButtonPlaceholder는 스타일 차이만 있을 뿐 기능적으로 동일합니다. 스크린 리더는 두 요소를 읽거나 구분하지 않습니다. 접근성을 위해 buttonProps["aria-label"]에 적절한 값을 제공하세요. 자세한 내용은 Accessibility 섹션을 참고하세요.

Clear Button

showClearButton prop을 true로 설정하면 Clear Button이 표시됩니다. showClearButtontrue로 설정하는 경우 onValuesChange prop을 제공해야 합니다.

FieldButtondisabled 또는 readOnly 상태인 경우 Clear Button은 표시되지 않습니다.

FieldButtonValue & FieldButtonPlaceholder

<FieldButton> 내부에 children으로 넣어 사용할 수 있는 단순한 <div> 요소입니다.

스크린 리더는 FieldButtonValueFieldButtonPlaceholder를 읽지 않습니다. buttonProps["aria-label"]에 적절한 값을 제공하여 접근성을 확보하세요. 자세한 내용은 Accessibility 섹션을 참고하세요.

Accessibility

Field Button 내부 buttonaria-label 속성을 제공하세요. 스크린 리더 사용자가 Field Button을 클릭했을 때 어떤 일이 일어날지 예상할 수 있도록 해야 하며, 현재 선택된 값이 있는 경우 그 값이 무엇인지도 알려야 합니다.

<FieldButton
  label="사용자 이름" // 스크린 리더는 label을 읽습니다.
  description="본명을 사용하지 않아도 괜찮습니다." // 스크린 리더는 description을 버튼과 함께 읽습니다.
  buttonProps={{
    // 버튼을 클릭했을 때 어떤 일이 일어날지, 현재 선택된 값이 무엇인지 알려야 합니다.
    "aria-label": `사용자 이름 선택 화면 열기. 현재 선택된 이름: ${username || "없음"}`, 
    "aria-haspopup": "dialog",
    onClick: () => setIsUsernamePickerOpen(true),
  }}
>
  {username ? (
    <FieldButtonValue>{username}</FieldButtonValue> // 스크린 리더는 FieldButtonValue를 읽지 않습니다.
  ) : (
    <FieldButtonPlaceholder>김하늘</FieldButtonPlaceholder> // 스크린 리더는 FieldButtonPlaceholder를 읽지 않습니다.
  )}
</FieldButton>

화면을 볼 수 있는 사용자는 Field Button이 클릭할 수 있는 요소라는 점과, Field Button을 클릭했을 때 일어날 동작을 쉽게 예측할 수 있지만, 스크린 리더 사용자는 buttonaria-label 속성이 없는 경우 Field Button을 클릭했을 때 어떤 일이 일어날지 파악하기 어렵습니다.

Use Cases

Form

FieldButtonvalues prop을 제공하는 경우 폼 제출에 활용할 수 있도록 <input type="hidden" />을 함께 렌더링합니다.

Form and Bottom Sheet

React Hook Form

Multiple Values (React Hook Form (Field Array))

Multiple Values (Native form)

State

Enabled

Disabled

  • values를 제공할 때 렌더링되는 <input type="hidden" />도 함께 disabled 처리되어 폼 제출 시 값이 전송되지 않습니다.
  • <button> 요소도 disabled 처리되어 클릭할 수 없게 됩니다.

Read Only

  • values를 제공할 때 렌더링되는 <input type="hidden" />은 영향을 받지 않습니다.
  • <button> 요소는 disabled 처리되어 클릭할 수 없게 됩니다.

Size

size로 FieldButton의 크기를 정합니다. (default: large)

responsive는 화면 너비에 따라 size가 자동으로 전환되는 값입니다. 여러 화면 너비를 함께 지원하는 제품에서 size=responsive를 사용하여 대응합니다.

Customizable Parts

Prefix

Suffix

Both Affixes

Indicator

Last updated on

On this page