Toast#

사용자에게 간단한 피드백 메시지를 일시적으로 표시하는 토스트 컴포넌트입니다.

Live Preview#

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

  @override
  Component build(BuildContext context) {
    return Toast(
      message: 'Success',
      description: 'Your changes have been saved.',
      onDismiss: () {},
    );
  }
}

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

  @override
  State<ToastDefaultExample> createState() => _ToastDefaultExampleState();
}

class _ToastDefaultExampleState extends State<ToastDefaultExample> {
  @override
  Widget build(BuildContext context) {
    return Toast(
      message: 'Success',
      description: 'Your changes have been saved.',
      onDismiss: () {},
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    return Toast(
      message: 'Error',
      description: 'Something went wrong.',
      variant: CoreToastVariant.destructive,
      onDismiss: () {},
    );
  }
}

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

  @override
  State<ToastDestructiveExample> createState() =>
      _ToastDestructiveExampleState();
}

class _ToastDestructiveExampleState extends State<ToastDestructiveExample> {
  @override
  Widget build(BuildContext context) {
    return Toast(
      message: 'Error',
      description: 'Something went wrong.',
      variant: CoreToastVariant.destructive,
      onDismiss: () {},
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    return Toast(
      message: 'Success',
      description: 'Your changes have been saved.',
      onDismiss: () {},
    ).withStyle(
      const CoreToastStyle(
        panelBorderRadius: CoreBorderRadius.all(CoreRadius.radius4),
        panelBorderColor: CoreColor.token(CoreColors.primary),
        panelBorderWidth: CoreStrokeWidth.stroke2,
        panelPaddingWithDismiss: CoreEdgeInsets.directional(
          start: CoreSpace.space16,
          top: CoreSpace.space16,
          end: CoreSpace.space32,
          bottom: CoreSpace.space16,
        ),
        messageDescriptionGapStyle: CoreGapStyle(size: CoreSpace.space8),
      ),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Toast(
      message: 'Success',
      description: 'Your changes have been saved.',
      onDismiss: () {},
    ).withStyle(
      const CoreToastStyle(
        panelBorderRadius: CoreBorderRadius.all(CoreRadius.radius4),
        panelBorderColor: CoreColor.token(CoreColors.primary),
        panelBorderWidth: CoreStrokeWidth.stroke2,
        panelPaddingWithDismiss: CoreEdgeInsets.directional(
          start: CoreSpace.space16,
          top: CoreSpace.space16,
          end: CoreSpace.space32,
          bottom: CoreSpace.space16,
        ),
        messageDescriptionGapStyle: CoreGapStyle(size: CoreSpace.space8),
      ),
    );
  }
}

사용 시기 (When to Use)#

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

• 작업 결과(성공/실패)를 간단히 알릴 때
• 되돌리기(undo) 액션을 제공할 때
• 사용자 흐름을 방해하지 않는 비침입적 알림이 필요할 때

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

• Dialog: 사용자 확인이 반드시 필요한 중요한 알림일 때
• Alert / Banner: 페이지에 고정된 영구적 알림이 필요할 때
• Tooltip: 특정 요소에 대한 설명이 필요할 때

기본 사용법 (Basic Usage)#

// 기본 토스트 카드
Toast(
  message: '저장되었습니다.',
  description: '변경사항이 성공적으로 저장되었습니다.',
  onDismiss: () {},
)

// destructive 변형
Toast(
  message: '오류가 발생했습니다.',
  description: '네트워크 연결을 확인해 주세요.',
  variant: CoreToastVariant.destructive,
  onDismiss: () {},
)

// showToast와 함께 사용
showToast(
  context: context,
  builder: (context, overlay) => Toast(
    message: '파일이 업로드되었습니다.',
    onDismiss: overlay.close,
  ),
)

// 기본 토스트 (default 변형)
Toast(
  message: '저장되었습니다.',
  description: '변경사항이 성공적으로 저장되었습니다.',
  onDismiss: handleDismiss,
)

// destructive 변형
Toast(
  message: '오류가 발생했습니다.',
  description: '네트워크 연결을 확인해 주세요.',
  variant: CoreToastVariant.destructive,
  onDismiss: handleDismiss,
)

Props / Parameters#

빠른 오버라이드 (Chain)#

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

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

  @override
  Widget build(BuildContext context) {
    return Toast(
      message: 'Success',
      description: 'Your changes have been saved.',
      onDismiss: () {},
    ).withStyle(
      const CoreToastStyle(
        panelBorderRadius: CoreBorderRadius.all(CoreRadius.radius4),
        panelBorderColor: CoreColor.token(CoreColors.primary),
        panelBorderWidth: CoreStrokeWidth.stroke2,
        panelPaddingWithDismiss: CoreEdgeInsets.directional(
          start: CoreSpace.space16,
          top: CoreSpace.space16,
          end: CoreSpace.space32,
          bottom: CoreSpace.space16,
        ),
        messageDescriptionGapStyle: CoreGapStyle(size: CoreSpace.space8),
      ),
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    return Toast(
      message: 'Success',
      description: 'Your changes have been saved.',
      onDismiss: () {},
    ).withStyle(
      const CoreToastStyle(
        panelBorderRadius: CoreBorderRadius.all(CoreRadius.radius4),
        panelBorderColor: CoreColor.token(CoreColors.primary),
        panelBorderWidth: CoreStrokeWidth.stroke2,
        panelPaddingWithDismiss: CoreEdgeInsets.directional(
          start: CoreSpace.space16,
          top: CoreSpace.space16,
          end: CoreSpace.space32,
          bottom: CoreSpace.space16,
        ),
        messageDescriptionGapStyle: CoreGapStyle(size: CoreSpace.space8),
      ),
    );
  }
}

스타일 시스템 — toastStyle#

Toast 의 panel chrome / 슬롯 미세 조정은 단일 toastStyle (CoreToastStyle) 으로 흐릅니다. 시맨틱 enum (variant) 은 위젯 파라미터.

Toast(
  message: '저장 완료',
  description: '변경사항이 적용되었습니다',
  variant: CoreToastVariant.destructive,
  onDismiss: handleDismiss,
  action: Button(
    variant: .ghost,
    onPressed: undo,
    child: Text('되돌리기'),
  ),
  toastStyle: CoreToastStyle(
    panelBackgroundColor: CoreColor.token(CoreColors.surface),
    panelBorderColor: CoreColor.token(CoreColors.outline),
    panelBorderRadius: CoreBorderRadius.all(CoreRadius.radius12),
    panelPadding: CoreEdgeInsets.all(CoreSpace.space16),
    contentActionGapStyle: CoreGapStyle(size: CoreSpace.space12),
    messageStyle: CoreTextStyle.token(
      CoreTextStyles.labelLarge,
    ).copyWith(fontWeight: CoreFontWeight.semiBold),
    descriptionStyle: CoreTextStyle.token(
      CoreTextStyles.bodySmall,
      color: CoreColor.token(CoreColors.onSurfaceVariant),
    ),
    // actionButtonStyle 은 action 안의 Button 이 자동 적용 가능
    // (위처럼 variant 직접 주입 — asChild)
  ),
)

CoreToastStyle 필드#

CoreToastStyle 변형별 기본값 (CoreToastVariantStyle)#

asChild 패턴 — action 버튼 변경#

action 버튼의 시맨틱 (variant) 변경이 필요할 때는 action 슬롯에 직접 위젯을 주입합니다:

Toast(
  message: '...',
  action: Button(variant: .ghost, child: Text('되돌리기')),  // ← variant 직접
)

toastStyle.actionButtonStyle 은 chrome 미세 조정용 (paddingH / labelStyle 등).

Resolve chain#

design system default for variant
  → CoreToastTheme.style                       // 프로젝트 공통
  → CoreToastTheme.variantStyles[widget.variant]   // variant 별
  → 부모 컴포넌트 슬롯 오버라이드
  → widget.toastStyle                          // 인스턴스별

변형 (Variants)#

세 변형은 선행 글리프 하나로만 갈립니다. 배경 · 전경 · 보더는 셋 다 같은 inverse-surface 쌍이라(위 변형별 기본값 표 참조), 변형을 고르는 것은 색을 고르는 것이 아니라 무엇을 주장하는지를 고르는 것입니다.

neutral#

기본값입니다. 글리프가 없습니다 — 결과를 보고하지 않는 알림.

variant 를 적지 않으면 이것이 그려집니다. 아무 변형도 이름하지 않은 호출자는 어떤 결과도 주장하지 않은 것이고, 글리프 없는 토스트가 그 상태의 모습입니다.

Toast(
  message: 'New version available',
  description: 'Reload to get the latest.',
  onDismiss: handleDismiss,
)

success#

초록 성공 체크를 답니다. 무언가 성공했을 때만 씁니다.

Toast(
  message: 'Saved',
  description: 'Your changes have been saved.',
  variant: CoreToastVariant.success,
  onDismiss: handleDismiss,
)

default_ 는 이 변형의 옛 이름이고 deprecated 별칭으로 남아 있습니다. 값으로 쓰는 코드는 그대로 컴파일되지만, switch 의 exhaustive arm 은 success 로 바꿔야 합니다.

destructive#

오류 색 글리프를 답니다. 실패를 보고할 때 씁니다.

Toast(
  message: 'Error',
  description: 'Something went wrong.',
  variant: CoreToastVariant.destructive,
  onDismiss: handleDismiss,
)

Flutter 인프라 (ToastLayer)#

Flutter에서는 ToastLayer와 showToast()로 토스트 표시/스태킹/애니메이션을 관리합니다.

// 앱 최상단에 ToastLayer 배치
ToastLayer(
  maxStackedEntries: 3,
  expandMode: ExpandMode.expandOnHover,
  child: MyApp(),
)

// 토스트 표시
final overlay = showToast(
  context: context,
  builder: (context, overlay) => Toast(
    message: '처리 완료',
    onDismiss: overlay.close,
  ),
  location: ToastLocation.bottomRight,
  showDuration: Duration(seconds: 5),
);

// 프로그래밍 방식으로 닫기
overlay.close();

테마 커스터마이징#

CoreComponentTheme(
  toast: CoreToastTheme(
    style: CoreToastStyle(
      panelBorderRadius: CoreBorderRadius.all(CoreRadius.radius12),
    ),
  ),
)

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

✅ Do#

Toast(
  message: '삭제되었습니다.',
  action: Button(variant: .ghost, onPressed: undo, child: Text('되돌리기')),
  onDismiss: handleDismiss,
)

❌ Don't#

// ❌ Toast 카드만 트리 어딘가에 그대로 둠 — 스태킹/자동 닫힘/애니메이션 없음
Column(children: [Toast(message: '저장되었습니다.', onDismiss: () {})])

접근성 (Accessibility)#

스크린 리더#

• Flutter: Semantics(liveRegion: true) 적용으로 스크린 리더에 자동 알림
• Web: role="status", aria-live="polite" 적용으로 비침입적 알림

닫기 버튼#

• onDismiss가 제공되면 aria-label="Close" 속성이 있는 닫기 버튼 렌더링

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

관련 컴포넌트 (Related Components)#

• Dialog: 사용자 확인이 필요한 모달 알림
• Alert: 페이지에 고정된 알림
• Banner: 페이지 상단의 전체 너비 알림