Skip to main content

resizable_columns 0.2.1 copy "resizable_columns: ^0.2.1" to clipboard
resizable_columns: ^0.2.1 copied to clipboard

A Flutter widget that lays out panes in a row or a column with draggable dividers. Supports nesting, minimum sizes, pushing neighbouring panes and right-to-left layouts.

resizable_columns #

pub package

A Flutter widget for the layouts of desktop and web tools - an editor next to a live preview, a sidebar, a document and an inspector, a code pane over a console - where the user drags the borders between panes and folds away the ones they do not need right now.

Row with Expanded gives fixed shares, and a draggable split is usually two panes, a hand-written GestureDetector and a pile of edge cases: a pane squeezed to nothing, a divider that drifts off the pointer, sizes that jump when the window is resized, a layout that cannot be saved. This widget handles any number of panes, keeps them above a minimum, keeps their proportions when the window changes, and collapses a pane to nothing or to a rail of icons and brings it back at the size it had.

Features #

  • Any number of panes - in a row or a column, nested for grids, with a draggable divider between every two.
  • Collapsible panes - a controller folds a pane to nothing or to a narrow rail and expands it back to exactly the size it had; the toolbar button that opens a chat or an inspector is one toggle call.
  • Never too small - a pane does not shrink below its minimum while the space allows it; in push mode a divider goes on past a pane at its minimum and shrinks the panes behind it.
  • Steady under resizing - panes keep their proportions when the window grows or shrinks, and the divider stays under the pointer, right to left included.
  • Saved and restored - onSizesChanged reports every pane's size, initialSizes puts them back, collapsed panes included.
  • Easy to grab, cheap to drag - the drag area is wider than the divider and takes no space; panes are not rebuilt while a divider moves.
  • Desktop and web ready - resize cursors over dividers, transparent or colored dividers of any thickness.
  • No dependencies beyond Flutter itself.

Requirements #

  • Flutter 3.24 or later.
  • Any platform Flutter runs on; the resize cursors matter on desktop and web.

Installation #

dependencies:
  resizable_columns: ^0.2.0
flutter pub get
import 'package:resizable_columns/resizable_columns.dart';

Usage #

Basic example #

Two panes in a horizontal orientation, split equally:

ResizableColumns(
  orientation: ResizableOrientation.horizontal,
  dividerThickness: 8.0,
  minChildSize: 100.0,
  children: [
    (context) => Container(color: Colors.red),
    (context) => Container(color: Colors.blue),
  ],
);

Setting initial proportions #

initialProportions splits the space by share. Here the middle pane starts twice as wide as the others:

ResizableColumns(
  orientation: ResizableOrientation.horizontal,
  dividerThickness: 8.0,
  initialProportions: const [1, 2, 1],
  minChildSize: 100.0,
  children: [
    (context) => Container(color: Colors.red),
    (context) => Container(color: Colors.blue),
    (context) => Container(color: Colors.green),
  ],
);

Nesting #

A pane can hold another ResizableColumns with the other orientation:

ResizableColumns(
  orientation: ResizableOrientation.horizontal,
  children: [
    (context) => Container(color: Colors.red),
    (context) => ResizableColumns(
          orientation: ResizableOrientation.vertical,
          children: [
            (context) => Container(color: Colors.blue),
            (context) => Container(color: Colors.orange),
          ],
        ),
  ],
);

Pushing other panes #

By default a divider stops when the pane next to it reaches minChildSize. With ResizableDragMode.push it keeps going and takes the space from the panes further along, one after another:

ResizableColumns(
  orientation: ResizableOrientation.horizontal,
  minChildSize: 100.0,
  dragMode: ResizableDragMode.push,
  children: [
    (context) => Container(color: Colors.red),
    (context) => Container(color: Colors.blue),
    (context) => Container(color: Colors.green),
  ],
);

Dragging the first divider to the right shrinks the blue pane to 100 and then the green one. Dragging back during the same gesture gives them their space again.

Saving and restoring sizes #

onSizesChanged reports the size of every pane in pixels while a divider is dragged. Keep the last value and pass it back as initialSizes to restore the layout:

ResizableColumns(
  orientation: ResizableOrientation.horizontal,
  initialSizes: savedSizes,
  onSizesChanged: (sizes) => savedSizes = sizes,
  children: [
    (context) => Container(color: Colors.red),
    (context) => Container(color: Colors.blue),
  ],
);

The callback is not called for the initial layout or when the parent is resized. Restored sizes are scaled to the space available, so the layout keeps its proportions in a window of a different size.

Collapsing panes #

A ResizableColumnsController collapses a pane and expands it again. A collapsed pane shrinks to its entry in collapsedSizes (nothing at all without one), and the other panes share the space it leaves in their proportions. Expanding it gives it back exactly the size it had, and the other panes shrink in proportion to make room:

// The editor collapses to a 56 px rail, the chat disappears; the chat starts collapsed.
final controller = ResizableColumnsController(collapsed: {2});

ResizableColumns(
  orientation: ResizableOrientation.horizontal,
  controller: controller,
  collapsedSizes: const [56, 0, 0],
  children: [
    (context) => controller.isCollapsed(0) ? const IconRail() : const Editor(),
    (context) => const Preview(),
    (context) => const Chat(),
  ],
);

