flutter-ui Reference

Provides detailed descriptions, example code, and precautions for each Use Case.

Flutter UI Patterns - Reference#

Provides detailed descriptions, example code, and precautions for each Use Case.

1. Page Structure#

Overview#

All pages follow a consistent structure.

Basic Structure#

class MyPage extends HookWidget {
  const MyPage({super.key});

  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (_) => MyBloc()..add(const MyEvent.started()),
      child: Scaffold(
        headers: [
          AppBar(
            title: Text('페이지 제목'),
            leading: [
              IconButton.ghost(
                icon: HeroIcon(HeroIcons.arrowLeft),
                onPressed: () => context.pop(),
              ),
            ],
            trailing: [
              IconButton.ghost(
                icon: HeroIcon(HeroIcons.cog6Tooth),
                onPressed: onSettings,
              ),
            ],
          ),
        ],
        child: const _Body(),
      ),
    );
  }
}

class _Body extends StatelessWidget {
  const _Body();

  @override
  Widget build(BuildContext context) {
    return BlocBuilder<MyBloc, MyState>(
      builder: (context, state) {
        return Padding(
          padding: EdgeInsets.symmetric(horizontal: Spacing.s4),
          child: Column(
            children: [
              // 컨텐츠
            ],
          ),
        );
      },
    );
  }
}

Pattern Selection Criteria#

Pattern	When to Use	Example
HookWidget + BlocProvider	Async data loading	Details Page, List
HookWidget only	Only local state needed	Settings Page, Form
StatelessWidget	No state	Static info Page

Precautions#

// ✅ CORRECT: BlocProvider는 페이지 레벨에서 생성
class MyPage extends HookWidget {
  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (_) => MyBloc(),
      child: _Body(),
    );
  }
}

// ❌ WRONG: build 메서드 내에서 매번 생성 금지
class MyPage extends HookWidget {
  @override
  Widget build(BuildContext context) {
    final bloc = MyBloc(); // 매번 새로 생성됨!
    return BlocProvider.value(
      value: bloc,
      child: _Body(),
    );
  }
}

2. State Management#

BLoC Pattern Overview#

User Action → Event → BLoC → State → UI Update

BlocBuilder#

Used for UI rendering based on state.

BlocBuilder<MyBloc, MyState>(
  // Optional: specify rebuild conditions
  buildWhen: (previous, current) => previous.items != current.items,
  builder: (context, state) {
    // State branching with switch expression (recommended)
    return switch (state) {
      MyStateInitial() => const SizedBox.shrink(),
      MyStateLoading() => const LoadingIndicator(),
      MyStateSuccess(:final data) => SuccessWidget(data: data),
      MyStateFailure(:final error) => ErrorWidget(message: error),
    };
  },
)

BlocConsumer#

Used when both UI rendering and side effects are needed.

BlocConsumer<AuthBloc, AuthState>(
  listenWhen: (previous, current) => previous.status != current.status,
  listener: (context, state) {
    // Side effects: navigation, snackbar, dialog
    if (state.isAuthenticated) {
      context.go('/home');
    }
    if (state.hasError) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text(state.errorMessage)),
      );
    }
  },
  buildWhen: (previous, current) => previous.formState != current.formState,
  builder: (context, state) {
    return LoginForm(
      isLoading: state.isLoading,
      isValid: state.isValid,
    );
  },
)

BlocListener#

Used when only side effects are needed.

BlocListener<PaymentBloc, PaymentState>(
  listenWhen: (previous, current) => current.isCompleted,
  listener: (context, state) {
    showDialog(
      context: context,
      builder: (_) => SuccessDialog(),
    );
  },
  child: PaymentForm(),
)

MultiBlocProvider#

Used in pages requiring multiple BLoCs.

MultiBlocProvider(
  providers: [
    BlocProvider(create: (_) => UserBloc()),
    BlocProvider(create: (_) => SettingsBloc()),
    BlocProvider(create: (_) => NotificationBloc()),
  ],
  child: SettingsPage(),
)

