Flutter Date Kit
A comprehensive Flutter package that provides easy-to-use date formatting and manipulation utilities using the intl package. This package offers a complete toolkit of date formatting methods, extension methods, and utility functions for DateTime objects.
โจ Features
- ๐๏ธ Multiple Date Formats: Support for various date formats including dd/MM/yyyy, yyyy-MM-dd, ISO formats, and more
- โฐ Time Formatting: Format time in 12-hour and 24-hour formats
- ๐ง Extension Methods: Convenient extension methods for DateTime objects
- ๐ฑ Flutter Ready: Built specifically for Flutter applications
- ๐งช Well Tested: Comprehensive test coverage
- ๐ Well Documented: Clear documentation and examples
- โก Performance Optimized: Singleton pattern for better performance
- ๐ก๏ธ Error Handling: Proper error handling for date parsing operations
- ๐ ๏ธ Utility Functions: Date manipulation and validation utilities
๐ Getting started
Add this to your package's pubspec.yaml
file:
dependencies:
flutter_date_kit: ^latest
๐ File Structure
The package is organized into a modular structure for better maintainability:
lib/
โโโ flutter_date_kit.dart # Main entry point (exports all components)
โโโ src/
โโโ date_format_service.dart # DateFormatService class with singleton pattern
โโโ date_time_extensions.dart # DateTime extension methods
โโโ string_date_extensions.dart # String extension methods for date parsing
โโโ date_formats.dart # DateFormat instances and patterns
โโโ date_utils.dart # Utility functions for date operations
This structure provides:
- Better Organization: Each file has a specific responsibility
- Easier Maintenance: Changes to specific functionality are isolated
- Improved Readability: Smaller, focused files are easier to understand
- Better Testing: Individual components can be tested separately
๐ Usage
๐ก Tip: Check out the example app for a comprehensive demonstration of all features with a beautiful UI!
๐ Quick Start: Run
./run_example.sh
to launch the example app directly!
import 'package:flutter_date_kit/flutter_date_kit.dart';
void main() {
// Using the singleton instance (recommended for better performance)
final formatted = DateFormatService.instance.formatToDdMmYyyy(DateTime.now());
print(formatted); // "25/12/2023"
// Or create a new instance (backward compatibility)
final formatter = DateFormatService();
final date = DateTime(2023, 12, 25, 14, 30, 45);
// Basic date formatting
print(formatter.formatToDdMmYyyy(date)); // "25/12/2023"
print(formatter.formatToYyyyMmDd(date)); // "2023-12-25"
print(formatter.formatToShortDate(date)); // "25 Dec 2023"
// Date with time
print(formatter.formatToDateWithTime(date)); // "25 Dec 2023, 2:30 PM"
print(formatter.formatToFullDateTime(date)); // "2023-12-25 14:30:45"
// Time formatting
print(formatter.formatToTime12Hour(date)); // "2:30 PM"
print(formatter.formatToTime24Hour(date)); // "14:30"
// Other formats
print(formatter.formatToDayOfWeek(date)); // "Mon"
print(formatter.formatToMonthYear(date)); // "December 2023"
}
Using Extension Methods (Most Convenient)
import 'package:flutter_date_kit/flutter_date_kit.dart';
void main() {
final date = DateTime(2023, 12, 25, 14, 30, 45);
// Extension methods make formatting even easier
print(date.toDdMmYyyy()); // "25/12/2023"
print(date.toYyyyMmDd()); // "2023-12-25"
print(date.toShortDate()); // "25 Dec 2023"
print(date.toDateWithTime()); // "25 Dec 2023, 2:30 PM"
print(date.toTime12Hour()); // "2:30 PM"
print(date.toTime24Hour()); // "14:30"
print(date.toMonthYear()); // "December 2023"
// Date utility extensions
print(date.isToday); // false
print(date.isYesterday); // false
print(date.isTomorrow); // false
print(date.age); // 0 (if date is today)
print(date.quarter); // 4
print(date.weekOfYear); // 52
// Date manipulation
final tomorrow = date.addDays(1);
final yesterday = date.subtractDays(1);
final daysDiff = date.differenceInDays(DateTime.now());
// Date boundaries
print(date.startOfDay); // 2023-12-25 00:00:00.000
print(date.endOfDay); // 2023-12-25 23:59:59.000
print(date.startOfWeek); // 2023-12-25 00:00:00.000 (Monday)
print(date.endOfWeek); // 2023-12-31 00:00:00.000 (Sunday)
print(date.startOfMonth); // 2023-12-01 00:00:00.000
print(date.endOfMonth); // 2023-12-31 00:00:00.000
}
Using String Date Parsing and Formatting
import 'package:flutter_date_kit/flutter_date_kit.dart';
void main() {
final formatter = DateFormatService.instance;
// Parse yyyy-MM-dd strings and format them
print(formatter.parseAndFormatDdMmYyyy('2023-12-25')); // "25/12/2023"
print(formatter.parseAndFormatShortDate('2023-12-25')); // "25 Dec 2023"
print(formatter.parseAndFormatMonthAbbr('2023-12-25')); // "Dec"
print(formatter.parseAndFormatDayOfWeek('2023-12-25')); // "Mon"
print(formatter.parseAndFormatYear('2023-12-25')); // "2023"
print(formatter.parseAndFormatMonthYear('2023-12-25')); // "December 2023"
// Parse dd/MM/yyyy strings and format them
print(formatter.parseDdMmYyyyAndFormatYyyyMmDd('25/12/2023')); // "2023-12-25"
print(formatter.parseDdMmYyyyAndFormatShortDate('25/12/2023')); // "25 Dec 2023"
print(formatter.parseDdMmYyyyAndFormatMonthAbbr('25/12/2023')); // "Dec"
// Using string extension methods
print('2023-12-25'.parseYyyyMmDdToDdMmYyyy()); // "25/12/2023"
print('2023-12-25'.parseYyyyMmDdToShortDate()); // "25 Dec 2023"
print('2023-12-25'.parseYyyyMmDdToMonthAbbr()); // "Dec"
print('25/12/2023'.parseDdMmYyyyToYyyyMmDd()); // "2023-12-25"
print('25/12/2023'.parseDdMmYyyyToShortDate()); // "25 Dec 2023"
// String validation
print('2023-12-25'.isValidYyyyMmDd); // true
print('25/12/2023'.isValidDdMmYyyy); // true
print('12/25/2023'.isValidMmDdYyyy); // true
print('invalid-date'.isValidYyyyMmDd); // false
}
Using DateUtils for Advanced Operations
import 'package:flutter_date_kit/flutter_date_kit.dart';
void main() {
// Current date and time utilities
print(DateUtils.getCurrentDateDdMmYyyy()); // "25/12/2023"
print(DateUtils.getCurrentDateYyyyMmDd()); // "2023-12-25"
print(DateUtils.getCurrentTime24Hour()); // "14:30"
print(DateUtils.getCurrentTime12Hour()); // "2:30 PM"
// Date validation
print(DateUtils.isValidYyyyMmDd('2023-12-25')); // true
print(DateUtils.isValidDdMmYyyy('25/12/2023')); // true
print(DateUtils.isValidMmDdYyyy('12/25/2023')); // true
// Date manipulation
final date = DateTime(2023, 12, 25);
print(DateUtils.addDays(date, 7)); // 2024-01-01
print(DateUtils.subtractDays(date, 7)); // 2023-12-18
// Date boundaries
print(DateUtils.startOfDay(date)); // 2023-12-25 00:00:00.000
print(DateUtils.endOfDay(date)); // 2023-12-25 23:59:59.000
print(DateUtils.startOfWeek(date)); // 2023-12-25 00:00:00.000 (Monday)
print(DateUtils.endOfWeek(date)); // 2023-12-31 00:00:00.000 (Sunday)
print(DateUtils.startOfMonth(date)); // 2023-12-01 00:00:00.000
print(DateUtils.endOfMonth(date)); // 2023-12-31 00:00:00.000
// Date comparisons
print(DateUtils.isToday(date)); // false
print(DateUtils.isYesterday(date)); // false
print(DateUtils.isTomorrow(date)); // false
// Date differences
final otherDate = DateTime(2023, 12, 30);
print(DateUtils.differenceInDays(otherDate, date)); // 5
print(DateUtils.differenceInHours(otherDate, date)); // 120
print(DateUtils.differenceInMinutes(otherDate, date)); // 7200
// Age calculation
final birthDate = DateTime(1990, 6, 15);
print(DateUtils.getAge(birthDate)); // 33
// Calendar utilities
print(DateUtils.isLeapYear(2024)); // true
print(DateUtils.daysInMonth(2023, 2)); // 28
print(DateUtils.getQuarter(date)); // 4
print(DateUtils.getWeekOfYear(date)); // 52
}
Error Handling
import 'package:flutter_date_kit/flutter_date_kit.dart';
void main() {
try {
// This will throw a FormatException
final result = DateFormatService.instance.parseAndFormatDdMmYyyy('invalid-date');
} catch (e) {
print('Error: $e'); // Error: FormatException: Invalid date format. Expected yyyy-MM-dd, got: invalid-date
}
// Safe validation
if ('2023-12-25'.isValidYyyyMmDd) {
final result = DateFormatService.instance.parseAndFormatDdMmYyyy('2023-12-25');
print(result); // "25/12/2023"
}
}
๐ Available Format Methods
DateFormatService Methods
Method | Format | Example Output |
---|---|---|
formatToDdMmYyyy() |
dd/MM/yyyy | "25/12/2023" |
formatToYyyyMmDd() |
yyyy-MM-dd | "2023-12-25" |
formatToShortDate() |
dd MMM yyyy | "25 Dec 2023" |
formatToDateWithTime() |
dd MMM yyyy, h:mm a | "25 Dec 2023, 2:30 PM" |
formatToFullDateTime() |
yyyy-MM-dd HH:mm:ss | "2023-12-25 14:30:45" |
formatToIsoWithTimezone() |
yyyy-MM-dd'T'HH:mm:ssZ | "2023-12-25T14:30:00+00:00" |
formatToTime12Hour() |
h:mm a | "2:30 PM" |
formatToTime24Hour() |
HH:mm | "14:30" |
formatToFullTime() |
HH:mm:ss | "14:30:45" |
formatToDayOfWeek() |
E | "Mon" |
formatToMonthAbbr() |
MMM | "Dec" |
formatToMonthFull() |
MMMM | "December" |
formatToYear() |
y | "2023" |
formatToMonthYear() |
MMMM yyyy | "December 2023" |
formatToMmDdYyyy() |
MM/dd/yyyy | "12/25/2023" |
formatToFullDayDate() |
EEEE, MMMM d, yyyy | "Monday, December 25, 2023" |
formatToYyyyMmDdHhMm() |
yyyy-MM-dd HH:mm | "2023-12-25 14:30" |
String Parsing Methods (DateFormatService)
Method | Input Format | Output Format | Example |
---|---|---|---|
parseAndFormatDdMmYyyy() |
yyyy-MM-dd | dd/MM/yyyy | "2023-12-25" โ "25/12/2023" |
parseAndFormatShortDate() |
yyyy-MM-dd | dd MMM yyyy | "2023-12-25" โ "25 Dec 2023" |
parseAndFormatMonthAbbr() |
yyyy-MM-dd | MMM | "2023-12-25" โ "Dec" |
parseAndFormatDayOfWeek() |
yyyy-MM-dd | E | "2023-12-25" โ "Mon" |
parseAndFormatYear() |
yyyy-MM-dd | y | "2023-12-25" โ "2023" |
parseAndFormatMonthYear() |
yyyy-MM-dd | MMMM yyyy | "2023-12-25" โ "December 2023" |
parseDdMmYyyyAndFormatYyyyMmDd() |
dd/MM/yyyy | yyyy-MM-dd | "25/12/2023" โ "2023-12-25" |
parseDdMmYyyyAndFormatShortDate() |
dd/MM/yyyy | dd MMM yyyy | "25/12/2023" โ "25 Dec 2023" |
parseDdMmYyyyAndFormatMonthAbbr() |
dd/MM/yyyy | MMM | "25/12/2023" โ "Dec" |
Extension Methods
Method | Format | Example Output |
---|---|---|
toDdMmYyyy() |
dd/MM/yyyy | "25/12/2023" |
toYyyyMmDd() |
yyyy-MM-dd | "2023-12-25" |
toShortDate() |
dd MMM yyyy | "25 Dec 2023" |
toDateWithTime() |
dd MMM yyyy, h:mm a | "25 Dec 2023, 2:30 PM" |
toFullDateTime() |
yyyy-MM-dd HH:mm:ss | "2023-12-25 14:30:45" |
toIsoWithTimezone() |
yyyy-MM-dd'T'HH:mm:ssZ | "2023-12-25T14:30:00+00:00" |
toTime12Hour() |
h:mm a | "2:30 PM" |
toTime24Hour() |
HH:mm | "14:30" |
toFullTime() |
HH:mm:ss | "14:30:45" |
toDayOfWeek() |
E | "Mon" |
toMonthAbbr() |
MMM | "Dec" |
toMonthFull() |
MMMM | "December" |
toYear() |
y | "2023" |
toMonthYear() |
MMMM yyyy | "December 2023" |
toMmDdYyyy() |
MM/dd/yyyy | "12/25/2023" |
toFullDayDate() |
EEEE, MMMM d, yyyy | "Monday, December 25, 2023" |
toYyyyMmDdHhMm() |
yyyy-MM-dd HH:mm | "2023-12-25 14:30" |
String Extension Methods
Method | Input Format | Output Format | Example |
---|---|---|---|
parseYyyyMmDdToDdMmYyyy() |
yyyy-MM-dd | dd/MM/yyyy | "2023-12-25" โ "25/12/2023" |
parseYyyyMmDdToShortDate() |
yyyy-MM-dd | dd MMM yyyy | "2023-12-25" โ "25 Dec 2023" |
parseYyyyMmDdToMonthAbbr() |
yyyy-MM-dd | MMM | "2023-12-25" โ "Dec" |
parseYyyyMmDdToDayOfWeek() |
yyyy-MM-dd | E | "2023-12-25" โ "Mon" |
parseYyyyMmDdToYear() |
yyyy-MM-dd | y | "2023-12-25" โ "2023" |
parseYyyyMmDdToMonthYear() |
yyyy-MM-dd | MMMM yyyy | "2023-12-25" โ "December 2023" |
parseDdMmYyyyToYyyyMmDd() |
dd/MM/yyyy | yyyy-MM-dd | "25/12/2023" โ "2023-12-25" |
parseDdMmYyyyToShortDate() |
dd/MM/yyyy | dd MMM yyyy | "25/12/2023" โ "25 Dec 2023" |
parseDdMmYyyyToMonthAbbr() |
dd/MM/yyyy | MMM | "25/12/2023" โ "Dec" |
isValidYyyyMmDd |
- | bool | "2023-12-25" โ true |
isValidDdMmYyyy |
- | bool | "25/12/2023" โ true |
isValidMmDdYyyy |
- | bool | "12/25/2023" โ true |
DateTime Extension Properties
Property | Type | Description | Example |
---|---|---|---|
isToday |
bool | Checks if date is today | date.isToday |
isYesterday |
bool | Checks if date is yesterday | date.isYesterday |
isTomorrow |
bool | Checks if date is tomorrow | date.isTomorrow |
age |
int | Gets age from birth date | birthDate.age |
quarter |
int | Gets quarter of year | date.quarter |
weekOfYear |
int | Gets week of year | date.weekOfYear |
startOfDay |
DateTime | Start of day (00:00:00) | date.startOfDay |
endOfDay |
DateTime | End of day (23:59:59) | date.endOfDay |
startOfWeek |
DateTime | Start of week (Monday) | date.startOfWeek |
endOfWeek |
DateTime | End of week (Sunday) | date.endOfWeek |
startOfMonth |
DateTime | Start of month | date.startOfMonth |
endOfMonth |
DateTime | End of month | date.endOfMonth |
startOfYear |
DateTime | Start of year | date.startOfYear |
endOfYear |
DateTime | End of year | date.endOfYear |
DateTime Extension Methods
Method | Description | Example |
---|---|---|
addDays(int days) |
Adds days to date | date.addDays(7) |
subtractDays(int days) |
Subtracts days from date | date.subtractDays(7) |
differenceInDays(DateTime other) |
Days difference | date.differenceInDays(other) |
differenceInHours(DateTime other) |
Hours difference | date.differenceInHours(other) |
differenceInMinutes(DateTime other) |
Minutes difference | date.differenceInMinutes(other) |
๐๏ธ Architecture
The package is organized into several modules for better maintainability:
flutter_date_kit.dart
: Main entry point with DateFormatService and extensionssrc/date_formats.dart
: Date format patterns and pre-configured DateFormat instancessrc/date_utils.dart
: Utility functions for date manipulation and validation
๐ง Performance Optimizations
- Singleton Pattern: DateFormatService uses a singleton pattern to avoid creating multiple instances
- Pre-configured Formats: DateFormat instances are pre-configured for better performance
- Extension Methods: Use the singleton instance internally for optimal performance
๐ก๏ธ Error Handling
The package provides comprehensive error handling:
- FormatException: Thrown when parsing invalid date strings
- Validation Methods: Safe validation methods to check date format validity
- Try-Catch Support: All parsing methods support try-catch error handling
๐ Additional information
This package is built on top of the intl package, which provides internationalization and localization facilities for Dart and Flutter applications.
Dependencies
intl: ^0.20.2
- For date formatting functionalityflutter: ">=1.17.0"
- Flutter framework
Contributing
Feel free to contribute to this package by:
- Forking the repository
- Creating a feature branch
- Making your changes
- Adding tests
- Submitting a pull request
License
This package is licensed under the BSD-3-Clause license.