Module 15: Custom Widgets -- Building Your Own Lego Bricks

Why Build Custom Widgets?

Think about every time you have copied and pasted a chunk of widget code from one screen to another, then tweaked a color or swapped an icon. That is the exact moment you should have been building a custom widget instead.

Three reasons custom widgets matter:

DRY (Don't Repeat Yourself). When the same card layout appears in three screens, a single CustomInfoCard widget means one place to fix bugs and one place to update the design.

Testability. A standalone widget with clear inputs and outputs can be widget-tested in isolation. You do not need to spin up the entire app just to verify that a delete button fires its callback.

Readability. Compare these two build methods:

// Before: a wall of nested widgets
Widget build(BuildContext context) {
  return Card(
    child: Padding(
      padding: const EdgeInsets.all(16),
      child: Row(
        children: [
          Icon(Icons.info, color: Colors.blue, size: 32),
          const SizedBox(width: 16),
          Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              Text('Server Status', style: Theme.of(context).textTheme.titleMedium),
              Text('All systems operational'),
            ],
          ),
        ],
      ),
    ),
  );
}

// After: one readable line
Widget build(BuildContext context) {
  return CustomInfoCard(
    title: 'Server Status',
    description: 'All systems operational',
    icon: Icons.info,
  );
}

The second version tells you what it does at a glance. The first version makes you read 15 lines to figure out the same thing.

Custom StatelessWidget Patterns

A custom StatelessWidget is the simplest kind. Its appearance depends entirely on what you pass into the constructor. No internal state, no surprises.

class InfoLabel extends StatelessWidget {
  final String label;
  final String value;

  const InfoLabel({super.key, required this.label, required this.value});

  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        Text('$label: ', style: const TextStyle(fontWeight: FontWeight.bold)),
        Text(value),
      ],
    );
  }
}

Use it like this:

const InfoLabel(label: 'Name', value: 'Campbell')

That is the whole pattern. A class, some final fields, a const constructor, a build method. You will write hundreds of these.

Constructor Parameters for Configuration

The power of custom widgets comes from their constructors. Parameters make a widget flexible without making it complicated.

class ActionCard extends StatelessWidget {
  final String title;
  final String subtitle;
  final IconData icon;
  final Color color;
  final VoidCallback onTap;

  const ActionCard({
    super.key,
    required this.title,
    required this.subtitle,
    required this.icon,
    this.color = Colors.blue,
    required this.onTap,
  });

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: onTap,
      child: Card(
        color: color.withOpacity(0.1),
        child: Padding(
          padding: const EdgeInsets.all(16.0),
          child: Row(
            children: [
              Icon(icon, color: color, size: 32),
              const SizedBox(width: 16),
              Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(title, style: Theme.of(context).textTheme.titleMedium),
                  Text(subtitle, style: Theme.of(context).textTheme.bodySmall),
                ],
              ),
            ],
          ),
        ),
      ),
    );
  }
}

Notice the mix of required and optional parameters. color has a default value of Colors.blue, so callers can omit it when blue is fine. Everything else is required because the card does not make sense without a title, subtitle, icon, and tap handler.

Use nullable types for truly optional features:

final VoidCallback? onTap;     // null means "not tappable"
final Widget? trailing;         // null means "nothing on the right side"

Then conditionally render based on whether the value is null:

if (onTap != null)
  InkWell(onTap: onTap, child: cardContent)
else
  cardContent

Callback Props -- Talking to Your Parents

Widgets communicate upward using callback functions passed as constructor parameters. The child widget calls the function. The parent widget provides the function.

class RatingBar extends StatelessWidget {
  final int rating;
  final ValueChanged<int> onRatingChanged;

  const RatingBar({
    super.key,
    required this.rating,
    required this.onRatingChanged,
  });

  @override
  Widget build(BuildContext context) {
    return Row(
      children: List.generate(5, (index) {
        return IconButton(
          icon: Icon(
            index < rating ? Icons.star : Icons.star_border,
            color: Colors.amber,
          ),
          onPressed: () => onRatingChanged(index + 1),
        );
      }),
    );
  }
}

The parent uses it like this:

RatingBar(
  rating: _currentRating,
  onRatingChanged: (newRating) {
    setState(() => _currentRating = newRating);
  },
)

Common callback types you will use:

• VoidCallback -- no arguments, no return value. For simple "something happened" signals.
• ValueChanged<T> -- takes one argument of type T. For "here is the new value" signals.
• Function(String, int) -- custom signatures when you need multiple arguments.

InkWell for Tap Feedback

When you want a tap effect with a Material ripple, wrap your widget in InkWell instead of GestureDetector:

InkWell(
  onTap: onTap,
  borderRadius: BorderRadius.circular(12),
  child: Padding(
    padding: const EdgeInsets.all(16),
    child: Text('Tap me for a ripple'),
  ),
)

InkWell gives you the standard Material Design ripple animation. GestureDetector gives you nothing visual -- it just detects the gesture silently. For most card and list item taps, InkWell is the better choice.

Custom StatefulWidget Patterns

Use StatefulWidget when the widget needs to manage internal state that the parent does not care about. The classic example: an expandable card. The parent cares about the card's content. The parent does not care whether the card is currently expanded or collapsed -- that is an internal UI detail.

class ExpandableInfoCard extends StatefulWidget {
  final String title;
  final String description;
  final IconData icon;
  final Widget expandedContent;

  const ExpandableInfoCard({
    super.key,
    required this.title,
    required this.description,
    required this.icon,
    required this.expandedContent,
  });

