Input · Overview

스토리북 개발자들을 위한 내부 문서

Components

Input

Overview

Input은 텍스트 입력을 위한하는 폼 컨트롤입니다. 레이블·설명·에러는 별도 패키지 @/components/field (Field · FieldLabel · FieldDescription · FieldError)와 조합합니다. 검증 UI는 Input이 강제하지 않습니다. 에러를 반환한 뒤 앱 규약(FieldError · Alert · Toast 등)에 맞게 표시하세요.

Placeholder

비어 있을 때 보이는 힌트 텍스트입니다. Input.placeholder로 전달합니다. 레이블·설명은 @/components/field의 FieldLabel · FieldDescription과 조합합니다. 아이콘을 붙일 때는 appearance="plain"으로 Input 크롬을 끄고, 상위 div에 inputChromeClassName으로 focus-within 강조를 둡니다.

Descriptiond: 기본 input 창에 대한 설명을 추가할 수 있습니다.

Description: 아이콘 추가, 상위 div 추가로 스타일링 가능합니다.

레이블·설명은 @/components/field의 FieldLabel · FieldDescription을 쓰고, Input 보더·포커스는 appearance="plain"으로 끈 뒤 상위 div에 inputChromeClassName으로 focus-within 강조를 둡니다.

import { Field, FieldLabel, FieldDescription } from "@/components/field";
import { Input, inputChromeClassName } from "@/components/input";

<Field className="flex flex-col gap-[var(--gap-8)]">
  <FieldLabel htmlFor="search">검색</FieldLabel>
  <div className={inputChromeClassName}>
    <Icon name="bookmark" />
    <Input id="search" appearance="plain" placeholder="검색어" className="flex-1" />
  </div>
  <FieldDescription>아이콘은 래퍼에, 포커스는 focus-within으로.</FieldDescription>
</Field>
Required

필수 입력. 포커스아웃 시 미입력이면 에러 보더(aria-invalid). 제출 버튼은 API Alert(fail / success) 데모용입니다. 필드 검증 실패 → 보더만.

포커스아웃 시 미입력 → 보더. 제출은 API Alert(fail/success) 데모

required — 포커스아웃 시 필수 검증

// 필드 검증(필수·minLength) → blur 시 보더
// 형식(비숫자) → onChange 입력 방지 + 보더
// API 실패 → 제출 시 Alert(fail)

function onNicknameBlur() {
  if (!nickname.trim()) {
    setFieldError("nickname", "필수 항목입니다.");
  }
}

function onPhoneChange(value: string) {
  if (value !== "" && !/^\d*$/.test(value)) {
    setFieldError("phone", "숫자만 입력할 수 있습니다.");
    return; // 값 미반영
  }
  setPhone(value);
  clearFieldError("phone"); // 수정으로 유효해지면 해제 (포커스만으로는 X)
}

async function onSubmit() {
  if (!nickname.trim()) {
    setFieldError("nickname", "필수 항목입니다.");
    return;
  }
  const res = await api.submit(...);
  if (!res.ok) {
    // Alert(fail, position="top") — API 실패에만
    return;
  }
  // Alert(success) 또는 앱 규약
}
Max Length

최대 입력 글자 수. 초과 입력을 막습니다.

0/8자 · 초과 입력 방지

Disabled

입력·포커스 상호작용을 막습니다.

disabled — 입력 불가

Read Only

포커스는 가능하지만 값을 바꿀 수 없습니다.

readOnly — 포커스만 가능

Min Length

최소 입력 글자 수. 포커스아웃 시 부족하면 에러 보더(FieldError). 유효해지면 수정 시 보더가 해제됩니다.

minLength={4} — 포커스아웃 시 최소 길이 검증

Pattern

허용 형식. Overview 휴대폰은 비숫자 입력 시 값 입력 방지 + 보더 에러(Alert 아님).

비숫자 입력 시 값 입력 방지 + 보더 에러

States

인터랙션·검증 상태입니다. Overview에서 강제 표시합니다. Error는 FieldError(@/components/field)와 함께 봅니다.

  • Default기본 상태입니다.
  • Hover포인터가 올라간 상태입니다.
  • Focus키보드·클릭으로 포커스된 상태입니다.
  • Disabled입력할 수 없습니다.
  • Error검증 실패. FieldError와 함께 표시합니다.
DefaultHoverFocusDisabledError