TextArea#

여러 줄의 텍스트를 입력받는 텍스트 영역 컴포넌트입니다. Flutter/Web 양쪽에서 동일한 API(TextArea)를 제공합니다.

Live Preview#

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

  @override
  State<TextAreaDefaultExample> createState() =>
      _TextAreaDefaultExampleState();
}

class _TextAreaDefaultExampleState extends State<TextAreaDefaultExample> {
  @override
  Component build(BuildContext context) {
    return TextArea(
      placeholder: 'Enter your message...',
      rows: 4,
    );
  }
}

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

  @override
  State<TextAreaDefaultExample> createState() =>
      _TextAreaDefaultExampleState();
}

class _TextAreaDefaultExampleState extends State<TextAreaDefaultExample> {
  @override
  Widget build(BuildContext context) {
    return TextArea(
      placeholder: 'Enter your message...',
      rows: 4,
    );
  }
}

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

  @override
  State<TextAreaChainExample> createState() => _TextAreaChainExampleState();
}

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

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

  @override
  State<TextAreaChainExample> createState() => _TextAreaChainExampleState();
}

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

사용 시기 (When to Use)#

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

• 댓글, 메모, 설명 등 여러 줄 텍스트 입력이 필요할 때
• 사용자 피드백이나 문의 내용을 받을 때
• 긴 텍스트 편집이 필요할 때

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

• TextField: 한 줄 텍스트 입력
• Form: 여러 필드 묶어 검증
• Select: 미리 정의된 옵션 선택

기본 사용법 (Basic Usage)#

// 기본 텍스트 영역
TextArea(
  placeholder: 'Enter your message...',
  rows: 4,
  onChanged: (value) => print(value),
)

// 라벨 + 설명 + 에러
TextArea(
  label: 'Message',
  description: 'Type your feedback here',
  errorText: hasError ? 'This field is required' : null,
  placeholder: 'Enter your message...',
  onChanged: handleChange,
)

// 크기 조절 가능 (드래그 핸들) — 초기 높이는 chrome 이므로 Style 슬롯으로
TextArea(
  expandableHeight: true,
  expandableWidth: true,
  placeholder: 'Drag to resize...',
  onChanged: handleChange,
  textAreaStyle: const CoreTextAreaStyle(initialHeight: 150),
)

// 기본 텍스트 영역
TextArea(
  placeholder: 'Enter your message...',
  rows: 4,
  onChanged: (value) => print(value),
)

// 라벨 + 설명 + 에러
TextArea(
  label: 'Message',
  description: 'Type your feedback here',
  errorText: hasError ? 'This field is required' : null,
  placeholder: 'Enter your message...',
  onChanged: handleChange,
)

// rows + maxLength 제어
TextArea(
  rows: 6,
  maxLength: 500,
  placeholder: 'Max 500 chars',
  onChanged: handleChange,
)

Props / Parameters#

TextArea은 Flutter/Web에서 동일한 파라미터 이름을 사용합니다.

textAlign / textAlignVertical 은 위젯 파라미터가 아니라 CoreTextAreaStyle 필드입니다 (defaultTextAlign = start, defaultTextAlignVertical = top). initialHeight / minHeight / maxHeight / padding / borderRadius / cursor 색·두께·반경도 같은 슬롯 안에 있습니다.

입력 동작 / 폼 (양 플랫폼)#

마스킹된 영역은 양 플랫폼 모두 브라우저/OS 텍스트 서비스에서 빠진다 — Web 은 spellcheck="false" · autocorrect="off" · autocapitalize="none" 를 함께 emit 하고, textCapitalization 을 명시해도 마스킹이 이긴다.

Flutter 전용 확장#

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

Web 전용 확장#

scrollPadding 은 위젯 파라미터입니다 (기본값 CoreTextAreaContract.defaultScrollPadding) — 스크롤-인투-뷰 inset 은 아무것도 그리지 않으므로 chrome 이 아니라 behaviour 이고, 그래서 CoreTextAreaStyle 이 아니라 위젯 평면에 있습니다.

스타일 시스템 — textAreaStyle#

TextArea 의 모든 chrome / dimensional / cursor / nested-slot 오버라이드는 CoreTextAreaStyle 단일 슬롯으로 흐릅니다. multi-line 전용 동작 (rows / expandableHeight / expandableWidth) 과 크기 토큰 (size) 은 위젯 파라미터입니다.

TextArea(
  size: CoreComponentSize.md,                              // ← 크기 토큰 위젯 파라미터
  rows: 4,                                                 // ← multi-line 동작
  expandableHeight: true,                                  // ← multi-line 동작
  onChanged: handleBio,
  textAreaStyle: CoreTextAreaStyle(                        // ← chrome / 슬롯 단일 진입점
    borderRadius: CoreBorderRadius.all(CoreRadius.radius8),
    padding: CoreEdgeInsets.symmetric(
      horizontal: CoreSpace.space16,
      vertical: CoreSpace.space12,
    ),
    minHeight: 96,
    maxHeight: 240,
    focusBorderColor: CoreColor.token(CoreColors.primary),
    valueStyle: CoreTextStyle.token(CoreTextStyles.bodyMedium),
  ),
)

