<!--
{
  "availability" : [
    "iOS: 8.0.0 -",
    "iPadOS: 8.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.10.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/DateComponentsFormatter",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSDateComponentsFormatter"
  },
  "title" : "DateComponentsFormatter"
}
-->

# DateComponentsFormatter

A formatter that creates string representations of quantities of time.

```
class DateComponentsFormatter
```

## Overview

An [`DateComponentsFormatter`](/documentation/Foundation/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”.

```swift
let formatter = DateComponentsFormatter()
formatter.unitsStyle = .full
formatter.includesApproximationPhrase = true
formatter.includesTimeRemainingPhrase = true
formatter.allowedUnits = [.minute]
 
// Use the configured formatter to generate the string.
let outputString = formatter.string(from: 300.0)
```

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 ``doc://com.apple.foundation/documentation/Foundation/Date/RelativeFormatStyle`` rather than ``doc://com.apple.foundation/documentation/Foundation/DateComponentsFormatter``. The ``doc://com.apple.foundation/documentation/Foundation/FormatStyle`` API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical ``doc://com.apple.foundation/documentation/Foundation/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:)`](/documentation/Foundation/DateComponentsFormatter/string(from:)-9exxn)

Returns a formatted string based on the specified date component information.

[`string(for:)`](/documentation/Foundation/DateComponentsFormatter/string(for:))

Returns a formatted string based on the date information in the specified object.

[`string(from:to:)`](/documentation/Foundation/DateComponentsFormatter/string(from:to:))

Returns a formatted string based on the time difference between two dates.

[`string(from:)`](/documentation/Foundation/DateComponentsFormatter/string(from:)-7sj4j)

Returns a formatted string based on the specified number of seconds.

[`localizedString(from:unitsStyle:)`](/documentation/Foundation/DateComponentsFormatter/localizedString(from:unitsStyle:))

Returns a localized string based on the specified date components and style option.

### Configuring the Formatter Options

[`allowedUnits`](/documentation/Foundation/DateComponentsFormatter/allowedUnits)

The bitmask of calendrical units such as day and month to include in the output string.

[`allowsFractionalUnits`](/documentation/Foundation/DateComponentsFormatter/allowsFractionalUnits)

A Boolean indicating whether non-integer units may be used for values.

[`calendar`](/documentation/Foundation/DateComponentsFormatter/calendar)

The default calendar to use when formatting date components.

[`collapsesLargestUnit`](/documentation/Foundation/DateComponentsFormatter/collapsesLargestUnit)

A Boolean value indicating whether to collapse the largest unit into smaller units when a certain threshold is met.

[`includesApproximationPhrase`](/documentation/Foundation/DateComponentsFormatter/includesApproximationPhrase)

A Boolean value indicating whether the resulting phrase reflects an inexact time value.

[`includesTimeRemainingPhrase`](/documentation/Foundation/DateComponentsFormatter/includesTimeRemainingPhrase)

A Boolean value indicating whether output strings reflect the amount of time remaining.

[`maximumUnitCount`](/documentation/Foundation/DateComponentsFormatter/maximumUnitCount)

The maximum number of time units to include in the output string.

[`unitsStyle`](/documentation/Foundation/DateComponentsFormatter/unitsStyle-swift.property)

The formatting style for unit names.

[`zeroFormattingBehavior`](/documentation/Foundation/DateComponentsFormatter/zeroFormattingBehavior-swift.property)

The formatting style for units whose value is 0.

### Constants

[`DateComponentsFormatter.UnitsStyle`](/documentation/Foundation/DateComponentsFormatter/UnitsStyle-swift.enum)

Constants for specifying how to represent quantities of time.

[`DateComponentsFormatter.ZeroFormattingBehavior`](/documentation/Foundation/DateComponentsFormatter/ZeroFormattingBehavior-swift.struct)

Formatting constants for when values contain zeroes.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)