Label

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

기본 사용법 (Basic Usage)#

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

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

// 아이콘 함께
const Label(
  text: 'Email',
  icon: Icon(LucideIcons.mail),
)

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

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

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

// 아이콘 함께
const Label(
  text: 'Email',
  icon: Icon(LucideIcons.mail),
)

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

빠른 오버라이드 (Chain)#

이미 만든 Label 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다.

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

  @override
  Widget build(BuildContext context) {
    return const Label(text: 'Email', isRequired: true).withStyle(
      const CoreLabelStyle(
        textStyle: CoreTextStyle.token(
          CoreTextStyles.titleMedium,
          color: CoreColor.token(CoreColors.primary),
        ),
        requiredColor: CoreColor.token(CoreColors.tertiary),
        labelRequiredGapStyle: CoreGapStyle(size: CoreSpace.space12),
        disabledOpacity: CoreOpacity.opacity50,
      ),
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    return const Label(text: 'Email', isRequired: true).withStyle(
      const CoreLabelStyle(
        textStyle: CoreTextStyle.token(
          CoreTextStyles.titleMedium,
          color: CoreColor.token(CoreColors.primary),
        ),
        requiredColor: CoreColor.token(CoreColors.tertiary),
        labelRequiredGapStyle: CoreGapStyle(size: CoreSpace.space12),
        disabledOpacity: CoreOpacity.opacity50,
      ),
    );
  }
}

Live Preview#

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

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

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

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

사용 시기 (When to Use)#

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

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

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

• Text: 폼과 무관한 일반 텍스트 표시
• FormField: 입력과 라벨·설명·오류·검증 컨텍스트를 함께 구성해야 할 때. 라벨 클릭으로 입력을 포커스하는 동작을 자동 보장하는 래퍼는 아닙니다
• Fieldset: 여러 라벨·입력에 공통 legend·비활성 스코프가 필요할 때
• ValidationBadge: 필드 이름 대신 valid/invalid 상태를 표시할 때

Props / Parameters#

W 는 Flutter의 Widget, Web의 Jaspr Component 입니다. W? 는 선택 슬롯입니다.

스타일 시스템 (Style System)#

모든 chrome / dimensional / 텍스트 override 는 labelStyle 슬롯 하나로 흐릅니다.

CoreLabelStyle 필드#

Resolve chain#

design system default (CoreLabelStyle.defaultX)
  → CoreLabelTheme.style                          // 프로젝트 공통
  → parent component slot override
  → widget.labelStyle                             // 인스턴스별

동작 스펙 (Behavior)#

인터랙션#

• 표시 전용 컴포넌트 — 클릭/호버 인터랙션 없음
• disabled 일 때 전용 disabledContent 색 (CoreLabelStyle.defaultDisabledTextStyle) 이 적용되고, 커서는 forbidden 으로 바뀝니다
• 글자 · 필수 표시(*) · 아이콘은 이 비활성 글자 스타일(disabledTextStyle)의 색 하나를 따릅니다. 그래서 disabledTextStyle 의 색을 바꾸면 셋이 함께 바뀌고, requiredColor 는 활성 상태에서만 쓰입니다 — 비활성 필드에 붉은 * 가 남아 "지금 입력해야 한다"는 잘못된 신호를 주지 않습니다
• disabledOpacity 기본값은 1 — 비활성 라벨은 이미 전용 색을 들고 있어서 투명도를 더 곱하면 대비가 놓인 배경에 따라 달라지기 때문입니다. 필요하면 labelStyle 로 낮출 수 있습니다

레이아웃#

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

토큰#

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

✅ Do#

Label(text: 'Email', disabled: !emailField.enabled)

❌ Don't#

// ❌ Label 은 컨트롤과 연결되지 않는다 — htmlFor 를 줘도 마찬가지
Column(
  children: [
    const Label(text: 'Email'),
    TextField(id: 'email-input'),
  ],
)

// ✅ FormField 가 라벨-컨트롤 연결을 실제로 만든다
FormField(
  label: 'Email',
  child: TextField(),
)

접근성 (Accessibility)#

역할#