  @override
  State<ExpandableInfoCard> createState() => _ExpandableInfoCardState();
}

class _ExpandableInfoCardState extends State<ExpandableInfoCard> {
  bool _isExpanded = false;

  @override
  Widget build(BuildContext context) {
    return Card(
      child: InkWell(
        onTap: () => setState(() => _isExpanded = !_isExpanded),
        child: Padding(
          padding: const EdgeInsets.all(16),
          child: Column(
            children: [
              Row(
                children: [
                  Icon(widget.icon, size: 32),
                  const SizedBox(width: 16),
                  Expanded(
                    child: Column(
                      crossAxisAlignment: CrossAxisAlignment.start,
                      children: [
                        Text(widget.title,
                            style: Theme.of(context).textTheme.titleMedium),
                        Text(widget.description),
                      ],
                    ),
                  ),
                  Icon(_isExpanded
                      ? Icons.keyboard_arrow_up
                      : Icons.keyboard_arrow_down),
                ],
              ),
              AnimatedCrossFade(
                duration: const Duration(milliseconds: 300),
                firstChild: const SizedBox.shrink(),
                secondChild: Padding(
                  padding: const EdgeInsets.only(top: 16),
                  child: widget.expandedContent,
                ),
                crossFadeState: _isExpanded
                    ? CrossFadeState.showSecond
                    : CrossFadeState.showFirst,
              ),
            ],
          ),
        ),
      ),
    );
  }
}

Notice how _isExpanded lives in the State class, not in the parent. The parent passes in title, description, icon, and expandedContent through the constructor. The widget handles the expand/collapse toggle on its own.

Widget Composition -- The Big Picture

Build complex UIs by combining smaller custom widgets. Each widget handles its own slice of responsibility.

class ProfileScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        const InfoLabel(label: 'Name', value: 'Alice'),
        const InfoLabel(label: 'Email', value: 'alice@example.com'),
        ActionCard(
          title: 'Edit Profile',
          subtitle: 'Update your information',
          icon: Icons.edit,
          onTap: () {},
        ),
        RatingBar(
          rating: 4,
          onRatingChanged: (r) => print('New rating: $r'),
        ),
      ],
    );
  }
}

Each widget is self-contained. InfoLabel does not know about ActionCard. RatingBar does not know it lives inside a ProfileScreen. They are independent building blocks that happen to be arranged together.

There Are No Dumb Questions

Q: When should I extract a widget into its own file vs. keeping it in the same file?

A: If you use the widget in more than one screen, give it its own file in a widgets/ directory. If it is only used inside one screen and is relatively small, keeping it in the same file is fine. When in doubt, separate it. You will never regret having too many small, focused files.

Q: Should I always use const constructors?

A: Yes, whenever possible. If all your constructor parameters are final and you are not doing any computation in the constructor body, add const. Flutter can optimize const widgets by reusing them instead of rebuilding. Your linter will usually remind you.

Q: What is the difference between VoidCallback and Function()?

A: They are functionally identical. VoidCallback is a typedef defined by Flutter that equals void Function(). Using VoidCallback is more idiomatic and readable in Flutter code.

Q: Can a custom widget have both internal state AND callback props?

A: Absolutely. A SearchBar widget might manage its own TextEditingController internally (StatefulWidget) while exposing an onSearch callback to the parent. Internal state for the UI mechanics, callbacks for the meaningful events.

📝 Module Quiz

Test what you learned. 45 seconds per question. Passing score is set per module. Your best attempt is saved in your browser so you can track progress -- nothing is sent to a server.

Sharpen Your Pencil

Exercise 1: CustomInfoCard

Create a CustomInfoCard StatelessWidget with these parameters:

• title (String, required) -- bold header text
• description (String, required) -- body text below the title
• icon (IconData, required) -- displayed on the left
• iconColor (Color, optional, default Colors.blue)
• onTap (VoidCallback?, optional) -- if provided, wrap the card in an InkWell
• trailing (Widget?, optional) -- displayed on the right side

Layout it as a Card with a ListTile-style arrangement: icon left, title and description stacked in the center, optional trailing widget on the right.

Exercise 2: ExpandableInfoCard

Create an ExpandableInfoCard StatefulWidget that extends the card concept:

• Same parameters as CustomInfoCard plus expandedContent (Widget, required)
• Internal _isExpanded boolean state starting at false
• Tapping toggles expansion with an AnimatedCrossFade or AnimatedSize transition
• Show a chevron icon (down when collapsed, up when expanded) as the trailing widget

Exercise 3: CustomButton

Create a CustomButton StatelessWidget with a ButtonType enum:

enum ButtonType { primary, secondary, danger }

Parameters: label, onPressed, optional icon, required style (ButtonType), optional isLoading (shows a CircularProgressIndicator and disables the button), optional isFullWidth.

Color mapping: primary = blue/white, secondary = grey/black, danger = red/white.

Exercise 4: ContactListItem

Create a ContactListItem StatelessWidget for displaying a contact:

• name and email (required), avatarUrl (optional String), isOnline (bool, default false), onTap and onDelete (both optional)
• Use a CircleAvatar with NetworkImage if avatarUrl is provided, otherwise show the first letter of the name
• Use a Stack to overlay a small green dot on the avatar when isOnline is true
• Conditionally show a delete icon button when onDelete is provided

Exercise 5: Composing a Screen

Build a ContactsScreen that composes all the widgets above into a working screen with a hardcoded list of 5 contacts, add/delete functionality, and at least one ExpandableInfoCard.