›› Formats

Formats

Formats

A Format defines how a quantity value is displayed to users. Formats control precision, unit labels, composite units (like feet-inches), and various display traits. Understanding format specifications is essential for creating consistent and user-friendly quantity displays.

FormatProps

FormatProps is the core interface that defines all format properties. Each property is documented with its constraints and valid values in the API reference. For additional context on format specifications, see the EC documentation on Format.

Format Types

Decimal Format

Displays values with a fixed number of decimal places.

{ "type": "Decimal", "precision": 4, "formatTraits": ["keepSingleZero", "showUnitLabel"], "decimalSeparator": "." }

Fractional Format

Displays values as fractions with specified denominator.

{ "type": "Fractional", "precision": 8, "formatTraits": ["keepSingleZero", "showUnitLabel"], "uomSeparator": "" }

Scientific Format

Displays values in scientific notation (e.g., 1.23E+04).

{ "type": "Scientific", "precision": 2, "scientificType": "Normalized" }

Station Format

Specialized format for civil engineering station values. See Station Format Properties below.

Composite Formats

Format definitions that utilize composite units allow quantity values to be displayed across multiple units. Typical examples:

Imperial length: 5'-3 1/2" (feet and inches)
Angles: 45°30'15" (degrees, minutes, seconds)
Surveying: 1+055.50 (stations)

Composite format properties:

includeZero - Whether to show zero values for sub-units
spacer - String separator between sub-unit values
units - Array of unit definitions with labels

Example: Feet-Inches Format

{ "composite": { "includeZero": true, "spacer": "-", "units": [ { "label": "'", "name": "Units.FT" }, { "label": "\"", "name": "Units.IN" } ] }, "formatTraits": ["keepSingleZero", "showUnitLabel"], "precision": 8, "type": "Fractional", "uomSeparator": "" }

Station Format Properties

Station formatting in iTwin.js supports properties that control how values are broken down into major and minor station components:

stationOffsetSize

The stationOffsetSize property specifies the number of decimal places for calculating the station offset magnitude. This must be a positive integer greater than 0. This works with stationBaseFactor to determine the effective station offset using the formula: effective offset = stationBaseFactor * 10^stationOffsetSize.

stationBaseFactor

The stationBaseFactor property provides additional flexibility for station formatting by acting as a multiplier for the base offset calculation. This allows for non-standard station intervals that aren't simple powers of 10. The default value is 1.

Note: The stationBaseFactor property is currently implemented as an iTwin.js-specific extension and is not supported in the native EC (Entity Context) layer. This feature will eventually be incorporated into the ECFormat specification to provide broader compatibility across the iTwin ecosystem.

Station Format Examples

stationOffsetSize	stationBaseFactor	Value	Effective Offset	Formatted
2	1	1055.5	100	10+55.50
3	1	1055.5	1000	1+055.50
2	5	1055.5	500	2+55.50

In the examples above:

With stationOffsetSize=2 and stationBaseFactor=1: effective offset = 1 × 10² = 100
With stationOffsetSize=3 and stationBaseFactor=1: effective offset = 1 × 10³ = 1000
With stationOffsetSize=2 and stationBaseFactor=5: effective offset = 5 × 10² = 500

Format Traits

Format traits are flags that control various display behaviors:

keepSingleZero - Always show at least one trailing zero
showUnitLabel - Display the unit label after the value
trailZeroes - Show trailing zeros up to specified precision
use1000Separator - Insert thousand separators (e.g., commas)
applyRounding - Apply rounding rules to precision
fractionDash - Use dash in fractions (e.g., 3-1/2 instead of 3 1/2)
keepDecimalPoint - Always show decimal point even for whole numbers
zeroEmpty - Display zero values as empty string

Code Examples

Numeric Format Example

This example uses a simple numeric format with 4 decimal place precision:

Example Code

const quantityFormatter = new QuantityFormatter(); const unitsProvider = quantityFormatter.unitsProvider; const formatData = { formatTraits: ["keepSingleZero", "applyRounding", "showUnitLabel", "trailZeroes", "use1000Separator"], precision: 4, type: "Decimal", uomSeparator: " ", thousandSeparator: ",", decimalSeparator: ".", }; // generate a Format from FormatProps to display 4 decimal place value const format = new Format("4d"); // load the format props into the format, since unit provider is used to validate units the call must be asynchronous. await format.fromJSON(unitsProvider, formatData); // define input/output unit const unitName = "Units.FT"; const unitLabel = "ft"; const unitFamily = "Units.LENGTH"; const inUnit = new BasicUnit(unitName, unitLabel, unitFamily); const magnitude = -12.5416666666667; // create the formatter spec - the name is not used by the formatter it is only // provided so user can cache formatter spec and then retrieve spec via its name. const spec = await FormatterSpec.create("test", format, unitsProvider, inUnit); // apply the formatting held in FormatterSpec const formattedValue = spec.applyFormatting(magnitude); // result in formattedValue of "-12.5417 ft"

Composite Format Example

This example formats a metric value (meters) as feet-inches with fractional precision: