flutter
/

Flutter Gradients – Linear, Radial, and Sweep Gradients

Last Sync: Today

On this page

9
0%
5 min read
Remaining
5 minleft

Click any section to jump — progress syncs automatically

flutter

Flutter Gradients – Linear, Radial, and Sweep Gradients

What are Gradients?

Gradients are smooth transitions between two or more colors. In Flutter, gradients are used to add depth and visual interest to UI elements. Flutter provides three types of gradients: LinearGradient (colors transition along a line), RadialGradient (colors transition from a center point outward), and SweepGradient (colors transition around a center point). Gradients are typically applied via BoxDecoration to a Container or DecoratedBox, but can also be used for text, custom painters, and more.

LinearGradient – A Straight Line Transition

LinearGradient creates a gradient along a straight line. You specify a list of colors and optional stops, plus a begin and end Alignment (or FractionalOffset) to define the direction.

DARTRead-only
1
Container(
  width: 200,
  height: 200,
  decoration: BoxDecoration(
    gradient: LinearGradient(
      begin: Alignment.topLeft,
      end: Alignment.bottomRight,
      colors: [Colors.red, Colors.blue],
      // stops: [0.0, 1.0] // optional, defaults to evenly spaced
    ),
  ),
)

You can also use Alignment constants like Alignment.centerLeft, or create custom offsets with Alignment(x, y). For more control, you can use FractionalOffset which ranges from 0.0 to 1.0 in both axes.

RadialGradient – Circular Transition

RadialGradient radiates from a center point. The gradient begins at center and spreads outward to the radius. You can also define focal (a secondary focus point) for a more dramatic effect.

DARTRead-only
1
Container(
  width: 200,
  height: 200,
  decoration: BoxDecoration(
    gradient: RadialGradient(
      center: Alignment.center,
      radius: 0.8,
      colors: [Colors.yellow, Colors.orange, Colors.red],
      stops: [0.0, 0.5, 1.0],
    ),
  ),
)

SweepGradient – Angular Transition

SweepGradient creates a gradient that rotates around a center point, like a color wheel. It's great for loading indicators or circular progress.

DARTRead-only
1
Container(
  width: 200,
  height: 200,
  decoration: BoxDecoration(
    gradient: SweepGradient(
      center: Alignment.center,
      startAngle: 0.0,
      endAngle: 2 * 3.14159, // full circle
      colors: [Colors.red, Colors.orange, Colors.yellow, Colors.green, Colors.blue, Colors.indigo, Colors.purple, Colors.red],
    ),
  ),
)

Applying Gradients to Text

To apply a gradient to text, you can use ShaderMask or RichText with a TextSpan and TextStyle that includes a foreground paint. The ShaderMask approach is simpler for entire text blocks.

DARTRead-only
1
ShaderMask(
  shaderCallback: (bounds) {
    return LinearGradient(
      colors: [Colors.purple, Colors.pink],
      begin: Alignment.topLeft,
      end: Alignment.bottomRight,
    ).createShader(bounds);
  },
  child: const Text(
    'Gradient Text',
    style: TextStyle(fontSize: 48, fontWeight: FontWeight.bold),
  ),
)

Gradients on CustomPaint

For custom shapes, you can use the CustomPaint widget and create a CustomPainter that uses a Paint with a shader created from the gradient. This gives you full control over the drawing area.

DARTRead-only
1
class GradientCirclePainter extends CustomPainter {
  @override
  void paint(Canvas canvas, Size size) {
    final paint = Paint()
      ..shader = LinearGradient(
        colors: [Colors.blue, Colors.green],
        begin: Alignment.topLeft,
        end: Alignment.bottomRight,
      ).createShader(Rect.fromLTWH(0, 0, size.width, size.height));
    canvas.drawCircle(size.center(Offset.zero), size.width / 2, paint);
  }

  @override
  bool shouldRepaint(CustomPainter oldDelegate) => false;
}

CustomPaint(
  size: Size(200, 200),
  painter: GradientCirclePainter(),
)

Common Mistakes

    • Using Colors list with inconsistent stops: If you provide stops, you must provide one stop per color, and they must be in increasing order (0.0 to 1.0).
    • Forgetting BoxDecoration: Gradients can only be applied via BoxDecoration (for containers) or directly via Paint in custom painting; you cannot set gradient directly on a Container without decoration.
    • Mixing Alignment and FractionalOffset: They are different types; use the appropriate one for the property (e.g., begin expects Alignment).
    • Not specifying colors with at least two colors: A gradient needs at least two colors; otherwise it's just a solid color.
    • Applying gradient to text without ShaderMask: Directly setting gradient on TextStyle is not supported; use ShaderMask or RichText.

