FAB

화면에 고정된 플로팅 액션 버튼 컴포넌트

FAB#

화면의 주요 액션을 강조하는 플로팅 액션 버튼(Floating Action Button)입니다. 기본형, 소형, 대형, 확장형을 지원합니다.

Live Preview#

Web

Edit Share

Flutter

Loading Flutter...

Fab(
  trigger: Button(variant: CoreButtonVariant.primary, child: text('+')),
  actions: [
    FabAction(child: text('Edit')),
    FabAction(child: text('Share')),
  ],
)

Fab(
  onPressed: () {},
  child: Text('+'),
  actions: [
    FabAction(label: Text('Edit')),
    FabAction(label: Text('Share')),
  ],
)

사용 시기 (When to Use)#

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

화면 내에서 가장 중요한 단일 액션을 명확히 강조하고 싶을 때 (새 항목 만들기, 작성, 공유)
스크롤해도 항상 접근 가능해야 하는 주요 CTA(Call to Action)가 필요할 때
모바일 환경에서 큰 터치 타겟이 필요한 핵심 액션을 제공할 때

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

Button: 여러 동등한 액션을 나란히 제공할 때, 또는 인라인 액션이 필요할 때
IconButton: 툴바나 앱바 내에서 아이콘만으로 액션을 제공할 때

기본 사용법 (Basic Usage)#

// 기본 FAB
Fab(
  onPressed: handleCreate,
  icon: Icon(Icons.add),
)

// 확장형 FAB (라벨 포함)
Fab(
  onPressed: handleCreate,
  icon: Icon(Icons.add),
  label: '새 항목',
  isExtended: true,
)

// Secondary 변형
Fab(
  onPressed: handleEdit,
  icon: Icon(Icons.edit),
  variant: FabVariant.secondary,
)

// 소형 FAB
Fab(
  onPressed: handleShare,
  icon: Icon(Icons.share),
  size: FabSize.small,
)

// 기본 FAB
Fab(
  onClick: handleCreate,
  icon: Icon(Icons.add),
)

// 확장형 FAB
Fab(
  onClick: handleCreate,
  icon: Icon(Icons.add),
  label: '새 항목',
  isExtended: true,
)

// Secondary 변형
Fab(
  onClick: handleEdit,
  icon: Icon(Icons.edit),
  variant: FabVariant.secondary,
)

Props / Parameters#

속성	타입	기본값	설명
`onPressed`	`VoidCallback?`	`null`	클릭 핸들러. null이면 비활성화
`icon`	`Widget`	필수	버튼 내부 아이콘
`label`	`String?`	`null`	확장형 FAB에 표시할 텍스트
`size`	`FabSize`	`medium`	버튼 크기
`variant`	`FabVariant`	`primary`	버튼 변형 스타일
`isExtended`	`bool`	`false`	라벨을 포함한 확장형 여부
`tooltip`	`String?`	`null`	툴팁 텍스트

변형 (Variants)#

Primary#

가장 강조되는 주요 액션에 사용합니다.

Fab(
  variant: FabVariant.primary,
  onPressed: handleCreate,
  icon: Icon(Icons.add),
)

Secondary#

보조 액션에 사용합니다.

Fab(
  variant: FabVariant.secondary,
  onPressed: handleEdit,
  icon: Icon(Icons.edit),
)

Tertiary#

덜 중요한 액션에 사용합니다.

Fab(
  variant: FabVariant.tertiary,
  onPressed: handleFilter,
  icon: Icon(Icons.filter_list),
)

크기 (Sizes)#

크기	값	크기
Small	`FabSize.small`	40px
Medium	`FabSize.medium`	56px
Large	`FabSize.large`	96px

동작 스펙 (Behavior)#

인터랙션#

클릭/탭: onPressed 콜백 실행. onPressed가 null이면 비활성화 상태로 렌더링
호버: 배경색이 강조되고 elevation 상승 (Flutter: shadow 증가, Web: shadow 증가)
포커스: 포커스 링 표시로 키보드 탐색 가능 상태 표시

상태 전환#

default → hover → pressed → default
disabled 상태에서는 모든 인터랙션 무시, 반투명 처리

애니메이션#

확장형(isExtended) 전환: 너비 변경 시 200ms ease-in-out
호버/프레스 상태: elevation 변화 150ms ease
아이콘 회전 애니메이션 지원 (필요 시 커스텀)

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

✅ Do#

한 화면에 하나의 FAB만 사용

// 가장 중요한 단일 액션에만 FAB 사용
Scaffold(
  floatingActionButton: CouiFab(
    onPressed: handleCreatePost,
    icon: Icon(Icons.add),
    label: '새 글 작성',
    isExtended: true,
  ),
)