Event Dispatching#

// ✅ CORRECT: context.read 사용
Button.primary(
  onPressed: () {
    context.read<MyBloc>().add(const MyEvent.submitted());
  },
  child: Text('제출'),
)

// ❌ WRONG: context.watch로 이벤트 발송 금지
Button.primary(
  onPressed: () {
    context.watch<MyBloc>().add(...); // 불필요한 리빌드 발생
  },
)

3. Local State (Hooks)#

Basic Hooks#

class MyWidget extends HookWidget {
  @override
  Widget build(BuildContext context) {
    // useState - 단순 상태
    final counter = useState(0);
    final isVisible = useState(true);

    // useTextEditingController - 텍스트 입력
    final controller = useTextEditingController();

    // useEffect - 사이드 이펙트
    useEffect(() {
      final subscription = stream.listen((value) {
        counter.value = value;
      });
      return subscription.cancel; // cleanup
    }, []); // 빈 배열 = componentDidMount

    return Column(
      children: [
        Text('Count: ${counter.value}'),
        TextField(controller: controller),
        Switch(
          value: isVisible.value,
          onChanged: (v) => isVisible.value = v,
        ),
      ],
    );
  }
}

Animation Hooks#

class AnimatedWidget extends HookWidget {
  @override
  Widget build(BuildContext context) {
    final animationController = useAnimationController(
      duration: const Duration(milliseconds: 300),
    );

    final animation = useAnimation(
      CurvedAnimation(
        parent: animationController,
        curve: Curves.easeInOut,
      ),
    );

    return FadeTransition(
      opacity: animation,
      child: Content(),
    );
  }
}

useMemoized#

Caches expensive computation results.

final expensiveResult = useMemoized(
  () => computeExpensiveValue(items),
  [items], // 의존성 변경 시 재계산
);

useCallback#

Memoizes callback functions.

final onSubmit = useCallback(() {
  context.read<MyBloc>().add(const MyEvent.submitted());
}, []);

4. Typography#

Text Chaining Pattern#

This project's standard text styling approach.

// 크기
Text('텍스트').xs    // 12px
Text('텍스트').sm    // 14px
Text('텍스트').md    // 16px (default)
Text('텍스트').lg    // 18px
Text('텍스트').xl    // 20px

// 굵기
Text('텍스트').normal     // 400
Text('텍스트').medium     // 500
Text('텍스트').semiBold   // 600
Text('텍스트').bold       // 700

// 색상
Text('텍스트').baseContent    // default 텍스트
Text('텍스트').base200        // 보조 텍스트
Text('텍스트').primary        // Primary color
Text('텍스트').success        // 성공
Text('텍스트').error          // 에러

// 조합
Text('제목').lg.bold.baseContent
Text('부제목').md.semiBold.base200
Text('본문').sm.normal.baseContent
Text('캡션').xs.normal.base200.withOpacity(0.7)

Direct Typography Access#

Access the typography object directly in special cases.

final typography = context.theme.typography;

// 스타일 병합
Text(
  '텍스트',
  style: typography.lg.merge(typography.semiBold).copyWith(
    letterSpacing: 0.5,
  ),
)

Precautions#

// ❌ WRONG: TextStyle 직접 정의 금지
Text(
  '텍스트',
  style: TextStyle(
    fontSize: 18,
    fontWeight: FontWeight.bold,
  ),
)

// ✅ CORRECT: Text chaining 사용
Text('텍스트').lg.bold

5. Buttons#

Button Variants#

// Primary - 주요 액션 (제출, 확인)
Button.primary(
  onPressed: onSubmit,
  expanded: true,        // 전체 너비
  enabled: isValid,      // 활성화 상태
  child: Text('확인'),
)

// Ghost - 보조 액션 (취소, 뒤로)
Button.ghost(
  onPressed: onCancel,
  child: Text('취소'),
)

