Date and Time in Dart

By Syncfusion®, Inc. · Last updated November 11, 2026

How to create DateTime values, read their parts, compare and subtract dates, add time with Duration, and convert dates to text and timestamps.

What Is DateTime?

DateTime = a Dart value that holds one exact moment: a date and a time.

For example:

• the start of the Maths exam: 14 November 2026, 9:30 in the morning
• the homework deadline: 20 November 2026, 11:59 at night
• right now

Duration = a length of time, like 3 days or 45 minutes. It is not a moment, just an amount.

Simple lesson: a DateTime is a point on the calendar, and a Duration is a gap between two points.

A Real-World Example

The school app shows: "Exam in 10 days, on Tuesday."

• It knows today (a DateTime).
• It knows the exam date (another DateTime).
• It works out the gap between them (a Duration), and the weekday of the exam.

Move the sliders to add time to a date:

What You Will Learn

In this lesson, you will learn:

1. How to create DateTime values in five ways.
2. How to read a date's parts, like year, month and weekday.
3. How to compare dates and find the time between them.
4. How to add and subtract time, and turn dates into text and timestamps.
5. How to create and use Duration values.

Creating DateTime Objects

Creating dates

void main() {
  var exam = DateTime(2026, 11, 14, 9, 30);
  var republicDay = DateTime.utc(2026, 1, 26, 10);
  var independenceDay = DateTime.parse('2026-08-15 08:00:00');
  var start = DateTime.fromMillisecondsSinceEpoch(0, isUtc: true);
  print(exam);
  print(republicDay);
  print(independenceDay);
  print(start);
}

Local time = the time on your own clock, in your time zone.

UTC (Coordinated Universal Time) = one standard clock for the whole world. India is 5 hours 30 minutes ahead of it.

DateTime.now()

Right now

void main() {
  var now = DateTime.now();
  print(now);
  print('This year is ${now.year}.');
}

Your output is different from everyone else's, because it reads your clock.

Simple lesson: use DateTime(...) for a fixed date, DateTime.now() for the current moment, and DateTime.parse() for text.

Date Components

Every DateTime has these parts:

Reading the parts of a date

