flutter
/

Flutter BoxDecoration – Complete Guide with Examples

Last Sync: Today

On this page

12
0%
5 min read
Remaining
5 minleft

Click any section to jump — progress syncs automatically

flutter

Flutter BoxDecoration – Complete Guide with Examples

What is BoxDecoration?

BoxDecoration is a class that describes how to paint a box. It is used as the decoration property of Container and DecoratedBox, and it can define background color, border, border radius, shadow, gradient, and background image. Mastering BoxDecoration is essential for creating custom, visually rich UI components in Flutter.

Basic Usage

DARTRead-only
1
Container(
  width: 200,
  height: 200,
  decoration: BoxDecoration(
    color: Colors.blue,
    borderRadius: BorderRadius.circular(16),
  ),
)

This creates a blue square with rounded corners. You can combine multiple properties to achieve complex styles.

Key Properties of BoxDecoration

    • color: Background color (cannot be used together with gradient).
    • gradient: A Gradient (linear, radial, sweep) – overrides color.
    • borderRadius: Rounds the corners (use BorderRadius.circular, .only, etc.).
    • border: A BoxBorder (usually Border.all or custom Border).
    • boxShadow: A list of BoxShadow objects for drop shadows.
    • shape: BoxShape.circle or BoxShape.rectangle (default).
    • image: A DecorationImage to display a background image.
    • backgroundBlendMode: Blend mode for the background (if both color/image/gradient).

Color and Gradient

You can set a solid background color, or a gradient. Note that color and gradient cannot both be set; use one or the other. For gradient, you can use LinearGradient, RadialGradient, or SweepGradient.

DARTRead-only
1
// Solid color
BoxDecoration(color: Colors.red)

// Linear gradient
BoxDecoration(
  gradient: LinearGradient(
    colors: [Colors.red, Colors.blue],
    begin: Alignment.topLeft,
    end: Alignment.bottomRight,
  ),
)

Border and BorderRadius

Add a border using border. For rounded borders, combine with borderRadius. You can create custom borders using Border with individual sides.

DARTRead-only
1
// All sides, 2px red border
BoxDecoration(
  border: Border.all(color: Colors.red, width: 2),
  borderRadius: BorderRadius.circular(12),
)

// Custom border: top and bottom only
BoxDecoration(
  border: Border(
    top: BorderSide(color: Colors.grey, width: 1),
    bottom: BorderSide(color: Colors.grey, width: 1),
  ),
)

BoxShadow – Drop Shadows

boxShadow takes a list of BoxShadow objects. Each shadow can have its own color, blur radius, spread, and offset. Multiple shadows can be stacked.

DARTRead-only
1
BoxDecoration(
  boxShadow: [
    BoxShadow(
      color: Colors.grey.withOpacity(0.5),
      spreadRadius: 2,
      blurRadius: 5,
      offset: Offset(0, 3),
    ),
    BoxShadow(
      color: Colors.blue.withOpacity(0.2),
      spreadRadius: 1,
      blurRadius: 10,
      offset: Offset(0, 0),
    ),
  ],
)

Shape – Circle vs Rectangle

By default, the shape is BoxShape.rectangle. Set it to BoxShape.circle to make the decoration a perfect circle. When using circle, borderRadius is ignored and the box is clipped to a circle based on the size of the widget.

DARTRead-only
1
Container(
  width: 100,
  height: 100,
  decoration: BoxDecoration(
    shape: BoxShape.circle,
    color: Colors.blue,
  ),
)

DecorationImage – Background Image

Use image to set a background image. It takes a DecorationImage which wraps an ImageProvider. You can also set fit, alignment, repeat, and colorFilter.

DARTRead-only
1
BoxDecoration(
  image: DecorationImage(
    image: NetworkImage('https://example.com/image.jpg'),
    fit: BoxFit.cover,
    colorFilter: ColorFilter.mode(Colors.black.withOpacity(0.4), BlendMode.darken),
  ),
)

Combining Multiple Effects

You can combine many of these properties. For example, a card with a gradient background, a shadow, rounded corners, and a border.

DARTRead-only
1
BoxDecoration(
  gradient: LinearGradient(
    colors: [Colors.purple, Colors.pink],
  ),
  borderRadius: BorderRadius.circular(20),
  border: Border.all(color: Colors.white, width: 2),
  boxShadow: [
    BoxShadow(
      color: Colors.black26,
      blurRadius: 10,
      offset: Offset(0, 5),
    ),
  ],
)

Common Mistakes

    • Using both color and gradient: They are mutually exclusive; if you set both, only the gradient will be used (and a warning may appear). Use only one.
    • Forgetting width and height: When using shape: BoxShape.circle, ensure the widget has explicit dimensions (width/height) or is constrained; otherwise, the circle may not appear.
    • Misusing borderRadius with BoxShape.circle: borderRadius is ignored when shape is circle. Use shape: BoxShape.circle directly.
    • Not using const: If the decoration is static, mark it as const to improve performance.
    • Applying decoration without a Container or DecoratedBox: The decoration property is not available on all widgets; use Container or DecoratedBox.

Best Practices

    • Use const for decorations that don't change to reduce rebuilds.
    • Define reusable decorations as constants or static variables.
    • When using images, pre‑cache them for smoother loading.
    • Combine boxShadow and borderRadius for modern card designs.
    • Test with different background colors to ensure contrast.

Key Takeaways

    • BoxDecoration is used to style the background, border, shadow, and shape of a box.
    • It can be applied via Container or DecoratedBox.
  • -Properties include color, gradient, borderRadius, border, boxShadow, shape, image, and backgroundBlendMode.
    • Use BoxShape.circle for circular containers.
    • Combine multiple shadows for rich depth.
    • Always respect the constraints of the parent widget when using shapes and images.

Try it yourself

import 'package:flutter/material.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('BoxDecoration Demo')),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Container(
                width: 150,
                height: 150,
                decoration: BoxDecoration(
                  gradient: LinearGradient(
                    colors: [Colors.orange, Colors.pink],
                    begin: Alignment.topLeft,
                    end: Alignment.bottomRight,
                  ),
                  borderRadius: BorderRadius.circular(20),
                  boxShadow: [
                    BoxShadow(
                      color: Colors.black26,
                      blurRadius: 10,
                      offset: Offset(0, 5),
                    ),
                  ],
                ),
                child: Center(
                  child: Text(
                    'Card',
                    style: TextStyle(color: Colors.white, fontSize: 20),
                  ),
                ),
              ),
              SizedBox(height: 20),
              Container(
                width: 100,
                height: 100,
                decoration: BoxDecoration(
                  shape: BoxShape.circle,
                  color: Colors.blue,
                  boxShadow: [
                    BoxShadow(
                      color: Colors.blue.withOpacity(0.5),
                      blurRadius: 8,
                      spreadRadius: 2,
                    ),
                  ],
                ),
                child: Center(
                  child: Text(
                    'Circle',
                    style: TextStyle(color: Colors.white),
                  ),
                ),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

Test Your Knowledge

Q1
of 4

Which property of BoxDecoration cannot be used together with `gradient`?

A
borderRadius
B
color
C
boxShadow
D
shape
Q2
of 4

How do you create a circular container with a background image?

A
Set `borderRadius: BorderRadius.circular(1000)`
B
Set `shape: BoxShape.circle` and `image` in BoxDecoration
C
Use `ClipOval` with a Container
D
Both B and C are valid
Q3
of 4

What is the purpose of `boxShadow`?

A
To add a shadow to the text
B
To add a shadow to the box
C
To add a glow effect
D
To create a gradient
Q4
of 4

How do you apply a background image that covers the entire box?

A
`image: DecorationImage(image: ..., fit: BoxFit.cover)`
B
`backgroundImage: ...`
C
`decorationImage: ...`
D
`child: Image.asset(...)`

Frequently Asked Questions

Can I animate a BoxDecoration?

Yes, you can animate BoxDecoration properties using AnimatedContainer or ImplicitlyAnimatedWidget. For more complex animations, use Tween<BoxDecoration> with an AnimationController.

How do I create a dashed border?

Flutter does not have a built‑in dashed border in BoxDecoration. You can achieve it by using a custom CustomPainter or using a Container with a Border and a Paint with a dash pattern. For simple needs, you can also use a Container with a ColoredBox background and a Stack with a CustomPaint for the border.

What is the difference between `BoxDecoration` and `ShapeDecoration`?

BoxDecoration is for rectangular/circular boxes and can contain a background image. ShapeDecoration is a more generic class that can draw any shape defined by a ShapeBorder. It is often used with Material or Container to create custom shapes (like a star or arrow). For most styling needs, BoxDecoration is sufficient.

Can I set a gradient on a circular shape?

Yes, you can. Use shape: BoxShape.circle together with gradient. The gradient will fill the entire circle.

How do I make the background image repeat?

Set repeat in DecorationImage: repeat: ImageRepeat.repeat or ImageRepeat.repeatX / ImageRepeat.repeatY. The image will tile to fill the area.

Previous

flutter richtext

Next

flutter border radius

Related Content

Need help?

Explore our comprehensive docs or start a chat with our tech experts.