// Card - 카드 형태 버튼
Button.card(
  style: const ButtonStyle.card().copyWith(
    borderRadius: RadiusScale.kBox,
  ),
  onPressed: onTap,
  child: Column(
    children: [
      Icon(Icons.settings),
      Text('설정'),
    ],
  ),
)

// Outline - 테두리 버튼
Button.outline(
  onPressed: onTap,
  child: Text('자세히 보기'),
)

IconButton#

IconButton.ghost(
  icon: HeroIcon(HeroIcons.pencilSquare),
  onPressed: onEdit,
)

IconButton.primary(
  icon: HeroIcon(HeroIcons.plus),
  onPressed: onAdd,
)

Button Size#

Button.primary(
  style: const ButtonStyle.primary().copyWith(
    size: ButtonSize.small,
  ),
  onPressed: onTap,
  child: Text('작은 버튼'),
)

Precautions#

// ❌ WRONG: 빈 style 파라미터 금지
Button.ghost(
  style: const ButtonStyle.ghost(
    // 빈 괄호
  ),
  onPressed: onTap,
  child: Text('취소'),
)

// ✅ CORRECT: default값 사용 시 style 생략
Button.ghost(
  onPressed: onTap,
  child: Text('취소'),
)

6. Forms#

Basic Form Structure#

class LoginForm extends HookWidget {
  @override
  Widget build(BuildContext context) {
    final formKey = useMemoized(GlobalKey<FormState>.new);
    final emailController = useTextEditingController();
    final passwordController = useTextEditingController();
    final isValid = useState(false);

    void validate() {
      isValid.value = formKey.currentState?.validate() ?? false;
    }

    return Form(
      key: formKey,
      onChanged: validate,
      child: Column(
        children: [
          FormTextField(
            controller: emailController,
            label: Text('이메일'),
            placeholder: '이메일을 입력하세요',
            keyboardType: TextInputType.emailAddress,
            validator: (value) {
              if (value == null || value.isEmpty) {
                return '이메일을 입력하세요';
              }
              if (!value.contains('@')) {
                return '올바른 이메일 형식이 아닙니다';
              }
              return null;
            },
          ),
          const Gap.s4(),
          FormTextField(
            controller: passwordController,
            label: Text('비밀번호'),
            placeholder: '비밀번호를 입력하세요',
            obscureText: true,
            validator: (value) {
              if (value == null || value.length < 8) {
                return '8자 이상 입력하세요';
              }
              return null;
            },
          ),
          const Gap.s6(),
          Button.primary(
            expanded: true,
            enabled: isValid.value,
            onPressed: () {
              if (formKey.currentState!.validate()) {
                // 제출 로직
              }
            },
            child: Text('로그인'),
          ),
        ],
      ),
    );
  }
}

FormTextField Properties#

FormTextField(
  controller: controller,
  label: Text('라벨'),
  placeholder: '플레이스홀더',
  height: 56,                              // 높이
  keyboardType: TextInputType.text,        // 키보드 타입
  textInputAction: TextInputAction.next,   // 액션 버튼
  autofocus: true,                         // 자동 포커스
  obscureText: false,                      // 비밀번호 숨김
  maxLines: 1,                             // 최대 줄 수
  enabled: true,                           // 활성화 상태
  readOnly: false,                         // 읽기 전용
  validator: (value) => null,              // 검증 함수
  onChanged: (value) {},                   // After 콜백
  onSubmitted: (value) {},                 // 제출 콜백
)

Validation State Visualization#

enum ValidationState { pending, valid, invalid }

Widget buildValidationIcon(ValidationState state) {
  final colorScheme = context.theme.colorScheme;

  return switch (state) {
    ValidationState.pending => Icon(
        Icons.circle_outlined,
        color: colorScheme.baseContent,
      ),
    ValidationState.valid => Icon(
        Icons.check_circle,
        color: colorScheme.success,
      ),
    ValidationState.invalid => Icon(
        Icons.error,
        color: colorScheme.error,
      ),
  };
}

7. Loading States#

Skeletonizer#