Best Practices

    • For smooth transitions, use colors with similar brightness or a gradient from a color scheme library.
    • Use const for gradient definitions that don't change to improve performance.
    • Precompute gradients that are reused across multiple widgets to avoid unnecessary allocations.
    • When applying gradients to text, ensure the text remains readable – use high contrast or darken the gradient beneath.
    • Test gradients on different background colors to ensure visibility.

Key Takeaways

    • Use LinearGradient for straight line transitions.
    • Use RadialGradient for circular transitions.
    • Use SweepGradient for angular transitions (like color wheels).
    • Gradients are applied through BoxDecoration (for containers) or through Paint shaders (for custom drawing).
    • For text, wrap the text in ShaderMask with a gradient shader.
    • Provide stops for fine control over color placement.

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('Gradients Demo')),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Container(
                width: 150,
                height: 150,
                decoration: BoxDecoration(
                  gradient: LinearGradient(
                    colors: [Colors.purple, Colors.orange],
                    begin: Alignment.topLeft,
                    end: Alignment.bottomRight,
                  ),
                ),
              ),
              SizedBox(height: 20),
              Container(
                width: 150,
                height: 150,
                decoration: BoxDecoration(
                  gradient: RadialGradient(
                    colors: [Colors.yellow, Colors.red],
                    radius: 0.8,
                  ),
                ),
              ),
              SizedBox(height: 20),
              ShaderMask(
                shaderCallback: (bounds) => LinearGradient(
                  colors: [Colors.green, Colors.blue],
                  begin: Alignment.topLeft,
                  end: Alignment.bottomRight,
                ).createShader(bounds),
                child: Text(
                  'Gradient Text',
                  style: TextStyle(fontSize: 32, fontWeight: FontWeight.bold, color: Colors.white),
                ),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

Test Your Knowledge

Q1
of 4

Which class is used to define a gradient that transitions along a straight line?

A
LinearGradient
B
RadialGradient
C
SweepGradient
D
Gradient
Q2
of 4

How do you apply a gradient to a Container?

A
Directly via the `gradient` property
B
Inside a `BoxDecoration` in the `decoration` property
C
Using `Container.gradient`
D
By wrapping with a `Gradient` widget
Q3
of 4

What widget is commonly used to apply a gradient to text?

A
GradientText
B
ShaderMask
C
TextGradient
D
TextShader
Q4
of 4

What does `stops` in a gradient define?

A
The direction of the gradient
B
The positions where each color starts
C
The radius of the gradient
D
The number of colors

Frequently Asked Questions

Can I apply a gradient to an image?

Yes, you can stack a Container with a gradient on top of an image using a Stack, or you can use DecoratedBox to combine the image and gradient. For example: Stack(children: [Image.asset(...), Container(decoration: BoxDecoration(gradient: ...))]).

How do I make a gradient repeat?

Flutter's built‑in gradients do not repeat automatically. You can simulate repetition by using a CustomPainter that tiles the gradient, or use a Shader with TileMode.repeated when creating a shader manually. For simple cases, you might use a larger gradient area with Alignment outside the bounds.

What is the difference between `Alignment` and `FractionalOffset`?

Both represent a point relative to a rectangle. Alignment uses coordinates where (-1, -1) is top‑left, (1, 1) is bottom‑right, and (0, 0) is center. FractionalOffset uses coordinates where (0, 0) is top‑left, (1, 1) is bottom‑right. Some gradient properties use Alignment, others use FractionalOffset. Always check the property's type.

How do I create a gradient border?

You can achieve a gradient border by using a Container with a gradient as the background, and then another Container with a solid color as the child, leaving a small gap (border). Or use a CustomPainter to draw the border with a gradient stroke. A simpler method is to use BoxDecoration with gradient and a border of Border.all – but the border will be a solid color, not gradient. For gradient borders, custom painting is the most flexible.

Can I animate a gradient?

Yes, you can animate the begin, end, colors, or stops by using an AnimationController and rebuilding a widget that contains the gradient. Wrap the gradient in an AnimatedBuilder and update the values.

Previous

flutter border radius

Next

flutter named routes

Related Content

Need help?

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