TextField

사용자로부터 텍스트를 입력받는 컴포넌트입니다. 다양한 타입과 상태를 지원합니다.

기본 사용법 (Basic Usage)#

// 기본 입력
TextField(
  onChanged: handleNameChange,
  placeholder: Text('이름을 입력하세요'),
)

// 비밀번호 입력 — 표시/숨김은 passwordToggle 기능이 맡는다
TextField(
  obscureText: true,
  features: [CoreInputFeature.passwordToggle()],
  placeholder: Text('비밀번호'),
)

// 라벨 및 에러
TextField(
  label: '이메일',
  onChanged: handleEmailChange,
  errorText: '올바른 이메일을 입력하세요',
)

// 기본 입력
TextField(
  onChanged: handleNameChange,
  placeholder: Text('이름을 입력하세요'),
)

// 비밀번호 입력 — 표시/숨김은 passwordToggle 기능이 맡는다
TextField(
  obscureText: true,
  features: [CoreInputFeature.passwordToggle()],
  placeholder: Text('비밀번호'),
)

// 라벨 + 에러
TextField(
  label: '이메일',
  onChanged: handleEmailChange,
  errorText: '올바른 이메일을 입력하세요',
)

Live Preview#

class TextFieldDefaultExample extends StatefulComponent {
  const TextFieldDefaultExample({super.key});

  @override
  State<TextFieldDefaultExample> createState() =>
      _TextFieldDefaultExampleState();
}

class _TextFieldDefaultExampleState extends State<TextFieldDefaultExample> {
  @override
  Component build(BuildContext context) {
    return TextField(
      placeholder: Text('Enter text...'),
    );
  }
}

class TextFieldDefaultExample extends StatefulWidget {
  const TextFieldDefaultExample({super.key});

  @override
  State<TextFieldDefaultExample> createState() =>
      _TextFieldDefaultExampleState();
}

class _TextFieldDefaultExampleState extends State<TextFieldDefaultExample> {
  @override
  Widget build(BuildContext context) {
    return TextField(
      placeholder: const Text('Enter text...'),
    );
  }
}

구조 (Anatomy)#

코드가 정본입니다. 부분 이름은 위젯 슬롯과 같고, Figma ❖ TextField 레이어와도 맞습니다.

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• 사용자로부터 짧은 텍스트를 입력받을 때 (이름, 이메일, 비밀번호 등)
• 검색 필드가 필요할 때
• 숫자, 전화번호 등 특정 형식의 입력이 필요할 때

대신 다른 컴포넌트를 사용하세요:

• TextArea: 여러 줄의 긴 텍스트를 입력받을 때
• Select: 미리 정해진 옵션 중 선택할 때
• Autocomplete: 입력하면서 추천 목록에서 선택할 때
• DatePicker: 날짜를 입력받을 때

Props / Parameters#

W는 Flutter의 Widget, Web의 Component를 뜻하는 합성 슬롯 타입입니다. 포커스·컨트롤러·포매터의 실제 타입 차이는 아래 런타임 인프라 표와 플랫폼 차이점에 구분합니다.

콘텐츠 / 상태#

xs 는 이르면 coui_core 0.153 부터 sm 으로 그려집니다 — 대신 sm 을 쓰세요. 그 전까지 xs 는 지금처럼 그려지고, assert 가 켜진 실행(디버그 빌드, Jaspr 정적 빌드의 사전 렌더)에서 로그 경고가 한 번 나옵니다 — 경고일 뿐 화면이나 빌드를 멈추지 않습니다. xs 행이 지워진 뒤에는 sm 으로 그려지고, assert 가 켜진 실행은 xs 에서 멈춥니다.

라벨 / 검증#

텍스트 동작#

슬롯 / 어포던스 / 콜백#

Flutter 전용 확장#

Web 은 이 capability 들을 브라우저 native <input> · DOM focus/scroll · 네이티브 컨텍스트 메뉴/확대경으로 제공합니다.

빠른 오버라이드 (Chain)#

이미 만든 TextField 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다. .radius16처럼 Core 토큰 상수 이름과 똑같은 이름의 getter도 있습니다 — withStyle을 한 번 더 줄인 sugar로, 이름이 곧 값이라(radius16 == CoreRadius.radius16) 어느 컴포넌트에서 써도 뜻이 갈리지 않습니다.