Converts widget to skeleton loading state.

BlocBuilder<MyBloc, MyState>(
  builder: (context, state) {
    return MyCard(
      title: state.title ?? 'Loading Title',
      subtitle: state.subtitle ?? 'Loading Subtitle',
    ).skeletonizer(enabled: state.isLoading);
  },
)

loadingOr Extension#

Displays conditional loading widget.

// default 사용
ContentWidget().loadingOr(
  isLoading: isLoading,
  loadingWidget: const CircularProgressIndicator(),
)

// Mock 데이터로 스켈레톤
ContentWidget().loadingOrWithMock(
  isLoading: isLoading,
  mockWidget: () => ContentWidget(data: MockData()),
)

emptyOrWhen Extension#

Used for empty state handling.

ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) => ItemCard(item: items[index]),
).emptyOrWhen(
  condition: () => items.isEmpty,
  emptyWidget: const EmptyStateWidget(
    icon: HeroIcon(HeroIcons.inbox),
    title: '항목이 없습니다',
    subtitle: '새 항목을 추가해보세요',
  ),
)

State-based UI Branching#

BlocBuilder<MyBloc, MyState>(
  builder: (context, state) {
    return switch (state.status) {
      LoadingStatus.initial => const SizedBox.shrink(),
      LoadingStatus.loading => const Center(
          child: CircularProgressIndicator(),
        ),
      LoadingStatus.success => SuccessWidget(data: state.data),
      LoadingStatus.failure => ErrorWidget(
          message: state.errorMessage,
          onRetry: () => context.read<MyBloc>().add(const MyEvent.retried()),
        ),
    };
  },
)

8. Color System#

ColorScheme Access#

final colorScheme = context.theme.colorScheme;

Semantic Colors#

Token	Purpose	Example
`primary`	Primary actions, brand	Buttons, links
`primaryContent`	Text on primary	Button text
`success`	Success state	Completion, approval
`error`	Error state	Failure, error
`warning`	Warning state	Caution, alerts
`info`	Information display	Guidance, tips

Base Colors#

Token	Purpose	Example
`base100`	Default background	Page background
`base200`	Card background	Cards, containers
`base300`	Divider lines, borders	Dividers
`baseContent`	Default text	Titles, body text
`neutral`	Neutral elements	Disabled buttons

Usage Examples#

Container(
  color: colorScheme.base100,
  child: Column(
    children: [
      Container(
        color: colorScheme.base200,
        child: Text('카드 내용').baseContent,
      ),
      Divider(color: colorScheme.base300),
      Container(
        color: colorScheme.success,
        child: Text('성공!').successContent,
      ),
    ],
  ),
)

Applying Opacity#

// ✅ CORRECT: withValues 사용
colorScheme.baseContent.withValues(alpha: 0.5)
Colors.black.withValues(alpha: 0.2)

// ❌ WRONG: withOpacity 사용 (deprecated)
colorScheme.baseContent.withOpacity(0.5)

9. Spacing#

// 상수 Gap
const Gap.s1()   // 4px
const Gap.s2()   // 8px
const Gap.s3()   // 12px
const Gap.s4()   // 16px
const Gap.s5()   // 20px
const Gap.s6()   // 24px
const Gap.s8()   // 32px

// 동적 Gap
Gap(Spacing.s4)

Spacing Constants#

// EdgeInsets에서 사용
EdgeInsets.all(Spacing.s4)
EdgeInsets.symmetric(
  horizontal: Spacing.s4,
  vertical: Spacing.s2,
)
EdgeInsets.only(
  top: Spacing.s4,
  bottom: Spacing.s2,
  left: Spacing.s4,
  right: Spacing.s4,
)

Consistent Spacing Usage#

Column(
  children: [
    Header(),
    const Gap.s4(),        // 헤더 아래 16px
    ContentSection(),
    const Gap.s6(),        // 섹션 간 24px
    Footer(),
  ],
)

