Indicator#

Indicator 는 child 위젯/컴포넌트를 감싸고 그 모서리·가장자리에 item 을 띄우는 wrapper 입니다. 아바타 우상단의 온라인 점, 아이콘 우상단의 카운트 배지, 카드 좌상단의 "NEW" 라벨 같은 패턴에 적합합니다.

Live Preview#

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

  @override
  Component build(BuildContext context) {
    return Indicator(
      item: Status(
        color: CoreStatusColor.success,
        size: CoreStatusSize.lg,
      ),
      child: Avatar(initials: 'DW'),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return const Indicator(
      item: Status(
        color: CoreStatusColor.success,
        size: CoreStatusSize.lg,
      ),
      child: Avatar(initials: 'DW'),
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    return Indicator(
      horizontalPosition: CoreIndicatorHorizontalPosition.start,
      verticalPosition: CoreIndicatorVerticalPosition.bottom,
      item: Status(
        color: CoreStatusColor.warning,
        size: CoreStatusSize.lg,
      ),
      child: Avatar(initials: 'DW'),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return const Indicator(
      horizontalPosition: CoreIndicatorHorizontalPosition.start,
      verticalPosition: CoreIndicatorVerticalPosition.bottom,
      item: Status(
        color: CoreStatusColor.warning,
        size: CoreStatusSize.lg,
      ),
      child: Avatar(initials: 'DW'),
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    return Indicator(
      item: Status(
        color: CoreStatusColor.success,
        size: CoreStatusSize.lg,
      ),
      child: Avatar(initials: 'DW'),
    ).withStyle(
      const CoreIndicatorStyle(offset: CoreSpace.space8),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Indicator(
      item: const Status(
        color: CoreStatusColor.success,
        size: CoreStatusSize.lg,
      ),
      child: const Avatar(initials: 'DW'),
    ).withStyle(
      const CoreIndicatorStyle(offset: CoreSpace.space8),
    );
  }
}

사용 시기 (When to Use)#

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

• 아바타에 온라인 상태 점 (status dot) 을 표시할 때
• 아이콘 위에 알림 카운트 배지를 띄울 때
• 카드/이미지 위에 "NEW" / "HOT" 라벨을 오버레이할 때

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

• Badge: 인라인 배지가 필요할 때 (다른 요소를 감싸지 않음)
• DotIndicator: 캐러셀 위치 표시 점들이 필요할 때

기본 사용법 (Basic Usage)#

// 기본 — 우상단 (end + top)
Indicator(
  item: Badge(child: Text('99+')),
  child: Avatar(initials: 'DW'),
)

// 좌하단 (start + bottom) + offset 4 (Flutter 4 logical px)
Indicator(
  horizontalPosition: CoreIndicatorHorizontalPosition.start,
  verticalPosition: CoreIndicatorVerticalPosition.bottom,
  indicatorStyle: CoreIndicatorStyle(offset: 4),
  item: Status(),
  child: Icon(LucideIcons.bell),
)

// 기본 — 우상단
Indicator(
  item: Badge(child: Text('99+')),
  child: Avatar(initials: 'DW'),
)

// 좌하단 + offset 4 (Web inline `0.25rem`)
Indicator(
  horizontalPosition: CoreIndicatorHorizontalPosition.start,
  verticalPosition: CoreIndicatorVerticalPosition.bottom,
  indicatorStyle: CoreIndicatorStyle(offset: 4),
  item: Status(),
  child: Icon(LucideIcons.bell),
)

Props / Parameters#

빠른 오버라이드 (Chain)#

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

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

  @override
  Widget build(BuildContext context) {
    return Indicator(
      item: const Status(
        color: CoreStatusColor.success,
        size: CoreStatusSize.lg,
      ),
      child: const Avatar(initials: 'DW'),
    ).withStyle(
      const CoreIndicatorStyle(offset: CoreSpace.space8),
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    return Indicator(
      item: Status(
        color: CoreStatusColor.success,
        size: CoreStatusSize.lg,
      ),
      child: Avatar(initials: 'DW'),
    ).withStyle(
      const CoreIndicatorStyle(offset: CoreSpace.space8),
    );
  }
}

스타일 시스템 (Style System)#

CoreIndicatorStyle 필드#

변형 (Variants)#

Default#

우상단 (end + top) 에 item 을 배치 — 가장 흔한 알림 배지 패턴.

Indicator(
  item: Badge(child: Text('99+')),
  child: Avatar(initials: 'DW'),
)

Bottom Start#

좌하단 (start + bottom) — "NEW" 라벨 같은 라벨 배지에 적합.

Indicator(
  horizontalPosition: CoreIndicatorHorizontalPosition.start,
  verticalPosition: CoreIndicatorVerticalPosition.bottom,
  item: Badge(child: Text('NEW')),
  child: Avatar(initials: 'DW'),
)

위치 조합 (Position Matrix)#

center / middle 일 땐 transform: translate(-50%, -50%) (Web) 또는 Align(alignment: Alignment(h, v)) (Flutter) 으로 anchor 를 자식의 중심에 맞춥니다.

동작 스펙 (Behavior)#

• 표시 전용 wrapper. 인터랙션 없음.
• Flutter: Stacks(clipBehavior: .none) + Position. item 이 child 의 bounding box 를 넘어가도 잘리지 않음.
• Web: position: relative; overflow: visible 컨테이너 + position: absolute overlay div. 동일 시맨틱.
• indicatorStyle.offset 은 양수일수록 item 이 child 안쪽으로 들어옴 — Flutter 는 Position 의 top / right / bottom / left 에 logical pixel 로, Web 은 같은 네 속성의 inline CSS 에 offset / 16 을 rem 으로 넣습니다 (offset: 4 → 0.25rem). 미지정 시 CoreIndicatorTheme.style?.offset → CoreIndicatorStyle.defaultOffset (0) 순으로 폴백.

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

✅ Do#

Indicator(
  item: Badge(child: Text('3 unread')),
  child: Icon(LucideIcons.bell),
)

❌ Don't#

// ❌ Indicator 는 하나의 child 에 하나의 item 을 배치하는 wrapper
Row(
  children: List.generate(
    5,
    (i) => Indicator(item: const Status(), child: const SizedBox()),
  ),
)

접근성 (Accessibility)#

• Indicator 자체는 시맨틱 의미가 없음. item 자체가 의미를 가져야 함 (예: Badge(child: Text('3 unread'))).

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

관련 컴포넌트 (Related Components)#

• Badge: Indicator.item 으로 가장 흔히 쓰이는 컴포넌트.
• Avatar: Indicator.child 로 가장 흔히 쓰이는 컴포넌트.
• DotIndicator: 캐러셀 위치 점들.