class TextFieldChainExample extends StatefulWidget {
  const TextFieldChainExample({super.key});

  @override
  State<TextFieldChainExample> createState() => _TextFieldChainExampleState();
}

class _TextFieldChainExampleState extends State<TextFieldChainExample> {
  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        // 토큰-정확 getter combo — 이름이 곧 값 (getter 이름 = Core 토큰 상수 1:1).
        TextField(placeholder: const Text('Enter text...')).radius16.primary,
        const Gap.space12(),
        // withStyle full-control — getter 가 없는 필드(borderWidth)까지 한 번에.
        TextField(placeholder: const Text('Enter text...')).withStyle(
          const CoreTextFieldStyle(
            borderColor: CoreColor.token(CoreColors.tertiary),
            borderRadius: CoreBorderRadius.all(CoreRadius.radius24),
            borderWidth: CoreStrokeWidth.stroke2,
          ),
        ),
      ],
    );
  }
}

class TextFieldChainExample extends StatefulComponent {
  const TextFieldChainExample({super.key});

  @override
  State<TextFieldChainExample> createState() => _TextFieldChainExampleState();
}

class _TextFieldChainExampleState extends State<TextFieldChainExample> {
  @override
  Component build(BuildContext context) {
    return div(
      [
        // 토큰-정확 getter combo — 이름이 곧 값 (getter 이름 = Core 토큰 상수 1:1).
        TextField(placeholder: Text('Enter text...')).radius16.primary,
        const Gap.space12(),
        // withStyle full-control — getter 가 없는 필드(borderWidth)까지 한 번에.
        TextField(placeholder: Text('Enter text...')).withStyle(
          const CoreTextFieldStyle(
            borderColor: CoreColor.token(CoreColors.tertiary),
            borderRadius: CoreBorderRadius.all(CoreRadius.radius24),
            borderWidth: CoreStrokeWidth.stroke2,
          ),
        ),
      ],
      classes: 'flex flex-col items-start',
    );
  }
}

스타일 시스템 (Style System)#

textFieldStyle 슬롯#

TextField 의 chrome / dimensional / cursor / 슬롯 텍스트 미세 조정은 단일 textFieldStyle 필드(CoreTextFieldStyle) 하나로 흐릅니다.

TextField(
  size: CoreComponentSize.md,                              // ← 크기 토큰 위젯 파라미터
  onChanged: handleEmailChange,
  textFieldStyle: CoreTextFieldStyle(                      // ← chrome / 슬롯 단일 진입점
    borderRadius: CoreBorderRadius.all(CoreRadius.radius8),
    padding: CoreEdgeInsets.symmetric(
      horizontal: CoreSpace.space16,
      vertical: CoreSpace.space12,
    ),
    focusBorderColor: CoreColor.token(CoreColors.primary),
    cursorColor: CoreColor.token(CoreColors.primary),
    valueStyle: CoreTextStyle.token(CoreTextStyles.bodyMedium),
    placeholderStyle: CoreTextStyle.token(
      CoreTextStyles.bodyMedium,
      color: CoreColor.token(CoreColors.onSurfaceVariant),
    ),
    leadingIconStyle: CoreIconStyle(size: CoreSize.size16),
  ),
  prefix: Icon(LucideIcons.mail),
  label: '이메일',
)

CoreTextFieldStyle 필드#

Resolve chain#

variant 는 CoreTextFieldVariant.of(hasError:, enabled:, variant:) 가 정합니다. 우선순위는 disabled > error 입니다 — errorText 가 있고 필드가 활성일 때만 error, 그 밖에는 위젯의 variant(null → defaultVariant). 비활성 필드는 에러가 남아 있어도 비활성으로 먼저 보여야 하므로 테두리·채움 같은 박스 chrome 에 error 행을 쓰지 않습니다. 에러 메시지는 콘텐츠라서 비활성이어도 그대로 표시되고, 그 스타일(errorStyle / errorColor)은 계속 variantStyles[error] 행에서 읽습니다. plain 은 테두리·채움이 없는 무테 필드로, 다른 표면 안에 들어가는 입력(Command 검색 행 등)이 씁니다. 그 키로 variantStyles 가 조회됩니다.