• Flutter — role 없음. semanticLabel 을 주면 Semantics(label:) 로, htmlFor 를 주면 Semantics(identifier:) 로 한 겹씩 감싸지지만 어느 쪽도 role 을 세우지 않습니다.
• Web — 루트 태그가 <span> 으로 고정이고 role 을 붙이지 않습니다. htmlFor 는 그 <span> 의 for 속성으로, semanticLabel 은 aria-label 로 실립니다. 내부의 아이콘 래퍼와 필수 표시(*) <span> 에도 역할이 없습니다.

키보드#

없음. 라벨은 어느 플랫폼에서도 포커스를 받지 않습니다 — Flutter 구현에 Focus / FocusNode 가 없고 Web <span> 에 tabindex 가 붙지 않아 tab stop 이 아니며, 키 핸들러도 양쪽 모두 없습니다. 라벨을 눌러 연결된 컨트롤로 넘어가는 동작도 없습니다(→ 알려진 제약).

스크린 리더#

• 접근 가능한 이름의 출처는 표시 텍스트(text)입니다. semanticLabel 을 주면 그 값이 대신 읽힙니다 — Flutter 는 Semantics(label:), Web 은 aria-label 로 나가며 Web 쪽 도달성에는 제약이 있습니다(→ 알려진 제약).
• isRequired: true 는 * 글리프 하나로만 표현됩니다. aria-required 같은 상태나 "필수" 라는 텍스트로는 나가지 않으므로, 필수임을 확실히 알려야 하면 semanticLabel: 'Email (필수)' 처럼 이름에 직접 담으세요.
• 상태 통보 없음 — 라벨은 정적 텍스트이고 live region 이 아닙니다.

포커스 관리#

해당 없음. 오버레이가 아니고 포커스를 받지도 않으므로 진입·이탈·트랩 모두 대상이 아닙니다. Tab 은 라벨을 건너뜁니다.

알려진 제약#

• htmlFor 는 어느 플랫폼에서도 라벨과 컨트롤을 실제로 잇지 않습니다. Web 의 루트는 tag: 'span' 으로 고정인데 for 는 <label> / <output> 에서만 의미를 갖는 속성이라 <span for="..."> 는 아무 관계도 만들지 않고, Flutter 는 그 값을 Semantics(identifier:) 메타로만 실을 뿐입니다. 두 구현 모두 탭/클릭 핸들러가 없어 라벨을 눌러도 컨트롤이 포커스를 받지 않습니다. 루트 태그는 호출부가 바꿀 수 없으므로 우회할 방법도 없습니다. htmlFor 는 deprecated 이며, 실제 라벨-컨트롤 연결이 필요하면 FormField 를 쓰세요.
• Web 의 semanticLabel 은 role 이 없는 <span> 에 aria-label 로 실립니다. ARIA 는 제네릭 요소에 이름을 붙이는 것을 금지하므로 브라우저가 이 값을 접근성 트리에 노출하지 않을 수 있습니다. Flutter 는 Semantics(label:) 로 감싸 값을 그대로 전달하므로 같은 코드가 두 플랫폼에서 다르게 읽힙니다.
• disabled: true 는 상태로 통보되지 않고 시각으로만 전달됩니다. Web 은 cursor-not-allowed 와 텍스트 색을 바꾸고 disabledOpacity 를 인라인 opacity 로 내보내며, Flutter 도 SystemMouseCursors.forbidden 과 Opacity 를 씌웁니다. 하지만 어느 쪽도 aria-disabled 나 Semantics(enabled: false) 를 세우지 않아 스크린 리더에는 활성 라벨과 구별되지 않습니다. 게다가 disabledOpacity 의 기본값이 CoreOpacity.opacity100(= 1) 이라 기본 경로에서는 알파 감쇠가 일어나지 않고, 남는 시각 차이는 색 토큰(onSurface ↔ disabledContent)과 커서뿐입니다 — 색 강제 모드에서는 두 색이 같은 시스템 색으로 접히고 커서는 마우스 사용자에게만 보입니다. 감쇠가 필요하면 CoreLabelStyle(disabledOpacity: …) 로 직접 낮추세요.

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

관련 컴포넌트 (Related Components)#

• Form: 폼 필드 그룹화 + 검증
• FormField: 라벨-컨트롤을 실제로 연결하는 폼 필드 래퍼
• Fieldset: 여러 라벨/입력의 그룹 컨테이너
• ValidationBadge: 라벨 옆 valid/invalid 인디케이터