Padding(
  padding: EdgeInsets.symmetric(
    horizontal: Spacing.s4,  // 좌우 16px
    vertical: Spacing.s2,    // 상하 8px
  ),
  child: Content(),
)

10. Overlays#

Dialog#

Future<bool?> showConfirmDialog(BuildContext context) {
  return showDialog<bool>(
    context: context,
    barrierColor: Colors.black.withValues(alpha: 0.2),
    builder: (context) => AlertDialog(
      title: Text('삭제 확인'),
      content: Text('정말 삭제하시겠습니까?'),
      actions: [
        Button.ghost(
          onPressed: () => Navigator.pop(context, false),
          child: Text('취소'),
        ),
        Button.primary(
          onPressed: () => Navigator.pop(context, true),
          child: Text('삭제'),
        ),
      ],
    ),
  );
}

// 사용
final result = await showConfirmDialog(context);
if (result == true) {
  // 삭제 수행
}

BottomSheet#

void showOptionsSheet(BuildContext context) {
  showModalBottomSheet(
    context: context,
    isScrollControlled: true,  // 높이 조절 가능
    shape: const RoundedRectangleBorder(
      borderRadius: BorderRadius.vertical(top: Radius.circular(16)),
    ),
    builder: (context) => SafeArea(
      child: Padding(
        padding: EdgeInsets.all(Spacing.s4),
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            ListTile(
              leading: HeroIcon(HeroIcons.pencil),
              title: Text('편집'),
              onTap: () {
                Navigator.pop(context);
                // 편집 로직
              },
            ),
            ListTile(
              leading: HeroIcon(HeroIcons.trash),
              title: Text('삭제').error,
              onTap: () {
                Navigator.pop(context);
                // 삭제 로직
              },
            ),
          ],
        ),
      ),
    ),
  );
}

Popover(
  positions: [PopoverPosition.bottom],
  barrierColor: Colors.transparent,
  builder: (context) => Container(
    padding: EdgeInsets.all(Spacing.s2),
    decoration: BoxDecoration(
      color: colorScheme.base200,
      borderRadius: BorderRadius.circular(8),
      boxShadow: [
        BoxShadow(
          color: Colors.black.withValues(alpha: 0.1),
          blurRadius: 8,
        ),
      ],
    ),
    child: Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        PopoverItem(title: '옵션 1', onTap: onOption1),
        PopoverItem(title: '옵션 2', onTap: onOption2),
      ],
    ),
  ),
  child: IconButton.ghost(
    icon: HeroIcon(HeroIcons.ellipsisVertical),
    onPressed: null, // Popover가 처리
  ),
)

11. Lists#

Basic ListView#

ListView.separated(
  padding: EdgeInsets.all(Spacing.s4),
  itemCount: items.length,
  separatorBuilder: (_, __) => const Gap.s2(),
  itemBuilder: (context, index) {
    final item = items[index];
    return ItemCard(item: item);
  },
)

RefreshIndicator#

RefreshIndicator(
  onRefresh: () async {
    context.read<MyBloc>().add(const MyEvent.refreshed());
    // BLoC 상태가 업데이트될 때까지 대기
    await context.read<MyBloc>().stream.firstWhere(
      (state) => !state.isRefreshing,
    );
  },
  child: ListView.builder(
    itemCount: items.length,
    itemBuilder: (context, index) => ItemCard(item: items[index]),
  ),
)

CustomScrollView + SliverList#

CustomScrollView(
  slivers: [
    SliverAppBar(
      title: Text('목록'),
      floating: true,
    ),
    SliverPadding(
      padding: EdgeInsets.symmetric(horizontal: Spacing.s4),
      sliver: SliverList.separated(
        itemCount: items.length,
        separatorBuilder: (_, __) => const Gap.s2(),
        itemBuilder: (context, index) => ItemCard(item: items[index]),
      ),
    ),
  ],
)

Infinite Scroll (Pagination)#

