pretty_duration

A small Dart utility to format Duration objects into human-readable strings.

Simple, zero-dependency, and null-safe.
Supports short (1h 30m) and verbose (1 hour 30 minutes) formats.
Skips zero-value units by default for clean output.
Supports selecting specific units and cascading larger units into smaller ones.

Features

Format Duration to short or verbose strings.
Automatically skips zero-value units by default.
Select which units to include using the units parameter.
Optionally cascade larger units into smaller selected units using cascade.
Returns "0{unit}" / "0 {unit}" if the duration is empty, customizable via emptyText.
Fully null-safe and Dart 3 compatible.

Installation

Add this to your pubspec.yaml:

dependencies:
  pretty_duration: ^1.0.0

Then run:

dart pub get

Usage

import 'package:pretty_duration/pretty_duration.dart';

void main() {
  final d = Duration(days: 1, hours: 2, minutes: 5, seconds: 0);

  // Default behavior (skipEmpty: true) with all units
  print(prettyDuration(d));
  // Output: "1d 2h 5m"

  // Keep zero-value units (skipEmpty: false)
  print(prettyDuration(d, skipEmpty: false));
  // Output: "1d 2h 5m 0s"

  // Verbose output, skipEmpty: true
  print(prettyDuration(d, verbose: true));
  // Output: "1 day 2 hours 5 minutes"

  // Verbose output, skipEmpty: false
  print(prettyDuration(d, verbose: true, skipEmpty: false));
  // Output: "1 day 2 hours 5 minutes 0 seconds"

  // Only show hours and minutes
  print(prettyDuration(d, units: [DurationUnit.hours, DurationUnit.minutes]));
  // Output: "2h 5m"

  // Only show hours and minutes with cascade
  print(prettyDuration(d,
      units: [DurationUnit.hours, DurationUnit.minutes], cascade: true));
  // Output: "26h 5m"

  // Only show hours and seconds with cascade
  print(prettyDuration(d,
      units: [DurationUnit.hours, DurationUnit.seconds], cascade: true));
  // Output: "26h 300s"

  // Custom empty text
  print(prettyDuration(Duration.zero, emptyText: "none"));
  // Output: "none"

  // Verbose, only seconds, zero duration
  print(prettyDuration(Duration.zero,
      verbose: true, units: [DurationUnit.seconds]));
  // Output: "0 seconds"
}

API

`String prettyDuration(Duration duration, {bool verbose = false, bool skipEmpty = true, List<DurationUnit>? units, bool cascade = false, String? emptyText})`

duration: The Duration to format.
verbose: If true, uses full words ("2 hours 5 minutes").
skipEmpty: If true (default), removes units with value 0.
units: Optional list of DurationUnit to include (default: all units).
cascade: If true, converts each larger unit into the next smaller unit in units.
emptyText: Optional text to use when the duration is zero.

Returns a human-readable string representing the duration.

Example Output

Duration	Default	Verbose	Skip Empty: false
`Duration(hours: 1, minutes: 30)`	`1h 30m`	`1 hour 30 minutes`	`0d 1h 30m 0s`
`Duration(seconds: 45)`	`45s`	`45 seconds`	`0d 0h 0m 45s`
`Duration(days: 1, hours: 2, minutes: 30)`	`1d 2h 30m`	`1 day 2 hours 30 minutes`	`1d 2h 30m 0s`
`Duration.zero`	`0s`	`0 seconds`	`0d 0h 0m 0s`

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.