TextField#

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

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...'),
    );
  }
}

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

  @override
  State<TextFieldErrorExample> createState() => _TextFieldErrorExampleState();
}

class _TextFieldErrorExampleState extends State<TextFieldErrorExample> {
  @override
  Component build(BuildContext context) {
    return TextField(
      placeholder: Text('Enter text...'),
      errorText: 'This field is required.',
    );
  }
}

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

  @override
  State<TextFieldErrorExample> createState() => _TextFieldErrorExampleState();
}

class _TextFieldErrorExampleState extends State<TextFieldErrorExample> {
  @override
  Widget build(BuildContext context) {
    return TextField(
      placeholder: const Text('Enter text...'),
      errorText: 'This field is required.',
    );
  }
}

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',
    );
  }
}

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,
          ),
        ),
      ],
    );
  }
}

사용 시기 (When to Use)#

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

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

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

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

기본 사용법 (Basic Usage)#

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

// 비밀번호 입력
TextField(
  obscureText: true,
  placeholder: Text('비밀번호'),
)

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

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

// 비밀번호 입력
TextField(
  obscureText: true,
  placeholder: Text('비밀번호'),
)

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

Props / Parameters#

콘텐츠 / 상태#

라벨 / 검증#

텍스트 동작#

슬롯 / 어포던스 / 콜백#

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',
    );
  }
}

스타일 시스템 — 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 는 위젯 파라미터가 아닙니다 — errorText 유무로 CoreTextFieldVariant 가 결정되고(defaultVariant / error), 그 키로 variantStyles 가 조회됩니다.

design system default for variant (defaultsByVariant[variant] / defaultsBySize[size])
  → CoreTextFieldTheme.style                       // 프로젝트 공통
  → CoreTextFieldTheme.variantStyles[variant]      // 에러 상태에서 파생된 variant 별
  → 부모 컴포넌트 슬롯 오버라이드
  → widget.textFieldStyle                          // 인스턴스별

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

변형 (Variants)#

variant는 errorText 파라미터로 자동 결정됩니다:

• errorText가 null이면 → 기본 스타일
• errorText가 설정되면 → 에러 스타일 (빨간 보더)

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

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

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

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

동작 스펙 (Behavior)#

포커스 관리#

• 클릭 또는 Tab 키로 포커스 획득 시 테두리 색상 변경
• autofocus: true로 페이지 로드 시 자동 포커스

상태 전환#

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

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

✅ 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: 편집 표면의 시맨틱 노드가 활성 상태(enabled)와 SemanticsAction.focus 핸들러를 진술합니다. 웹 엔진은 접근성이 켜지면 포인터 이벤트가 아니라 이 focus 액션으로 편집 세션을 열므로, 그 경로가 이 배선으로 성립합니다. 도달 범위는 여기까지입니다.
  • 노드가 내놓는 액션은 focus 하나이고 tap 은 없습니다. 따라서 모바일 보조기술의 활성화 제스처가 보내는 SemanticsAction.tap 은 커버되지 않습니다.
  • label:·errorText: 는 시각 표시일 뿐 이 노드에 닿지 않습니다 — 노드의 label 은 빈 문자열입니다.
• Web: <input> 요소의 네이티브 접근성. label 속성으로 접근성 라벨 자동 연결

터치 타겟#

• 최소 터치 타겟 높이는 24 (CoreTouchTarget.minimum) 이며, 실제 필드는 그보다 크게 그립니다.
• 충분한 내부 패딩으로 터치 영역 확보

관련 컴포넌트 (Related Components)#

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