minHeight / maxHeight 는 TextArea 의 auto-grow 제약에 특히 의미가 있습니다.

Resolve chain#

variantStyles 는 위젯의 에러 상태(errorText != null) 를 키로 갖는 Map<bool, CoreTextAreaStyle> 입니다 — 별도 variant enum 은 없습니다.

design system default (defaultNormalVariant / defaultsByVariant[hasError])
  → CoreTextAreaTheme.style
  → CoreTextAreaTheme.variantStyles[hasError]
  → 부모 컴포넌트 슬롯 오버라이드
  → widget.textAreaStyle

CoreTextAreaStyle 필드#

빠른 오버라이드 (Chain)#

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

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

  @override
  State<TextAreaChainExample> createState() => _TextAreaChainExampleState();
}

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

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

  @override
  State<TextAreaChainExample> createState() => _TextAreaChainExampleState();
}

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

테마 커스터마이징 (Theme)#

CoreTextAreaTheme 은 style + variantStyles 두 슬롯만 가집니다. variantStyles 의 키는 에러 상태 bool 입니다 (true → errorText != null).

CoreComponentTheme(
  textArea: CoreTextAreaTheme(
    style: CoreTextAreaStyle(
      borderRadius: CoreBorderRadius.all(CoreRadius.radius8),
      padding: CoreEdgeInsets.symmetric(
        horizontal: CoreSpace.space16,
        vertical: CoreSpace.space12,
      ),
    ),
    variantStyles: {
      true: CoreTextAreaStyle(
        focusBorderColor: CoreColor.token(CoreColors.error),
      ),
    },
  ),
)

autocorrect / enableSuggestions 같은 입력 정책 기본값은 Theme 이 아니라 CoreTextAreaContract.defaultXxx 단일 출처에서 옵니다.

Resolve 우선순위: widget.textAreaStyle > CoreTextAreaTheme.variantStyles[hasError]

CoreTextAreaTheme.style > 디자인 시스템 기본값.

동작 스펙 (Behavior)#

인터랙션#

• 타이핑: 입력 시 onChanged 호출
• 포커스 이탈/Enter: onSubmitted 호출 (Web은 change 이벤트)
• 크기 조절:
  • Flutter: expandableHeight/expandableWidth로 드래그 핸들 표시
  • Web: 네이티브 <textarea> 리사이즈 핸들(resize: vertical) 제공
  • 양쪽 모두 드래그 가능한 축에서만 onHeightChanged / onWidthChanged 호출 (Web 은 ResizeObserver, 마운트 첫 보고는 크기 변경이 아니므로 건너뜀)

유효성#

• maxLength: 초과 입력 차단
• errorText 존재 시 description 숨김, 에러 chrome(variantStyles[true])으로 자동 전환
• required: true → 라벨 옆 * 표시

시각적 토큰 통일#

• 정상 상태(defaultNormalVariant): surface 배경 + outlineVariant 보더 + primary 포커스 링
• 에러 상태(defaultErrorVariant): surface 배경 + error 보더 + error 포커스 링
• Flutter/Web 모두 CoreTextAreaVariantStyle을 참조하여 토큰 일관성 유지

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

✅ Do#

TextArea(
  expandableHeight: true,
  onChanged: handleChange,
  textAreaStyle: const CoreTextAreaStyle(
    initialHeight: 96,
    minHeight: 96,
    maxHeight: 320,
  ),
)

❌ Don't#

// ❌ errorText 가 생기는 순간 description 이 사라져 안내를 잃음
TextArea(
  description: '최소 10자 이상 입력하세요',
  errorText: hasError ? '필수 입력입니다' : null,
)

접근성 (Accessibility)#

• Web: <textarea> 네이티브 시맨틱을 그대로 사용합니다.
• Flutter: 편집 표면의 시맨틱 노드가 활성 상태(enabled)와 SemanticsAction.focus 핸들러를 진술합니다. 웹 엔진은 접근성이 켜지면 포인터 이벤트가 아니라 이 focus 액션으로 편집 세션을 열므로, 그 경로가 이 배선으로 성립합니다.
  • 이 컴포넌트의 노드는 focus 외에 tap 액션도 함께 내놓습니다. 그것은 이 배선이 아니라 영역을 감싸는 탭 제스처에서 오며, 그 핸들러가 포커스를 요청합니다 — TextField 쪽 노드에는 tap 이 없습니다.
  • label:·errorText: 는 시각 표시일 뿐 이 노드에 닿지 않습니다(노드의 label 은 빈 문자열).

관련 컴포넌트 (Related Components)#

• Input / TextField: 한 줄 텍스트 입력
• Form: 여러 필드 묶음
• Fieldset: 관련 필드 그룹화