design system default for variant (defaultsByVariant[variant] / defaultsBySize[size])
  → CoreTextFieldTheme.style                       // 프로젝트 공통
  → CoreTextFieldTheme.variantStyles[variant]      // CoreTextFieldVariant.of 가 고른 variant 별
  → 부모 컴포넌트 슬롯 오버라이드
  → widget.textFieldStyle                          // 인스턴스별

nested slot styles 는 재귀 머지 — valueStyle.fontWeight 만 override 해도 valueStyle.fontSize / valueStyle.color 는 이전 레이어 값 유지.

변형 (Variants)#

variant는 errorText 와 enabled 로 자동 결정됩니다:

• errorText가 null이면 → 기본 스타일
• errorText가 설정되고 활성이면 → 에러 스타일 (빨간 보더)
• 비활성이면 → errorText 가 있어도 비활성 스타일이 이깁니다 (에러 메시지는 표시)

테두리는 쉴 때 outline-variant, 마우스를 올리면 outline, 포커스되면 primary 입니다. 굵기는 모든 상태에서 1 이고, 포커스와 에러는 색으로만 말합니다. 바깥 포커스 링은 키보드로 포커스했을 때만 그립니다 — 마우스·터치로 누른 포커스는 primary 테두리가 이미 말합니다. 비활성 필드는 값과 placeholder 를 모두 disabled-content 로 그립니다.

filled 변형은 테두리 대신 채움으로 경계를 말합니다 — 카드·시트처럼 이미 틀이 있는 면 위에 둘 때 씁니다. 바탕 surface-container, hover surface-container-high, 포커스 primary 테두리, 비활성 surface-container-low 입니다.

// 기본 상태
TextField(
  placeholder: Text('이름을 입력하세요'),
)

// 에러 상태 (errorText 설정 시 자동)
TextField(
  errorText: '필수 입력 항목입니다',
  placeholder: Text('이름을 입력하세요'),
)

// 비활성화
TextField(
  enabled: false,
  placeholder: Text('수정 불가'),
)

// 채움 변형 — 카드 · 시트 위에서
TextField(
  variant: CoreTextFieldVariant.filled,
  placeholder: Text('검색'),
)

// 읽기 전용
TextField(
  readOnly: true,
  initialValue: '읽기 전용 값',
)

동작 스펙 (Behavior)#

포커스 관리#

• 클릭 또는 Tab 키로 포커스 획득 시 테두리 색상 변경
• 포커스와 에러의 테두리 굵기는 activeBorderWidth(기본 1 — 쉬는 테두리와 같음)입니다. 더 굵게 적으면 쉬는 테두리(borderWidth, 기본 1)는 레이아웃 안에 그대로 두고 늘어난 폭만 안쪽에 덧그리므로 (Flutter 는 foregroundDecoration, Web 은 차이만큼의 inset 그림자 — 실제 border 도 남아 강제 색 모드에서 경계가 살아 있습니다) 내용과 필드 높이는 움직이지 않습니다. borderWidth 만 더 굵게 쓰면(예: stroke2) 포커스에서 얇아지지 않고 그 폭을 유지합니다. plain 은 모든 상태에서 쉬는 테두리 그대로입니다.
• autofocus: true로 페이지 로드 시 자동 포커스

상태 전환#

• default → focused (포커스 획득) → filled (값 입력) → default (포커스 해제)
• error: errorText 설정 시 error 색 테두리와 에러 메시지 표시
• disabled: 모든 인터랙션 비활성화, 흐리게 표시
• readOnly: 포커스는 가능하나 편집 불가

글자 색 단계#

필드가 그리는 글자는 세 단계입니다. 값이 가장 크게 읽히고, 라벨은 한 단계 아래, 도움말과 붙임(앞·뒤 아이콘과 붙임 글자)은 가장 조용합니다.

활성 라벨이 이미 onSurfaceVariant 이므로 비활성 라벨을 같은 색에 두면 활성과 구분되지 않습니다. 한 단계 더 내려 onSurfaceSubtle 로 두면 읽을 수 있는 글자 단계에 머물면서 꺼진 것으로 읽힙니다 (그래픽 전용 disabledContent 는 쓰지 않습니다). 붙임은 상태가 바뀌어도 색이 같습니다 — 비활성은 값 글자와 테두리가 말합니다. 이 단계는 TextArea 와 같고, FormField 의 비활성 라벨 덮어쓰기도 같은 단계입니다.

