한국어 문서 보기 (View in Korean)

grabber_sheet #

A reusable and customizable draggable bottom sheet with a grabber handle, inspired by the modal sheets in popular apps like Google Maps.

Ideally suited for developers who need to build complex UIs within a bottom sheet while maintaining a separate, draggable grabber area and smooth snapping behavior.

It solves the common frustrations with Flutter's built-in DraggableScrollableSheet:

1. Independent Grabber Area: The grabber and header are separate from the scrollable content. Dragging the header moves the sheet; scrolling the content scrolls the list. No more gesture conflicts.
2. Predictable Snapping: Easily snap to specific heights without complex controller logic.
3. Seamless Integration: Works perfectly with ListView, SingleChildScrollView, and other scrollable widgets.

Why use GrabberSheet? #

If you've ever struggled with:

• The grabber disappearing when you scroll down.
• The sheet not moving when you try to drag the header.
• Janky snapping animations.

Then GrabberSheet is the solution you've been looking for. It provides a robust, production-ready implementation of the "modal bottom sheet" pattern found in top-tier mobile apps.

Features #

• Conflict-Free Dragging: Dedicated drag zone for the sheet, independent of the inner scroll view.
• Customizable Grabber: Style the handle to match your app's design.
• Smooth Snapping: Built-in support for snapping to min, max, and custom intermediate sizes.
• Flexible Content: Use any widget (ListView, Column, etc.) via a simple builder.
• Header Support: Insert custom widgets (titles, buttons) into the non-scrollable drag area.
• Cross-Platform: Works on Mobile, with optional desktop/web support for the grabber.

Getting started #

Add this to your package's pubspec.yaml file. Check the latest version on pub.dev.

dependencies:
  grabber_sheet: ^1.1.0

Then, install it by running flutter pub get in your terminal.

Compatibility #

This package is compatible with the following SDK versions:

• Flutter: >=3.0.0
• Dart: >=3.0.0 <4.0.0

Basic Usage #

Here's a simple example of how to use GrabberSheet:

import 'package:flutter/material.dart';
import 'package:grabber_sheet/grabber_sheet.dart';

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

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context);
    final sheetColor = Colors.blue.shade100;

    return Scaffold(
      backgroundColor: Colors.white,
      appBar: AppBar(
        title: const Text('GrabberSheet Example'),
        backgroundColor: sheetColor,
      ),
      body: Stack(
        children: [
          Center(
            child: Text(
              'Background Content',
              style: theme.textTheme.headlineMedium,
            ),
          ),
          GrabberSheet(
            initialChildSize: 0.5,
            minChildSize: 0.2,
            maxChildSize: 0.8,
            snap: true,
            snapSizes: const [.5],
            backgroundColor: sheetColor,
            grabberStyle: GrabberStyle(color: Colors.grey.shade400),
            bottom: Row(
              children: [
                const Text('sheet title'),
                const Spacer(),
                IconButton(onPressed: () {}, icon: const Icon(Icons.close)),
              ],
            ),
            bottomAreaPadding: const EdgeInsets.symmetric(horizontal: 16),
            builder: (BuildContext context, ScrollController scrollController) {
              return ListView.builder(
                controller: scrollController,
                itemCount: 30,
                itemBuilder: (BuildContext context, int index) {
                  return ListTile(
                    title: Text(
                      'Item $index',
                      style: TextStyle(
                        color: theme.colorScheme.onSurface,
                      ),
                    ),
                  );
                },
              );
            },
          ),
        ],
      ),
    );
  }
}

Advanced Customization #

Adding a Custom Widget to the Grabber Area #

You can insert a custom widget into the draggable area below the grabber handle using the bottom property. This entire area (handle and custom widget) is draggable. This is useful for adding a title, action buttons, or any other information that should remain visible and separate from the scrollable content.

The bottomAreaPadding property can be used to add padding around this custom widget.

GrabberSheet(
  bottom: Row(
    children: [
      const Text('sheet title'),
      const Spacer(),
      IconButton(onPressed: () {}, icon: const Icon(Icons.close)),
    ],
  ),
  bottomAreaPadding: const EdgeInsets.symmetric(horizontal: 16),
  builder: (context, scrollController) {
    // ... your list of locations
  },
),

Customizing the Grabber #

The appearance of the grabber handle can be fully customized using the grabberStyle property.

GrabberSheet(
  grabberStyle: GrabberStyle(
    width: 60,
    height: 6,
    margin: const EdgeInsets.symmetric(vertical: 10),
    color: Colors.grey.shade300,
    radius: const Radius.circular(12),
  ),
  builder: (context, scrollController) {
    // ... your content
  },
),

You can also hide the grabber completely by setting showGrabber: false.

Showing the Grabber on Desktop and Web #

By default, the grabber handle is only visible on mobile platforms (iOS, Android). However, you can force it to always be visible on desktop (Windows, macOS, Linux) and web platforms by setting the showGrabberOnNonMobile property to true. This is useful when you want to provide a consistent UI across all platforms.

GrabberSheet(
  showGrabberOnNonMobile: true,
  builder: (context, scrollController) {
    // ... Your content
  },
),

Controlling Snap Behavior #

By setting snap to true, the sheet will automatically animate to the nearest defined snap point when a drag gesture ends. This creates a clean, predictable motion for the user.

The snapping logic behaves differently based on the drag gesture:

• Slow Drag: If the user slowly drags the sheet and releases, it will snap to the closest snap point.
• Fling: If the user "flings" the sheet with a quick gesture, it will animate to the nearest boundary (either minChildSize or maxChildSize) in the direction of the fling.

You can define the snap points using minChildSize, maxChildSize, and the optional snapSizes for any intermediate points.

Here is an example with multiple intermediate snap points:

GrabberSheet(
  // Enable snapping
  snap: true, 
  
  // Define snap points: 0.2 (min), 0.5, 0.8 (intermediate), and 1.0 (max)
  minChildSize: 0.2,
  maxChildSize: 1.0,
  initialChildSize: 0.5,
  snapSizes: const [0.5, 0.8],
  
  builder: (context, scrollController) {
    // ... your content
  },
),

Properties #

GrabberSheet #

GrabberStyle #

Additional information #

To file issues, request features, or contribute, please visit the GitHub repository.