Box - The Styled Container

Box is a versatile and robust widget, designed to streamline and enrich the styling process in Flutter. This widget is similar to Flutter's native Container, but it incorporates the advanced capabilities of the Mix styling system, offering a more nuanced and flexible approach to design.

Usage

Using Box is straightforward and efficient. You simply wrap your desired child widget with Box, and specify its styling through a Style object.

Box(
  style: Style(
    $box.color.blue(),
    $box.borderRadius.all(8),
    $box.padding.vertical(20),
    $box.elevation(2),
  ),
  child: Text('Styled Box'),
);

In this example, Box adeptly applies a series of styles – a blue background, uniformly rounded corners, consistent vertical padding, and subtle elevation – to the enclosed Text widget.

Composition and Decoration

Mix excels in the composability of styles. Utilizing modifiers such as scale, opacity, and rotate, you can add rich visual effects to your widgets, often with just a single line of code.

Box(
  style: Style(
    $with.scale(1.2),
    $with.opacity(0.75),
    $with.rotate(45),
  ),
  child: Icon(Icons.star),
);

Utilities

The Box widget accepts a range of intuitive utilities, enhancing the ease of styling it. These utilities, functioning as style attribute builders, offer a streamlined approach to crafting intricate styles with minimal code. They cover a broad spectrum of styling aspects such as constraints, colors, and spacing, facilitating complex customizations and maintaining a cohesive design language across your application.

General

You can find all the Box utilities under the $box utility. With this, you can easily find all the utilities in one place, which can be helpful when wanting to have better control over the types. However, you can find some aliases for them to simplify the usage.

Constraints

$box.width: Sets the width of the box.
$box.height: Sets the height of the box.
$box.maxWidth: Sets the maximum width the box can have.
$box.minWidth: Sets the minimum width the box must have.
$box.maxHeight: Sets the maximum height the box can have.
$box.minHeight: Sets the minimum height the box must have.

Spacing

There are a few utilities that make use of the SpacingUtility, like padding and margin. These utilities allow you to specify spacing in a variety of ways, including shorthand notation, individual sides, and horizontal and vertical axes.

`$box.padding`

Padding creates space between the box's content and its border.

Shorthand

Allows quick, concise spacing definitions. The order and number of values dictate their mapping to the box sides.

// Uniform padding of 10 units on all sides.
$box.padding(10)
// 10 units vertical (top and bottom), 20 units horizontal (left and right).
$box.padding(10, 20)
// 10 units top, 20 units horizontal, 30 units bottom.
$box.padding(10, 20, 30)
// 10 units top, 20 units right, 30 units bottom, 40 units left.
$box.padding(10, 20, 30, 40)

Remember that you can always pass design tokens as values using the $space syntax. Read more about design tokens here.

The shorthand methods simplify the code, making it more readable and easier to write, while maintaining the versatile and powerful features that Mix provides.

Uniform Sides

Apply equal padding to all sides of the box.

$box.padding.all(8);

Individual Sides

There are two ways to set individual side padding: direct method naming or the only method.

Using side name method

$box.padding.top(8);
$box.padding.bottom(8);
$box.padding.left(8);
$box.padding.right(8);
$box.padding.start(8);
$box.padding.end(8);
 
$box.padding.only(left: 10, right: 10)

This approach is important because it also allows you easy access to design tokens for padding. For example, if you want to use the small design token for padding, you can do so like this:

$box.padding.top.small();

Using only method

Apply padding to specific sides of the box. You can specify which sides to apply padding to by passing the corresponding parameters. You can also specify directional values like start and end for left and right padding.

$box.padding.only(
  top: 16,
  bottom: 16,
  left: 8, // or start: 8,
  right: 8, // or end: 8,
);

Horizontal and Vertical

Define padding along horizontal or vertical axes.

$box.padding.horizontal(8);
$box.padding.vertical(8);

`$box.margin`

Margin controls the outer space of the Box. Mix provides a variety of options for defining margins.

Shorthand

Allows quick, concise spacing definitions. The order and number of values dictate their mapping to the box sides.

// Applies a uniform margin of 10 units on all sides.
$box.margin(10)
// 10 units on top and bottom, 20 units on left and right sides.
$box.margin(10, 20)
// 10 units top, 20 units horizontal, 30 units bottom.
$box.margin(10, 20, 30)
// 10 units top, 20 units right, 30 units bottom, 40 units left.
$box.margin(10, 20, 30, 40)

Shorthand methods make the code concise and readable, retaining the powerful customization options.

Uniform Sides

Set an equal margin to all sides:

$box.margin.all(8);

Individual Sides

There are two ways to set individual side margin: direct method naming or the only method.

Using side name method