FormField / Fieldset 안에서#

TextField 는 감싸는 FormField 나 Fieldset 이 진술한 비활성·에러 상태를 FormFieldScope 로 받아 자기 chrome 에 합칩니다.

에러는 톤만 합쳐집니다 — 메시지는 FormField 가 푸터에 그리고, TextField 는 자기 errorText 가 있을 때만 자기 메시지를 그립니다. 감싸는 쪽이 없으면 동작은 단독 사용과 완전히 같습니다.

TextField 를 합성하는 입력(Select 트리거 · Autocomplete · ChipInput 등)도 그 TextField 를 통해 같은 합성을 받습니다. 스코프는 감싼 서브트리 안에서만 흐르므로, 필드에서 연 팝오버·다이얼로그 안의 TextField 는 받지 않습니다.

FormField 안에서 — 값 보고#

FormField 안에서 TextField 는 자기 텍스트를 감싼 필드에 보고합니다 (Checkbox · Toggle · RadioGroup 과 같은 방식). Form 의 FormController 가 그 값을 formKey 로 모으고 validator 로 검증합니다.

• 검증기가 ReplaceResult 를 돌려주면 텍스트가 그 값으로 바뀌고 onChanged 가 새 텍스트로 한 번 더 불립니다 — 예: 앞뒤 공백 제거. Flutter 는 커서를 새 텍스트 안에 그대로 둡니다.
• FormField 밖의 TextField 는 아무것도 보고하지 않습니다 — 동작은 단독 사용과 완전히 같습니다.
• 다른 컴포넌트가 내부 부품으로 합성한 TextField (PhoneInput 의 번호 입력 · Select 트리거 · ChipInput 의 입력 등)와, 필드에서 연 팝오버·다이얼로그 안의 TextField 는 보고하지 않습니다 — 그 필드의 값은 합성한 컴포넌트의 것이지 부품 텍스트가 아닙니다. 직접 만든 합성 컴포넌트가 TextField 를 부품으로 쓴다면 Flutter 는 Data<FormFieldHandle>.boundary, Web 은 FormFieldHandleScope.boundary 로 감싸세요.

사용 가이드라인 (Usage Guidelines)#

라벨·오류·prefix/suffix·clear/password 어포던스를 포함한 입력에는 TextField를 사용합니다. 여러 줄과 드래그 리사이즈는 TextArea, 분할 필드 입력은 ObjectInput, 국가 코드와 번호를 함께 받으려면 PhoneInput을 선택합니다. 미리 정한 옵션만 허용할 때는 Select를 사용합니다.

편집 없이 선택·복사만 제공하면 SelectableText를 사용합니다.

✅ Do#

TextField(
  label: '이메일 주소',
  placeholder: Text('user@example.com'),
)

❌ Don't#

TextField(
  placeholder: Text('이메일 주소'),
)

✅ Do#

TextField(
  errorText: '이메일 형식이 올바르지 않습니다 (예: user@example.com)',
)

❌ Don't#

TextField(
  errorText: '입력이 올바르지 않습니다',
)

접근성 (Accessibility)#

역할#

• Flutter — 별도 role 플래그를 세우지 않고 EditableText 가 만드는 텍스트 필드 노드를 그대로 씁니다. 그 노드의 가장 안쪽에 Semantics(enabled:, onFocus:) 가 병합되어 활성 상태와 포커스 액션을 진술합니다. 입력 어포던스(비밀번호 토글 · 지우기)만 Semantics(button: true, label:) 로 감싸집니다.
• Web — 편집 표면이 네이티브 <input> 이라 암묵 역할(textbox, type="password" 면 비밀번호 입력)을 그대로 받습니다. <input> 에 붙는 명시적 role / aria-* 는 하나도 없고, 보조기술에 닿는 것은 type · disabled · readonly · required · placeholder · title 같은 네이티브 속성뿐입니다. 어포던스 <button> 에만 aria-label 이 실립니다. 루트 <div> · <label> · 설명/오류 <p> 에는 역할이 없습니다.

키보드#

Escape 는 어느 플랫폼에서도 처리되지 않습니다 — 포커스를 놓거나 값을 되돌리는 핸들러가 양쪽 모두 없습니다.

스크린 리더#

