# Duration.UnitsFormatStyle A format style that shows durations with localized labeled components ``` struct UnitsFormatStyle ``` ## Overview This style produces formatted strings that break out a duration’s individual components, like “2 min, 3 sec”. Create a `UnitsFormatStyle` by providing a set of allowed [`Duration.UnitsFormatStyle.Unit`](/documentation/Swift/Duration/UnitsFormatStyle/Unit) instances — such as hours, minutes, or seconds — for formatted strings to include. You also specify a width for displaying these units, which controls whether they appear as full words (“minutes”) or abbreviations (“min”). The initializers also take optional parameters to control things like the handling of zero units and fractional parts. Then create a formatted string by calling [`formatted(_:)`](/documentation/Swift/Duration/formatted(_:)) on a duration, passing the style, or [`format(_:)`](/documentation/Swift/Duration/UnitsFormatStyle/format(_:)) on the style, passing a duration. You can also use the style’s [`attributed`](/documentation/Swift/Duration/TimeFormatStyle/attributed-swift.property) property to create a style that produces instances, which contains attributes that indicate the unit value of formatted runs of the string. In situations that expect a [`Duration.UnitsFormatStyle`](/documentation/Swift/Duration/UnitsFormatStyle), such as [`formatted(_:)`](/documentation/Swift/Duration/formatted(_:)), you can use the convenience function `.units(allowed:width:maximumUnitCount:zeroValueUnits:valueLength:fractionalPart:)` to create a [`Duration.UnitsFormatStyle`](/documentation/Swift/Duration/UnitsFormatStyle), rather than using the full initializer. If you want to reuse a style to format many durations, call [`format(_:)`](/documentation/Swift/Duration/UnitsFormatStyle/format(_:)) on the style, passing in a new duration each time. The following example creates `duration` to represent 1 hour, 10 minutes, 32 seconds, and 400 milliseconds. It then creates a [`Duration.UnitsFormatStyle`](/documentation/Swift/Duration/UnitsFormatStyle) to show the hours, minutes, seconds, and milliseconds parts, with a wide width that presents the full name of each unit. ``` let duration = Duration.seconds(70 * 60 + 32) + Duration.milliseconds(400) let format = duration1.formatted( .units(allowed: [.hours, .minutes, .seconds, .milliseconds], width: .wide)) // format == "1 hour, 10 minutes, 32 seconds, 400 milliseconds" ``` The formatted string omits any units that aren’t needed to accurately represent the value. In the above example, a duration of exactly one minute would format as `1 minute`, omitting the hours, seconds, and milliseconds parts. To override this behavior and show the omitted units, use the initializer’s’ `zeroValueUnits` parameter. ## Topics ### Creating a units format style [`init(allowedUnits:width:maximumUnitCount:zeroValueUnits:valueLength:fractionalPart:)`](/documentation/Swift/Duration/UnitsFormatStyle/init(allowedUnits:width:maximumUnitCount:zeroValueUnits:valueLength:fractionalPart:)) Creates a units format style using the given parameters. [`init(allowedUnits:width:maximumUnitCount:zeroValueUnits:valueLengthLimits:fractionalPart:)`](/documentation/Swift/Duration/UnitsFormatStyle/init(allowedUnits:width:maximumUnitCount:zeroValueUnits:valueLengthLimits:fractionalPart:)) Creates a units format style using the given parameters. ### Formatting a duration [`format(_:)`](/documentation/Swift/Duration/UnitsFormatStyle/format(_:)) Creates a locale-aware string representation from a duration value. ### Formatting a duration as an attributed string [`attributed`](/documentation/Swift/Duration/UnitsFormatStyle/attributed-swift.property) A property that formats the duration as an attributed string. [`Duration.UnitsFormatStyle.Attributed`](/documentation/Swift/Duration/UnitsFormatStyle/Attributed-swift.struct) A format style that formats durations as attributed strings. ### Working with units [`allowedUnits`](/documentation/Swift/Duration/UnitsFormatStyle/allowedUnits) The units that may be included in the output string. [`Duration.UnitsFormatStyle.Unit`](/documentation/Swift/Duration/UnitsFormatStyle/Unit) A unit to use in formatting a duration. [`maximumUnitCount`](/documentation/Swift/Duration/UnitsFormatStyle/maximumUnitCount) The maximum number of time units to include in the output string. [`valueLengthLimits`](/documentation/Swift/Duration/UnitsFormatStyle/valueLengthLimits) The padding or truncating behavior of the unit value. ### Working with unit widths [`unitWidth`](/documentation/Swift/Duration/UnitsFormatStyle/unitWidth-swift.property) The width of the unit and the spacing between the value and the unit. [`Duration.UnitsFormatStyle.UnitWidth`](/documentation/Swift/Duration/UnitsFormatStyle/UnitWidth-swift.struct) The width of a unit to use in formatting a duration. ### Working with zero values [`zeroValueUnitsDisplay`](/documentation/Swift/Duration/UnitsFormatStyle/zeroValueUnitsDisplay) The strategy for how zero-value units are handled. [`Duration.UnitsFormatStyle.ZeroValueUnitsDisplayStrategy`](/documentation/Swift/Duration/UnitsFormatStyle/ZeroValueUnitsDisplayStrategy) A strategy that determines how to format a unit whose value is zero. ### Working with fractional values [`fractionalPartDisplay`](/documentation/Swift/Duration/UnitsFormatStyle/fractionalPartDisplay) The strategy for displaying a duration if it cannot be represented exactly with the allowed units. [`Duration.UnitsFormatStyle.FractionalPartDisplayStrategy`](/documentation/Swift/Duration/UnitsFormatStyle/FractionalPartDisplayStrategy) A strategy that determines how to format the fractional part of a duration if the allowed units can’t represent it exactly. ### Working with locales [`locale`](/documentation/Swift/Duration/UnitsFormatStyle/locale) The locale to use when formatting the duration. [`locale(_:)`](/documentation/Swift/Duration/UnitsFormatStyle/locale(_:)) A modifier to set the locale of the format style. ### Encoding and decoding ### Hashing ### Supporting types --- Copyright © 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)