Label#

폼 필드 위 또는 옆에 표시하는 정적 텍스트 라벨 컴포넌트입니다. 선택적으로 leading 아이콘과 필수 필드 표시(*)를 지원하며, 비활성 상태(disabled)도 양쪽 플랫폼 동일하게 적용됩니다.

Live Preview#

class LabelDefaultExample extends StatelessComponent {
  const LabelDefaultExample({super.key});

  @override
  Component build(BuildContext context) {
    return const CoLabel(text: 'Email');
  }
}

class LabelDefaultExample extends StatelessWidget {
  const LabelDefaultExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const CoLabel(text: 'Email');
  }
}

class LabelRequiredExample extends StatelessComponent {
  const LabelRequiredExample({super.key});

  @override
  Component build(BuildContext context) {
    return const CoLabel(text: 'Email', isRequired: true);
  }
}

class LabelRequiredExample extends StatelessWidget {
  const LabelRequiredExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const CoLabel(text: 'Email', isRequired: true);
  }
}

class LabelWithIconExample extends StatelessComponent {
  const LabelWithIconExample({super.key});

  @override
  Component build(BuildContext context) {
    return const CoLabel(
      text: 'Email',
      icon: CoIcon(CoLucideIcons.mail),
    );
  }
}

class LabelWithIconExample extends StatelessWidget {
  const LabelWithIconExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const CoLabel(
      text: 'Email',
      icon: CoIcon(CoLucideIcons.mail),
    );
  }
}

class LabelDisabledExample extends StatelessComponent {
  const LabelDisabledExample({super.key});

  @override
  Component build(BuildContext context) {
    return const CoLabel(text: 'Email', disabled: true);
  }
}

class LabelDisabledExample extends StatelessWidget {
  const LabelDisabledExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const CoLabel(text: 'Email', disabled: true);
  }
}

사용 시기 (When to Use)#

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

• Input / Textarea / Checkbox 등 폼 컨트롤 옆에 라벨 텍스트가 필요할 때
• 필수 필드(*)를 시각적으로 표시할 때
• 라벨에 leading 아이콘(메일, 사용자 아이콘 등)을 함께 표시할 때
• 폼 필드의 상태(disabled)를 라벨에서도 함께 반영할 때

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

• Text: 폼과 무관한 일반 텍스트 표시
• Fieldset: 여러 라벨/입력을 묶는 그룹 컨테이너
• ValidationBadge: 라벨 옆 valid/invalid 인디케이터

기본 사용법 (Basic Usage)#

// 단순 라벨
const CoLabel(text: 'Email')

// 필수 필드
const CoLabel(text: 'Email', isRequired: true)

// 아이콘 함께
const CoLabel(
  text: 'Email',
  icon: CoIcon(CoLucideIcons.mail),
)

// 비활성 상태
const CoLabel(text: 'Email', disabled: true)

// 폼 컨트롤과 연결 (a11y identifier)
const CoLabel(text: 'Email', htmlFor: 'email-input')

// 단순 라벨
const CoLabel(text: 'Email')

// 필수 필드
const CoLabel(text: 'Email', isRequired: true)

// 아이콘 함께
const CoLabel(
  text: 'Email',
  icon: CoIcon(CoLucideIcons.mail),
)

// 비활성 상태
const CoLabel(text: 'Email', disabled: true)

// 폼 컨트롤과 연결 (HTML `for` attribute)
const CoLabel(text: 'Email', htmlFor: 'email-input')

Props / Parameters#

동작 스펙 (Behavior)#

인터랙션#

• 표시 전용 컴포넌트 — 클릭/호버 인터랙션 없음
• disabled 일 때 muted 색 + 투명도 70% 적용 (CoreLabelTokens.disabledOpacity)

레이아웃#

• 루트는 inline-flex row — leading 아이콘 → 텍스트 → 필수(*) 순서
• 아이콘 크기: CoreLabelTokens.iconSize (16px)
• 아이콘-텍스트 간격: CoreSpace.space6
• 텍스트-필수(*) 간격: CoreSpace.space4

토큰#

접근성 (Accessibility)#

• htmlFor 로 연결된 폼 컨트롤이 있으면 라벨 클릭/탭으로 컨트롤이 포커스를 받아야 한다 (Web <for>, Flutter Semantics.identifier 메타).
• semanticLabel 을 통해 스크린 리더용 텍스트를 별도 지정 가능 — 시각적 라벨과 다른 의미를 전달해야 할 때 사용.
• 필수(*) 만으로 의미 전달이 부족하면 semanticLabel: 'Email (필수)' 같이 명시.

관련 컴포넌트 (Related Components)#

• Form: 폼 필드 그룹화 + 검증
• Fieldset: 여러 라벨/입력의 그룹 컨테이너
• ValidationBadge: 라벨 옆 valid/invalid 인디케이터