FAB은 화면에서 가장 중요한 단일 액션을 나타내야 합니다. 여러 개를 사용하면 사용자가 어느 것이 주요 액션인지 혼란스러워집니다.

❌ Don't#

빈번한 액션이나 파괴적인 액션에 FAB 사용 금지

// ❌ 삭제(파괴적) 액션에 FAB 사용
CouiFab(
  onPressed: handleDeleteAll,
  icon: Icon(Icons.delete),
)

FAB은 눈에 잘 띄기 때문에 실수로 클릭하기 쉽습니다. 삭제 같은 파괴적인 액션에는 확인 다이얼로그가 있는 일반 버튼을 사용하세요.

✅ Do#

확장형 FAB으로 액션 명확히 전달

// 처음에는 텍스트 포함 확장형, 스크롤 시 아이콘만
CouiFab(
  onPressed: handleCompose,
  icon: Icon(Icons.edit),
  label: '이메일 작성',
  isExtended: isAtTop,
)

확장형 FAB은 아이콘만 있는 FAB보다 사용자가 액션을 명확히 이해할 수 있게 해줍니다.

❌ Don't#

콘텐츠를 가리는 위치에 FAB 배치 금지

// ❌ 하단 네비게이션과 겹치게 배치
Scaffold(
  bottomNavigationBar: CouiNavigationBar(...),
  // FAB이 네비게이션 바를 가림
  floatingActionButtonLocation: FloatingActionButtonLocation.endFloat,
  floatingActionButton: CouiFab(onPressed: handleCreate, icon: Icon(Icons.add)),
)

FAB이 중요한 콘텐츠나 네비게이션 요소를 가리면 사용성이 저하됩니다. endContained 위치를 사용하거나 하단 네비게이션과 겹치지 않도록 조정하세요.

✅ Do#

FAB는 한 화면에 하나만 사용하세요.

Scaffold(
  floatingActionButton: CouiFab(
    onPressed: handleCreateNote,
    child: Icon(Icons.add),
    tooltip: '새 노트 작성',
  ),
  body: NoteList(),
)

FAB는 화면의 주요 액션 하나를 강조합니다. 여러 FAB를 동시에 표시하면 사용자의 시선이 분산됩니다.

❌ Don't#

부차적인 액션에 FAB를 사용하지 마세요.

// ❌ 보조 기능에 FAB 사용
Scaffold(
  floatingActionButton: CouiFab(
    onPressed: handleOpenFilter,  // 필터는 주요 액션이 아님
    child: Icon(Icons.filter_list),
  ),
  body: content,
)

FAB는 가장 중요한 단일 액션을 위한 컴포넌트입니다. 필터, 정렬 등 보조 기능은 AppBar나 BottomSheet에 배치하세요.

접근성 (Accessibility)#

키보드 인터랙션#

키	동작
`Enter` / `Space`	FAB 액션 실행
`Tab`	다음 포커스 가능 요소로 이동

스크린 리더#

Flutter: Semantics 위젯으로 버튼 레이블 및 상태 전달. tooltip prop 설정 권장
Web: aria-label 자동 적용. isExtended 시 텍스트가 레이블 역할

터치 타겟#

Small: 40px (최소 권장보다 작음, 중요도 낮은 보조 액션에만 사용)
Medium: 56px (기본, 권장)
Large: 96px (특별히 강조가 필요한 경우)

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

항목	Flutter	Web
클래스명	`CouiFab`	`Fab`
클릭 핸들러	`onPressed`	`onClick`
elevation	Material elevation 지원	CSS shadow
위치 제어	`Scaffold.floatingActionButton`	CSS `position: fixed`

Button: 인라인 또는 덜 중요한 액션에 사용
Tooltip: 아이콘 전용 FAB에 레이블 설명 추가 시 함께 사용

조합 예제#

// FAB + Tooltip 조합
CouiTooltip(
  message: '새 항목 만들기',
  child: CouiFab(
    onPressed: handleCreate,
    icon: Icon(Icons.add),
  ),
)

FAB

FAB#

Live Preview#

사용 시기 (When to Use)#

기본 사용법 (Basic Usage)#

Props / Parameters#

변형 (Variants)#

Primary#

Secondary#

Tertiary#

크기 (Sizes)#

동작 스펙 (Behavior)#

인터랙션#

상태 전환#

애니메이션#

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

✅ Do#

❌ Don't#

✅ Do#

❌ Don't#

✅ Do#

❌ Don't#

접근성 (Accessibility)#

키보드 인터랙션#

스크린 리더#

터치 타겟#

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

관련 컴포넌트 (Related Components)#

조합 예제#