collapsible 1.0.0

A widget that implicitly collapses and expands around its child by clipping it.

collapsible

A widget that implicitly collapses and expands around its child by clipping it.

Usage

import 'package:collapsible/collapsible.dart';

[Collapsible] has three required parameters: [child], [collapsed], and [axis].

[child] provides the widget [Collapsible] wraps, while [collapsed] defines the current state, whether its collapsed or not, and [axis] specifies whether the collapsing/expanding animation should transition horizontally, vertically, or along both axes.

/// When updated to `false` the [Collapsible] will expand, revealing its
/// child, and will collapse, hiding the child if set back to `true`.
var _collapsed = true;

/// A [Collapsible] built with its default parameters.
Collapsible(
  collapsed: _collapsed,
  axis: CollapsibleAxis.both,
  child: MyWidget(),
);

Alignment

Depending on the [axis] of the transition and the [Collapsible]'s placement within its parent, you'll likely want to change the [alignment] of the [child] to match that of the [Collapsible]'s alignment within its parent.

/// When collapsing vertically and the [Collapsible] is aligned to
/// the top edge of its parent, the [child] will look best if aligned
/// to the top-center of the [Collapsible].
Collapsible(
  collapsed: _collapsed,
  axis: CollapsibleAxis.vertical,
  alignment: Alignment.topCenter,
  child: MyWidget(),
);

Restricting the Size

The minimum width and height the [Collapsible] will collapse to can be provided as factors that the [child]'s size will be multiplied by.

Specifying a minimum width/height factor can be a good idea if you want to clip only a part of the [child] or if you'd like the child to continue occupying space within its parent when collapsed.

/// A [Collapsible] that collapses to 20% of the width and 40% of the
/// height of its child.
Collapsible(
  collapsed: _collapsed,
  axis: CollapsibleAxis.both,
  minWidthFactor: 0.2,
  minHeightFactor: 0.4,
  child: MyWidget(),
);

Fading

[Collapsible] has a parameter, [fade], that if set to true, will wrap the [child] with an [AnimatedOpacity] widget, which will fade the child in/out as the [Collapsible] expands/collapses.

The minimum opacity the [child] should fade to can be specified with the [minOpacity] parameter, which defaults to 0.0 (0%).

/// A [Collapsible] that fades its child in/out as it expands/collapses,
/// fading it out to 20% opacity.
Collapsible(
  collapsed: _collapsed,
  axis: CollapsibleAxis.horizontal,
  fade: true,
  minOpacity: 0.2,
  child: MyWidget(),
);

Curve

An easing curve can be applied to the animation with the [curve] parameter, the curve will also be applied to the fading animation if [fade] is true.

[curve] defaults to Curves.easeOut.

/// A [Collapsible] whose animations start slowly then speed up.
Collapsible(
  collapsed: _collapsed,
  axis: CollapsibleAxis.both,
  curve: Curves.easeIn,
  fade: true,
  child: MyWidget(),
);

Duration

The [duration] of the animation can also be provided, which defaults to 240ms.

/// A [Collapsible] that takes 1 second to expand/collapse around its child.
Collapsible(
  collapsed: _collapsed,
  axis: CollapsibleAxis.both,
  duration: Duration(seconds: 1),
  child: MyWidget(),
);

Depending on the [curve] you may want to provide a different duration for the collapsing and expanding animations for a smoother appearance.

/// A [Collapsible] that takes 240ms to collapse and 360ms to expand.
Collapsible(
  collapsed: _collapsed,
  axis: CollapsibleAxis.both,
  duration: Duration(milliseconds: _collapsed ? 240 : 360),
  child: MyWidget(),
);

State Management

MaintainState

With the default settings, the [Collapsible] will replace the [child] with a SizedBox.shrink() to free up the resources used by the [child]. This means every time the [child] is revealed it will be built from a fresh state.

To prevent this, [maintainState] can be set to true, which will tell the [Collapsible] to build the [child] once and keep it built.

/// A [Collapsible] that maintains the state of its child when the
/// child is hidden.
Collapsible(
  collapsed: _collapsed,
  axis: CollapsibleAxis.both,
  maintainState: true,
  child: MyWidget(),
);

[maintainState] will automatically be set to true if the [child] still occupies any space when the [Collapsible] is in its collapsed space. This occurs when [minWidthFactor] or [minHeightFactor] are greater than 0.0 and the transition occurs along the horizontal or vertical axes respectively.

MaintainAnimation

By default, the [Collapsible] will stop any of the childs', or its sub-trees', animation tickers when in the collapsed state. [maintainAnimation] can be set to true to keep them running.

/// A [Collapsible] that maintains the animations of its child when collapsed.
Collapsible(
  collapsed: _collapsed,
  axis: CollapsibleAxis.both,
  maintainAnimation: true,
  child: MyWidget(),
);

Setting [maintainAnimation] to true will automatically set [maintainState] to true, but unlike [maintainState], [maintainAnimation] will remain false even if part of the child is still in view when collapsed, it must be set to true to keep the tickers active.