• Flutter: 편집 표면의 시맨틱 노드가 활성 상태(enabled)와 SemanticsAction.focus 핸들러를 진술합니다. 웹 엔진은 접근성이 켜지면 포인터 이벤트가 아니라 이 focus 액션으로 편집 세션을 열므로, 그 경로가 이 배선으로 성립합니다. 도달 범위는 여기까지입니다.
  • 노드가 내놓는 액션은 focus 하나이고 tap 은 없습니다. 따라서 모바일 보조기술의 활성화 제스처가 보내는 SemanticsAction.tap 은 커버되지 않습니다.
  • label:·errorText: 는 시각 표시일 뿐 이 노드에 닿지 않습니다 — 노드의 label 은 빈 문자열입니다.
• Web: <input> 의 네이티브 시맨틱을 그대로 씁니다. 이름은 placeholder(= hintText: 또는 placeholder:)나 title: 에서 오는데, 둘 다 이름 계산의 폴백이라 브라우저·보조기술마다 다르게 취급될 수 있습니다. label: 은 필드에 연결되지 않습니다(→ 알려진 제약).
• 값 변경도 오류 발생도 통보되지 않습니다. errorText: 가 나타나거나 사라지는 것을 알리는 live region 이 양 플랫폼 모두 없습니다.

포커스 관리#

• 진입 — 오버레이가 아니므로 열림에 따른 포커스 이동이 없습니다. autofocus: true 를 주면 최초 빌드에서 필드가 포커스를 가져갑니다(Flutter 는 EditableText.autofocus, Web 은 <input autofocus>). 기본값은 false 입니다.
• 이탈 — 없음. 포커스를 다른 곳으로 되돌리는 코드가 양 플랫폼 모두 없습니다.
• 트랩 — 없음. Tab 이 필드를 그대로 통과합니다. Flutter 는 필드 다음 tab stop 이 입력 어포던스로 이어지지만 Web 은 어포던스가 tab 순서에서 빠집니다(→ 알려진 제약).
• selectAllOnFocus: true(기본 false)를 주면 포커스가 들어오는 순간 값 전체가 선택됩니다 — 양 플랫폼 동일합니다.

알려진 제약#

• Web 은 label: 을 <input> 에 연결하지 않습니다. <label> 요소가 그려지긴 하지만 for 속성이 없고 <input> 을 감싸지도 않아, 라벨 텍스트가 필드의 이름이 되지 않고 라벨을 눌러도 포커스가 옮겨가지 않습니다. description: / errorText: 도 형제 <p> 로 그려질 뿐 aria-describedby 로 참조되지 않고, 오류 상태에 aria-invalid 도 붙지 않습니다. 호출부가 넘긴 attributes 는 루트 <div> 에 실리므로 <input> 에 직접 aria 를 얹을 수도 없습니다 — 이름이 필요하면 title: 로 <input> 의 title 속성을 채우세요 (툴팁으로도 보입니다).
• 입력 어포던스(비밀번호 토글 · 지우기)는 Web 에서 키보드로 닿지 않습니다. Web 은 그 버튼에 tabindex="-1" 을 고정으로 박고, 이를 끄는 것처럼 보이는 skipInputFeatureFocusTraversal 은 Web 에서 => true 로 하드코딩된 getter 라 값을 바꿀 수 없습니다. Flutter 에서는 같은 필드가 생성자에 선언만 되어 있고 build 가 읽지 않아 어포던스가 항상 포커스를 받으므로, 같은 코드가 플랫폼에 따라 다르게 동작합니다. 우회할 방법은 없습니다.

크로스 플랫폼 차이점 (Platform Differences)#

현재 기본값 제약과 우회#

현재 Flutter 생성자는 maxLines 생략 시 CoreTextFieldContract.defaultMaxLines(1)을 사용하지만 Web 생성자는 null을 받습니다. 지원되는 플랫폼별 정책이 아니라 기본값 대칭의 코드 갭입니다. 한 줄 입력 의도를 고정하려면 maxLines: 1을 명시하세요. Web의 native input은 여러 줄 표면이 아니므로 실제 다중 줄 편집은 TextArea로 구성합니다.

관련 컴포넌트 (Related Components)#

• Form: 여러 입력 필드를 묶어 유효성 검증 수행
• Select: 미리 정해진 옵션 중 선택
• TextArea: 여러 줄 텍스트 입력