$box.margin.top(8);
$box.margin.bottom(8);
$box.margin.left(8);
$box.margin.right(8);
$box.margin.start(8);
$box.margin.end(8);
 
$box.margin.only(left: 10, right: 10),

Access design tokens directly for margin, enhancing the ability to maintain consistent spacing throughout your app:

$box.margin.top.small();

Using only method

Specify margins for individual sides:

$box.margin.only(
  top: 16,
  bottom: 16,
  left: 8, // or start: 8,
  right: 8, // or end: 8,
);

Horizontal and Vertical

Define padding along horizontal or vertical axes.

$box.margin.horizontal(8);
$box.margin.vertical(8);

Decoration

`$box.border`

The border utility enables you to define the border styling for a Box widget. Through the use of BoxBorderUtility, developers can add precision and clarity in laying out borders on their UI components.

Uniform Border

Apply a border with equal style, width, and color on all four sides.

// Solid red border of 2 logical pixels on all sides.
$box.border(
  color: Colors.red,
  width: 2,
  style: BorderStyle.solid,
  strokeAlign: 0.5,
)
 
// You can also use the .all method, which allows you a few benefits in syntax.
$box.border.all(
  color: Colors.red,
  width: 2,
  style: BorderStyle.solid,
  strokeAlign: 0.5,
)
 
// You can also call directly its parameters like
$box.border.all.color.red();
$box.border.all.width(2);
$box.border.all.style.solid();
$box.border.all.strokeAlign(0.5);

Individual Sides

Apply borders to individual sides. This allows you to set different colors, widths, or styles for each side.

// Red border on the top side only.
$box.border.top(
  color: Colors.red,
  width: 2,
  style: BorderStyle.solid,
  strokeAlign: 0.5,
);
// or border.bottom, border.left, border.right, border.start and border.end

Using individual sides border also allow you access parameter specific utilities.

$box.border.top.color.red();
$box.border.top.width(2);
$box.border.top.style.solid();
$box.border.top.strokeAlign(0.5);

Horizontal and Vertical

Apply border to either the horizontal or vertical sides of a Box. Useful for creating a border only on the top and bottom or on the sides.

// Borders on the left and right sides.
$box.border.horizontal(
  color: Colors.green,
  width: 1,
  style: BorderStyle.solid,
);
// or $box.border.vertical
 
// You can also use the .horizontal and .vertical methods, which allows you a few benefits in syntax.
$box.border.horizontal.color.green();

`$box.borderRadius`

The borderRadius utility is used for setting the border radius of UI elements in a Flutter application. This utility helps in defining how rounded the corners of an element should be, and it simplifies the application of border radius to widgets.

By providing a BorderRadiusGeometryUtility, this enables customization of each corner’s radius, offering a powerful and intuitive utility.

Utility API

Most methods of the borderRadius return a RadiusUtility, that allow more control over the radius.

// The callable method withing the RadiusUtility defaults a circular radius.
$box.borderRadius.all(10.0);
 
// But you can also use other methods
$box.borderRadius.all.circular(10.0);
 
// Allows to set x and y coordinates for the radius.
$box.borderRadius.all.elliptical(10.0, 8.0);
 
// Sets the radius to Radius.zero
$box.borderRadius.all.zero();

Uniform Border Radius

Sets a uniform radius for all corners:

// Sets a border radius of 10 logical pixels for all corners.
$box.borderRadius.all(10.0);

Individual Corners

Specify the radius of individual corners, returning a BorderSideUtility for each corner:

// Sets a radius to bottomLeft corner.
$box.borderRadius.bottomLeft(10.0);
 
// Sets a radius to topLeft corner.
$box.borderRadius.topRight(10.0);

Also use the same for directional corners:

// Sets a radius to topStart corner.
$box.borderRadius.topStart(10.0);
 
// Sets a radius to bottomEnd corner.
$box.borderRadius.bottomEnd(10.0);
 
// Sets a radius to topEnd corner.
$box.borderRadius.topEnd(10.0);
 
// Sets a radius to bottomStart corner.
$box.borderRadius.bottomStart(10.0);

Specific Pairs or Axes

Convenient methods are provided for setting border radius to specific pairs of corners or axes:

// Sets radius of topLeft and topRight corners.
$box.borderRadius.top(10.0);
 
// Sets radius of topLeft and bottomLeft corners.
$box.borderRadius.left(10.0);
 
// Sets radius of topRight and bottomRight corners.
$box.borderRadius.right(10.0);
 
// Sets radius of bottomLeft and bottomRight corners.
$box.borderRadius.bottom(10.0);

$box.color: Sets the background color of the box.
$box.elevation: Sets the elevation of the box.

Alignment

$box.alignment: Sets the alignment of the box.

ClipBehavior

$box.clipBehavior: Sets the clip behavior of the box.

Introduction PressableBox