void main() {
  var exam = DateTime(2026, 11, 14, 9, 30);
  var days = ['', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'];
  print('${exam.day}/${exam.month}/${exam.year}');
  print('Starts at ${exam.hour}:${exam.minute}');
  print('Weekday number: ${exam.weekday}');
  print('That is a ${days[exam.weekday]}.');
  print(exam.weekday == DateTime.saturday);
}

• weekday starts at 1 for Monday, not 0.
• Dart has names for them: DateTime.monday is 1, up to DateTime.sunday, which is 7.

Simple lesson: read a date's parts with year, month, day, hour and weekday.

Time Zone Properties

• isUtc = true if the date is in UTC.
• timeZoneName = a short name, like IST. It depends on the computer.
• timeZoneOffset = how far this time zone is from UTC, as a Duration.

Your time zone

void main() {
  var exam = DateTime(2026, 11, 14, 9, 30);
  print(exam.isUtc);
  print(exam.timeZoneName);
  print(exam.timeZoneOffset);
  var utc = exam.toUtc();
  print(utc);
  print(utc.isUtc);
}

In India, the offset is 5:30:00.000000. On a computer set to another country, the numbers differ.

• toUtc() = the same moment, shown on the UTC clock.
• toLocal() = the same moment, shown on your local clock.

Simple lesson: a moment is the same everywhere, but its clock time depends on the time zone.

Date Operations

Comparing two dates

void main() {
  var today = DateTime(2026, 11, 4);
  var exam = DateTime(2026, 11, 14);
  print(today.isBefore(exam));
  print(today.isAfter(exam));
  print(today.compareTo(exam));
  var gap = exam.difference(today);
  print(gap);
  print('Exam in ${gap.inDays} days');
}

exam.difference(today) = exam minus today. Swap them and the Duration is negative.

Simple lesson: compare dates with isBefore and isAfter, and measure the gap with difference.

Date Modification

• add(duration) = a new date, later by that much.
• subtract(duration) = a new date, earlier by that much.

The original date never changes.

Simple lesson: add and subtract give new dates, and leave the old one unchanged.

Formatting and Timestamps

toString() and toIso8601String()

• toString() = 2026-11-14 09:30:00.000. This is what print shows.
• toIso8601String() = 2026-11-14T09:30:00.000. The world standard, used by servers and JSON.

Timestamps

Epoch = 1 January 1970, 00:00 UTC. Computers count time from this moment.

Timestamp = the number of milliseconds (or microseconds) since the epoch.

Text and timestamps

void main() {
  var launch = DateTime.utc(2026, 11, 14, 9, 30);
  print(launch.toString());
  print(launch.toIso8601String());
  print(launch.millisecondsSinceEpoch);
  print(launch.microsecondsSinceEpoch);
  var back = DateTime.fromMillisecondsSinceEpoch(launch.millisecondsSinceEpoch, isUtc: true);
  print(back);
}

A timestamp is just a number, so it is easy to store and send.

Simple lesson: toIso8601String() is the standard text form, and a timestamp is the date as one big number.

Duration Fundamentals

Duration = an amount of time.

Duration Constructors

Make one with named parameters, all optional:

Duration(days: 1, hours: 2, minutes: 30, seconds: 15, milliseconds: 0, microseconds: 0)

Making durations

void main() {
  var period = Duration(minutes: 40);
  var lunch = Duration(minutes: 45);
  var schoolDay = Duration(hours: 6, minutes: 30);
  var holiday = Duration(days: 10);
  print(period);
  print(lunch);
  print(schoolDay);
  print(holiday);
}

A Duration prints as hours:minutes:seconds.microseconds. Ten days is 240:00:00.000000.

Duration Properties

One duration, many units

void main() {
  var schoolDay = Duration(hours: 6, minutes: 30);
  print(schoolDay.inHours);
  print(schoolDay.inMinutes);
  print(schoolDay.inSeconds);
  print(schoolDay.inDays);
}

Each in... gives whole units. 6 hours 30 minutes is 6 in inHours, not 6.5.

Simple lesson: make a Duration with named parts, and read it back in any unit with in....

Working with Duration

Adding and Subtracting Durations

Adding up the school timetable

void main() {
  var period = Duration(minutes: 40);
  var breakTime = Duration(minutes: 15);
  var morning = period + period + period + breakTime;
  print(morning);
  print(morning.inMinutes);
  var left = Duration(hours: 3) - morning;
  print(left);
  print(period < breakTime);
  print(period * 2);
}

• + and - add and subtract durations.
• <, > and == compare them.
• * with a number multiplies a duration.

Simple lesson: durations add and subtract like numbers, and a date plus a duration is a new date.

TL;DR

1. DateTime = one moment. Create with DateTime(...), now(), utc(...), parse(...) or fromMillisecondsSinceEpoch(...).

2. Parts: year, month, day, hour, minute, second, weekday (1 = Monday).

   • Time zones: isUtc, timeZoneName, timeZoneOffset, toUtc(), toLocal().
3. Compare: isBefore, isAfter, isAtSameMomentAs, compareTo. Gap: difference.

4. Change: add and subtract give new dates.

   • Text: toString(), toIso8601String(). Timestamps: millisecondsSinceEpoch.

5. Duration = an amount. Duration(days:, hours:, minutes:, ...), read with inDays, inHours...

   • Add and subtract with + and -.

Common mistakes

Check Yourself

Exercises

What to Remember

• A DateTime is a moment. Create it with DateTime(...), now(), utc() or parse().
• weekday runs from 1 (Monday) to 7 (Sunday), and months run from 1 to 12.
• isBefore, isAfter and difference compare dates.
• add and subtract make new dates. The original never changes.
• A Duration is an amount of time. Read it with inDays, inHours and inMinutes.

Next: Libraries. You will learn how Dart code is split into libraries, and how to import the ones you need.