class InfiniteListWidget extends HookWidget {
  @override
  Widget build(BuildContext context) {
    final scrollController = useScrollController();

    useEffect(() {
      void onScroll() {
        if (scrollController.position.pixels >=
            scrollController.position.maxScrollExtent - 200) {
          context.read<MyBloc>().add(const MyEvent.loadMore());
        }
      }

      scrollController.addListener(onScroll);
      return () => scrollController.removeListener(onScroll);
    }, []);

    return BlocBuilder<MyBloc, MyState>(
      builder: (context, state) {
        return ListView.builder(
          controller: scrollController,
          itemCount: state.items.length + (state.hasMore ? 1 : 0),
          itemBuilder: (context, index) {
            if (index >= state.items.length) {
              return const Center(child: CircularProgressIndicator());
            }
            return ItemCard(item: state.items[index]);
          },
        );
      },
    );
  }
}

GoRouter Setup#

// route 정의
@TypedGoRoute<HomeRoute>(
  path: '/',
  routes: [
    TypedGoRoute<ProfileRoute>(path: 'profile/:userId'),
    TypedGoRoute<SettingsRoute>(path: 'settings'),
  ],
)
class HomeRoute extends GoRouteData {
  const HomeRoute();

  @override
  Widget build(BuildContext context, GoRouterState state) {
    return const HomePage();
  }
}

class ProfileRoute extends GoRouteData {
  const ProfileRoute({required this.userId});
  final String userId;

  @override
  Widget build(BuildContext context, GoRouterState state) {
    return ProfilePage(userId: userId);
  }
}

// Navigate (replace history)
context.go('/home');

// Push page (keep history)
context.push('/details');

// Go back
context.pop();

// Go back with result
context.pop(result);

// TypedRoute usage (type-safe)
const ProfileRoute(userId: '123').go(context);
const ProfileRoute(userId: '123').push(context);

// Navigating page
Button.primary(
  onPressed: () async {
    final result = await context.push<String>('/select-item');
    if (result != null) {
      // 결과 처리
    }
  },
  child: Text('선택'),
)

// Page returning result
Button.primary(
  onPressed: () => context.pop(selectedItem),
  child: Text('확인'),
)

Deep Link Parameters#

@TypedGoRoute<SearchRoute>(path: '/search')
class SearchRoute extends GoRouteData {
  const SearchRoute({this.query, this.category});

  final String? query;
  final String? category;

  @override
  Widget build(BuildContext context, GoRouterState state) {
    return SearchPage(
      initialQuery: query,
      initialCategory: category,
    );
  }
}

// Navigate with query parameters
const SearchRoute(query: 'flutter', category: 'tutorial').go(context);
// → /search?query=flutter&category=tutorial

flutter-ui Reference

Flutter UI Patterns - Reference#

1. Page Structure#

Overview#

Basic Structure#

Pattern Selection Criteria#

Precautions#

2. State Management#

BLoC Pattern Overview#

BlocBuilder#

BlocConsumer#

BlocListener#

MultiBlocProvider#

Event Dispatching#

3. Local State (Hooks)#

Basic Hooks#

Animation Hooks#

useMemoized#

useCallback#

4. Typography#

Text Chaining Pattern#

Direct Typography Access#

Precautions#

5. Buttons#

Button Variants#

IconButton#

Button Size#

Precautions#

6. Forms#

Basic Form Structure#

FormTextField Properties#

Validation State Visualization#

7. Loading States#

Skeletonizer#

loadingOr Extension#

emptyOrWhen Extension#

State-based UI Branching#

8. Color System#

ColorScheme Access#

Semantic Colors#

Base Colors#

Usage Examples#

Applying Opacity#

9. Spacing#

Gap Widget#

Spacing Constants#

Consistent Spacing Usage#

10. Overlays#

Dialog#

BottomSheet#

Popover#

11. Lists#

Basic ListView#

RefreshIndicator#

CustomScrollView + SliverList#

Infinite Scroll (Pagination)#

12. Navigation#

GoRouter Setup#

Navigation Methods#

Receiving Navigation Results#

Deep Link Parameters#