Duration Units and Conversion

Gantt stores duration, remainingDuration, and task workHours in one canonical unit: hours. durationUnit controls Duration, Remaining Duration, and Duration Variance; workUnit independently controls Work. These unit fields affect display and editing, not storage. Different tasks can therefore retain different display units in the same column:

1
grid.source = [
2
  { id: 'review', name: 'Review', startDate: '2026-04-06T09:00:00Z', duration: 5, durationUnit: 'hour', workHours: 16, workUnit: 'day' }, // 5 hours, 2 days Work
3
  { id: 'build', name: 'Build', startDate: '2026-04-07', duration: 16, durationUnit: 'day', workHours: '40h' }, // 2 days, 40 hours Work
4
  { id: 'release', name: 'Release train', startDate: '2026-04-09', duration: 120, durationUnit: 'week' }, // renders 3 weeks
5
  { id: 'handoff', name: 'Handoff', startDate: '2026-04-30T16:00:00Z', duration: 0.5, durationUnit: 'minute' }, // renders 30 minutes
6
];

The managed Duration, Remaining Duration, Duration Variance, Work, tooltip, task editor, and Excel export surfaces include the unit label, with singular/plural output such as 1 hour, 5 hours, 1 day, and 2 days.

DurationUnit

1
type DurationUnit =
2
  | 'minute'
3
  | 'hour'
4
  | 'day'
5
  | 'week'
6
  | 'month'
7
  | 'quarter'
8
  | 'year';

Minutes are supported. Persist new numeric data as canonical hours and include durationUnit when a particular display unit must be retained. At source hydration only, legacy unitless numeric values remain supported as day-based values (or the configured fixed default); hydrated task-store data is converted to hours.

When durationUnit is omitted and defaultUnit is auto (the default), the table chooses a readable display unit: values below one working hour use minutes, values below one working day use hours, and longer values use days. Work follows the same rule through workUnit and defaultWorkUnit. A unit entered by the user is retained, so 5 hrs and 2 days can coexist.

Flexible input

The inline grid editor and Task Information editor accept a number followed by a short or long unit:

| Input | Meaning | |---|---| | 30m, 30 min, 30 mins | 30 working minutes | | 5h, 5 hr, 5 hrs | 5 working hours | | 2d, 2 days | 2 working days | | 3w, 3 wk, 3 wks | 3 working weeks | | 2mo, 2 months | 2 working months | | 1q, 1 quarter | 1 working quarter | | 1y, 1 year | 1 working year |

A bare Duration or Remaining Duration edit uses the task's retained durationUnit, then defaultUnit, then days. A bare Work edit uses workUnit, then defaultWorkUnit, then hours. Every accepted edit is converted to hours before the task store is updated. Invalid or negative text is rejected. Work is person-time, so elapsed forms such as 2ed are rejected for Work even though they are valid for task Duration.

Conversion settings

Set project-wide conversion values with gantt.durationSettings:

1
grid.gantt = {
2
  ...project,
3
  durationSettings: {
4
    defaultUnit: 'auto', // or fix: 'minute' | 'hour' | 'day' | ...
5
    defaultWorkUnit: 'auto', // independent fixed/automatic Work unit
6
    hoursPerDay: 8,
7
    hoursPerWeek: 40,
8
    daysPerMonth: 20,
9
    maximumFractionDigits: 1, // default MSP-style compact precision
10
  },
11
};

With these settings:

1 day = 8 hours
1 week = 40 hours = 5 working days
1 month = 20 working days
1 quarter = 3 working months
1 year = 12 working months

defaultUnit and defaultWorkUnit can be fixed independently, matching the distinction between task span and person-work. Both default to auto. hoursPerDay defaults to the effective task calendar's hoursPerDay, then 8. hoursPerWeek defaults to hoursPerDay × workingDays.length, commonly 40. daysPerMonth defaults to 20.

maximumFractionDigits controls rendered precision for Duration, Remaining Duration, Duration Variance, and Work. It defaults to 1, trims trailing zeroes, and only affects presentation: 56.625 days renders as 56.6 days, while canonical stored hours are unchanged. Set it to 0 for whole units or a larger integer when a project needs more visible precision.

Changing hoursPerDay or hoursPerWeek changes conversion at edit, render, and scheduling boundaries. It does not rewrite stored hours and does not redefine the calendar's workingDays, holidays, or workingHours; configure those separately on CalendarEntity.

Working time and elapsed time

Normal units consume working time. With an 8-hour day, 2d is normally 16 working hours. When scheduling.excludeHolidaysFromDuration is enabled, the scheduler also skips closed weekdays, holidays, and configured intraday working-hour gaps.

Elapsed input uses an e prefix and runs continuously, ignoring the working calendar:

1
{ duration: 48, durationUnit: 'day', durationIsElapsed: true } // renders 2 elapsed days

The same value can be entered as 2ed or 2 elapsed days. 2d means two working days; 2ed means 48 continuous hours and can cross nights, weekends, and holidays. Elapsed aliases are supported for every DurationUnit, such as 30em, 4eh, and 1ew.

Summary tasks

Summary duration is derived from the earliest scheduled child start to the latest scheduled child finish. It is a span, not the sum of child durations. Summary Duration cells remain read-only even when their children use mixed units.

Milestones and zero duration

Setting a task's Duration to 0 schedules and renders it as a milestone. Unlike a derived summary Duration, the milestone Duration cell remains editable. Entering any positive value, such as 4h or 2d, stores the converted canonical hours and changes the task type back to task. The same reversible behavior applies in the Task Information dialog.

Programmatic helpers

The Enterprise package exports shared date-layer helpers used by source hydration, scheduling, editors, and projection. Duration parsing, conversion, and formatting live in one module, so every integration follows the same canonical-hour rules:

1
import {
2
  parseDuration,
3
  formatDurationValue,
4
  durationToHours,
5
  hoursToDuration,
6
  durationToElapsedHours,
7
  elapsedHoursToDuration,
8
  resolveDurationSettings,
9
} from '@revolist/revogrid-enterprise';

Use these helpers in custom editors or persistence adapters instead of implementing a second unit conversion table.