smooth_sheets

smooth_sheets

smooth_sheets is a Flutter package providing modal and persistent sheet widgets designed for smooth, graceful motion and high flexibility.

Key Capabilities:

• Smooth Motion: High-quality interaction response.
• Flexible Design: Supports both modal and persistent styles, as well as scrollable and non-scrollable content without design restrictions.
• Nested Navigation: Supports sheets with multiple pages and motion-animated transitions between them.
• Navigator Compatibility: Works seamlessly with both the imperative Navigator API (Navigator.push) and declarative Navigator 2.0 APIs (e.g., go_router).
• iOS Style: Includes support for iOS 15-style modal sheets.

Sheet behavior is controlled by two distinct mechanisms:

1. SheetPhysics: Determines how the sheet behaves during over-dragging, under-dragging, or when the user stops dragging (e.g., momentum/friction). This is independent of snapping.
2. SheetSnapGrid: Determines the specific offsets to which the sheet snaps when the user stops dragging or when an animation completes.

In v0.11.x, SheetViewport is a required component for non-modal sheets. Modal sheets (like those using ModalSheetRoute or ModalSheetPage) create a SheetViewport internally and do not require you to wrap them manually.

Adding Padding

You can add transparent space around a sheet using the padding property on SheetViewport for regular sheets, or the viewportPadding property on modal routes.

// For Regular Sheets
SheetViewport(
  padding: EdgeInsets.all(10),
  child: Sheet(...),
)

// For Modal Sheets
ModalSheetRoute(
  viewportPadding: EdgeInsets.only(
    top: MediaQuery.viewPaddingOf(context).top,
    bottom: 10,
    left: 10,
    right: 10,
  ),
  builder: (context) => Sheet(...),
);

Use PagedSheet to manage a stack of pages within a single sheet, allowing for transitions between them. It integrates with Flutter's Navigator API for both imperative (Navigator.push) and declarative (e.g., go_router, auto_route) navigation.

Each page in the stack is defined using a PagedSheetPage, which allows for per-page configurations such as:

• initialOffset
• snapGrid
• scrollConfiguration
• Custom transitions (defaults to the application's theme)

In v0.11.x, sheet physics and snapping behavior are separated into two independent properties on the Sheet widget: physics and snapGrid.

Sheet(
  physics: const BouncingSheetPhysics(),
  snapGrid: const SheetSnapGrid(
    snaps: [SheetOffset(0.5), SheetOffset(1)],
  ),
  // ...
)

The v0.11.x API has standardized terminology around the concept of Offset to replace inconsistent terms like 'extent', 'position', and 'anchor'.

If you are deciding between smooth_sheets and wolt_modal_sheet, consider these differences:

Starting from version 0.3.x, SnapToNearest can no longer be declared as a const due to performance optimizations.

If you want the sheet to snap only to the minimum and maximum pixel boundaries, it is recommended to use SnapToNearestEdge instead of SnapToNearest, as it is more simplified and performant.

When using SnapToNearest with specific extents, ensure the parent physics object is not marked as const.

physics: StretchingSheetPhysics(
  parent: SnappingSheetPhysics(
    snappingBehavior: SnapToNearest(
      snapTo: [
        const Extent.proportional(0.2),
        const Extent.proportional(0.5),
        const Extent.proportional(1),
      ],
    ),
  ),
),

In version 0.8.0 and later, StretchingSheetPhysics was renamed to BouncingSheetPhysics to more accurately describe its behavior (allowing the sheet position to exceed content bounds without resizing the sheet). All related classes and properties were renamed accordingly. To migrate, replace any usage of StretchingSheetPhysics with BouncingSheetPhysics and update the configuration of the bounce range.

// BEFORE (0.7.x)
const physics = StretchingSheetPhysics(
  stretchingRange: Extent.proportional(0.1),
);

// AFTER (0.8.x+)
const physics = BouncingSheetPhysics(
  behavior: FixedBouncingBehavior(Extent.proportional(0.1)),
);

To learn how to use smooth_sheets, refer to the following resources in the repository:

• Tutorials: For basic usage of core components, see example/lib/tutorial/.
• Showcases: For practical, real-world implementations, see example/lib/showcase/.
• API Documentation: For full technical details, visit the official pub.dev documentation.