---
title: DateComponentsFormatter
framework: foundation
role: symbol
role_heading: Class
path: foundation/datecomponentsformatter
---

# DateComponentsFormatter

A formatter that creates string representations of quantities of time.

## Declaration

```swift
class DateComponentsFormatter
```

## Overview

Overview An DateComponentsFormatter object takes quantities of time and formats them as a user-readable string. Use a date components formatter to create strings for your app’s interface. The formatter object has many options for creating both abbreviated and expanded strings. The formatter takes the current user’s locale and language into account when generating strings. To use this class, create an instance, configure its properties, and call one of its methods to generate an appropriate string. The properties of this class let you configure the calendar and specify the date and time units you want displayed in the resulting string. The listing below shows how to configure a formatter to create the string “About 5 minutes remaining”. The methods of this class may be called safely from any thread of your app. It is also safe to share a single instance of this class from multiple threads, with the caveat that you should not change the configuration of the object while another thread is using it to generate a string. tip: In Swift, you can use Date.RelativeFormatStyle rather than DateComponentsFormatter. The FormatStyle API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical FormatStyle instances, so you don’t need to pass them around your app, or risk wasting memory with duplicate formatters.

## Topics

### Formatting Values

- [string(from:)](foundation/datecomponentsformatter/string(from:)-9exxn.md)
- [string(for:)](foundation/datecomponentsformatter/string(for:).md)
- [string(from:to:)](foundation/datecomponentsformatter/string(from:to:).md)
- [string(from:)](foundation/datecomponentsformatter/string(from:)-7sj4j.md)
- [localizedString(from:unitsStyle:)](foundation/datecomponentsformatter/localizedstring(from:unitsstyle:).md)

### Configuring the Formatter Options

- [allowedUnits](foundation/datecomponentsformatter/allowedunits.md)
- [allowsFractionalUnits](foundation/datecomponentsformatter/allowsfractionalunits.md)
- [calendar](foundation/datecomponentsformatter/calendar.md)
- [collapsesLargestUnit](foundation/datecomponentsformatter/collapseslargestunit.md)
- [includesApproximationPhrase](foundation/datecomponentsformatter/includesapproximationphrase.md)
- [includesTimeRemainingPhrase](foundation/datecomponentsformatter/includestimeremainingphrase.md)
- [maximumUnitCount](foundation/datecomponentsformatter/maximumunitcount.md)
- [unitsStyle](foundation/datecomponentsformatter/unitsstyle-swift.property.md)
- [zeroFormattingBehavior](foundation/datecomponentsformatter/zeroformattingbehavior-swift.property.md)

### Constants

- [DateComponentsFormatter.UnitsStyle](foundation/datecomponentsformatter/unitsstyle-swift.enum.md)
- [DateComponentsFormatter.ZeroFormattingBehavior](foundation/datecomponentsformatter/zeroformattingbehavior-swift.struct.md)

### Instance Properties

- [formattingContext](foundation/datecomponentsformatter/formattingcontext.md)
- [referenceDate](foundation/datecomponentsformatter/referencedate.md)

### Instance Methods

- [getObjectValue(_:for:errorDescription:)](foundation/datecomponentsformatter/getobjectvalue(_:for:errordescription:).md)

## Relationships

### Inherits From

- [Formatter](foundation/formatter.md)

### Conforms To

- [CVarArg](swift/cvararg.md)
- [CustomDebugStringConvertible](swift/customdebugstringconvertible.md)
- [CustomStringConvertible](swift/customstringconvertible.md)
- [Equatable](swift/equatable.md)
- [Hashable](swift/hashable.md)
- [NSCoding](foundation/nscoding.md)
- [NSCopying](foundation/nscopying.md)
- [NSObjectProtocol](objectivec/nsobjectprotocol.md)
- [Sendable](swift/sendable.md)
- [SendableMetatype](swift/sendablemetatype.md)

## See Also

### Dates and times

- [DateFormatter](foundation/dateformatter.md)
- [RelativeDateTimeFormatter](foundation/relativedatetimeformatter.md)
- [DateIntervalFormatter](foundation/dateintervalformatter.md)
- [ISO8601DateFormatter](foundation/iso8601dateformatter.md)