// In a toolbar:
IconButton(icon: const Icon(Icons.view_sidebar), onPressed: () => controller.toggle(0));
IconButton(icon: const Icon(Icons.chat), onPressed: () => controller.toggle(2));
  • The builders run again when the set of collapsed panes changes, so a pane can show a rail of icons instead of disappearing.
  • One handle between two expanded panes. The divider right after an expanded pane stays draggable even when collapsed panes follow it, and resizes it and the next expanded pane across them. The other dividers next to a collapsed pane take no drag. Drags, push mode included, move only expanded panes.
  • When the size does not fit on expanding, for example after the parent shrank, the pane gets what is left once each of the others is at minChildSize.
  • Saving and restoring. onSizesChanged reports a collapsed pane with the size it returns to. Pass the list as initialSizes and the same indexes to the controller to restore both the layout and those sizes.

API reference #

ResizableColumns #

A widget that displays multiple resizable child widgets separated by draggable dividers.

const ResizableColumns({
  super.key,
  required this.children,
  required this.orientation,
  this.dividerThickness = 2.0,
  this.dividerColor = const Color(0x00000000),
  this.dividerHitSize = 12.0,
  this.initialProportions,
  this.initialSizes,
  this.draggable = true,
  this.dragMode = ResizableDragMode.adjacent,
  this.alignment = Alignment.topLeft,
  this.minChildSize = 50.0,
  this.onSizesChanged,
  this.controller,
  this.collapsedSizes,
})
Parameter Description
children Functions that build the child widgets. Each one receives a BuildContext.
orientation ResizableOrientation.horizontal or ResizableOrientation.vertical.
dividerThickness The thickness of the dividers between panes.
dividerColor The color of the dividers. Transparent by default.
dividerHitSize The size of the area a divider can be dragged by. Never smaller than dividerThickness.
initialProportions The initial share of the space for each pane. The length must match the number of children.
initialSizes The initial size of each pane in pixels. The length must match the number of children. Cannot be combined with initialProportions.
draggable Whether the dividers can be dragged.
dragMode ResizableDragMode.adjacent stops at the next pane's minimum; ResizableDragMode.push goes on and shrinks the panes further along.
alignment Alignment of each child within its pane.
minChildSize The minimum size a pane can shrink to.
onSizesChanged Called while a divider is dragged, with the size of every pane in pixels. A collapsed pane is reported with the size it returns to.
controller A ResizableColumnsController that collapses and expands panes.
collapsedSizes The size of each pane while it is collapsed. The length must match the number of children; 0 for every pane by default.

Behavior #

  • Sizes are proportions. initialSizes that do not add up to the available space are scaled to fill it, and panes keep their proportions when the parent is resized.
  • The minimum yields when it cannot fit. If the space is smaller than minChildSize times the number of panes, the panes share it equally.
  • The drag area lies over the panes. It is dividerHitSize wide, centered on the divider, and takes no space in the layout. A drag that starts there moves the divider, and a tap still reaches the pane under it.
  • A child gets the constraints of its pane. A child larger than its pane is shrunk to fit. To keep its size and clip it instead, wrap it in ClipRect and OverflowBox, or make it scrollable.
  • Panes are not rebuilt while dragging. The builders run when ResizableColumns itself is rebuilt or when something a pane depends on changes.
  • Initial values are read once. A later change of initialSizes or initialProportions does not move the panes.
  • Changing the number of children resets the sizes to the initial ones.
  • draggable: false removes the drag areas. The dividers are still drawn, but they take no gestures and do not change the mouse cursor.
  • An unbounded parent needs initialSizes. Inside a scroll view along the orientation there is no space to share, so the sizes are taken from initialSizes as they are.

ResizableColumnsController #

A ChangeNotifier that holds the indexes of the collapsed panes: collapse(index), expand(index), toggle(index), setCollapsed(index, collapsed), isCollapsed(index) and collapsed. It notifies only when something changes. An index with no pane behind it is ignored, and a negative one fails an assert in debug builds and is ignored in release builds.

ResizableDragMode #

What a dragged divider does once the pane next to it cannot shrink.

enum ResizableDragMode {
  adjacent,
  push,
}
Value Description
adjacent Only the two panes next to the divider change. The divider stops when one of them reaches minChildSize. This is the default.
push The divider keeps going and takes the space from the panes further along, one after another. Only the pane it moves away from grows.

ResizableOrientation #

The axis along which the panes are laid out and resized.

enum ResizableOrientation {
  vertical,
  horizontal,
}
Value Description
vertical Panes are stacked from top to bottom and resized by height.
horizontal Panes are placed side by side and resized by width.

Example #

The example app shows four columns with different content: a fixed-size box, a nested vertical layout with scrolling lists, a fixed-width list, and a child larger than its pane. The outer row uses ResizableDragMode.push, the nested layout the default mode. Run it in Chrome:

cd example
flutter run -d chrome

Contributing #

Contributions are welcome! If you encounter any issues or have suggestions for improvements, please open an issue or submit a pull request on GitHub.

License #

This project is licensed under the MIT License - see the LICENSE file for details.

9
likes
160
points
1.18k
downloads

Documentation

API reference

Publisher

verified publisherserdun.online

Weekly Downloads

A Flutter widget that lays out panes in a row or a column with draggable dividers. Supports nesting, minimum sizes, pushing neighbouring panes and right-to-left layouts.

Repository (GitHub)
View/report issues

Topics

#layout #split-view #resizable #panels #desktop

License

MIT (license)

Dependencies

flutter

More

Packages that depend on resizable_columns