Quantity Formatting › Usage › Providers
Edit this page

Providers

Providers are the runtime components that supply format and unit definitions to formatters and parsers. Understanding the different provider types and how to register them is essential for setting up quantity formatting in iTwin.js applications.

Understanding Providers

UnitsProvider

The UnitsProvider interface is central to unit management in iTwin.js. It provides methods to:

Units Provider Concept

A units provider acts as a registry and converter for units. When you need to format or parse a quantity value, the provider:

  1. Locates the source unit (e.g., meters for persistence)
  2. Locates the target unit (e.g., feet and inches for display)
  3. Provides conversion factors between these units
  4. Validates unit compatibility (ensures units are in the same phenomenon)

BasicUnitsProvider

BasicUnitsProvider is a standalone provider backed by the full BIS Units schema bundled as a JSON asset in @itwin/core-quantity. It is the default provider used by IModelApp.quantityFormatter when no iModel-specific provider is registered.

Characteristics:

  • No dependencies on iModels or schemas — works in any context (frontend, backend, tools)
  • Contains all BIS units covering all phenomena (length, area, volume, temperature, pressure, angle, force, velocity, etc.)
  • Unit data is resolved lazily on first use and cached at module scope — construction is essentially free, and multiple instances share the same immutable lookup indexes
  • Available from @itwin/core-quantity, so it can be used outside @itwin/core-frontend
  • The bundled unit data is versioned: version tracks the serialization format, and sourceEcSchemaVersion records which BIS Units EC schema release the data was derived from

When to use:

  • Default for all applications — enabled automatically by QuantityFormatter
  • Backend or CLI tools that need unit resolution without an iModel
  • UIs and workflows that don't need an iModel, like iTwin-level workflows
  • As a lightweight alternative to SchemaUnitProvider when domain-specific custom units are not needed

Note: The BasicUnitsProvider previously exported from @itwin/core-frontend was a limited provider (≈40 units) and has been removed. Use BasicUnitsProvider from @itwin/core-quantity instead.

Synchronous local data

Use the optional SyncUnitsProvider capability when a caller must construct a formatter without awaiting a provider. BasicUnitsProvider implements it for the bundled canonical BIS units.

These methods use local data only. BasicUnitsProvider returns BadUnit for an unknown name. It returns an identity conversion with error: true when a unit is unavailable or the units are incompatible. Treat either result as a miss and use the plain-value fallback instead of loading a schema or awaiting.

A format provider can implement SyncFormatsProvider when it can return a locally available FormatDefinition through getFormatSync. The method returns undefined when the format is not available synchronously; it does not make schema loading synchronous. A provider that delegates the current lookup to another provider should forward the optional lookup context unchanged; omit it only when starting an independent lookup.

createUnitsProvider

createUnitsProvider is a factory function that layers a primary provider (such as SchemaUnitProvider) on top of BasicUnitsProvider. Schema-defined units win on overlap; basic BIS units fill any gaps. Pass bisUnitsPolicy: "preferBundled" to invert precedence so the bundled BIS units win instead.

import { createUnitsProvider } from "@itwin/core-quantity"; import { SchemaUnitProvider } from "@itwin/ecschema-metadata"; const provider = createUnitsProvider({ primary: new SchemaUnitProvider(schemaContext), }); // SchemaUnitProvider units win; BasicUnitsProvider fills gaps

When no primary is supplied, createUnitsProvider() returns a plain new BasicUnitsProvider() — no wrapper.

You can also use the generated canonical identifiers exported by @itwin/core-quantity to avoid magic strings when looking up bundled BIS units:

import { BasicUnitsProvider, getDefaultPersistenceUnit, Phenomena, Units } from "@itwin/core-quantity"; const provider = new BasicUnitsProvider(); const persistenceUnit = getDefaultPersistenceUnit(Phenomena.LENGTH); const meter = await provider.findUnitByName(Units.LENGTH.M); const lengthUnits = await provider.getUnitsByFamily(Phenomena.LENGTH);

When you need a recommended built-in persistence unit for a bundled phenomenon, use getDefaultPersistenceUnit. For example, getDefaultPersistenceUnit(Phenomena.LENGTH) returns Units.LENGTH.M.

Note: getDefaultPersistenceUnit(...) intentionally does not accept Phenomena.LENGTH_RATIO yet, because the bundled built-in unit set does not currently provide an agreed default for that phenomenon.

SchemaUnitProvider

SchemaUnitProvider loads unit definitions from EC schemas using a SchemaContext. It provides access to the extensive Units schema as well as custom units defined in domain schemas.

Characteristics:

  • Requires access to ECSchemas via SchemaContext, commonly through iModels
  • Accesses units through SchemaContext
  • Supports custom domain-specific units not included in the bundled BIS Units schema

When to use:

  • Applications working with iModels
  • When domain-specific units (civil, structural, etc.) are needed
  • When unit definitions must match schema specifications

FormatsProvider

A FormatsProvider supplies format definitions for a KindOfQuantity. The FormatDefinition interface extends FormatProps to help identify formats.

SchemaFormatsProvider

SchemaFormatsProvider retrieves formats from EC schemas using a SchemaContext. An optional UnitSystemKey selects formats for a unit system.

A schema-backed provider can implement SyncFormatsProvider for definitions that are already loaded. Treat an undefined result as a synchronous cache miss and use the asynchronous provider path when loading is acceptable.

Characteristics:

  • Loads formats from KindOfQuantity definitions in schemas
  • Filters formats by unit system preference group. See Unit Systems and UnitSystemKey for how each key maps to EC UnitSystems
  • Throws an error for invalid EC full names
  • Read-only format provider

Format selection

When a unit system is provided, SchemaFormatsProvider checks a KindOfQuantity in this order:

  1. Presentation formats, using the unit-system preference order and the order declared by the KindOfQuantity
  2. The persistence unit, represented as a basic decimal format when its unit system matches
  3. The default presentation format

Without a unit system, it uses the default presentation format. getFormatSync follows the same order but reads only schema metadata already loaded in the SchemaContext. If required metadata is not cached, it returns undefined instead of loading a schema; use getFormat when loading is acceptable.

Example: Simple Formatting

Formatting with SchemaFormatsProvider
const formatsProvider = new SchemaFormatsProvider(schemaContext, "metric"); const unitsProvider = new SchemaUnitProvider(schemaContext); const persistenceUnit = await unitsProvider.findUnitByName("Units.M"); // or unitsProvider.findUnit("m"); // No unit system was provided, and no format was found in the cache so the method will return the first presentation format for the KoQ, which uses meters. const formatProps = await formatsProvider.getFormat("AecUnits.LENGTH"); const format = await Format.createFromJSON("testFormat", unitsProvider, formatProps!); const formatSpec = await FormatterSpec.create("TestSpec", format, unitsProvider, persistenceUnit); const result = formatSpec.applyFormatting(50); // The persistence unit is meters, so this input value is 50 m. // result in formatted value of 50 m

Example: Parsing

Parsing with SchemaFormatsProvider
const formatsProvider = new SchemaFormatsProvider(schemaContext, "metric"); const unitsProvider = new SchemaUnitProvider(schemaContext); const persistenceUnit = await unitsProvider.findUnitByName("Units.M"); // or unitsProvider.findUnit("m"); const formatProps = await formatsProvider.getFormat("AecUnits.LENGTH_LONG"); const format = await Format.createFromJSON("testFormat", unitsProvider, formatProps!); const parserSpec = await ParserSpec.create(format, unitsProvider, persistenceUnit); const result = parserSpec.parseToQuantityValue("50 km"); // result.value 50000 (value in meters)

Example: Unit System Override

When retrieving a format from a schema, you might want to ensure the format matches your current unit system. You can pass the unit system on initialization or change it afterward:

Formatting with Unit System Override
const formatsProvider = new SchemaFormatsProvider(schemaContext, "metric"); const unitsProvider = new SchemaUnitProvider(schemaContext); const persistenceUnit = await unitsProvider.findUnitByName("Units.M"); // or unitsProvider.findUnit("m"); formatsProvider.unitSystem = "imperial"; // This will cause the method to return the first presentation format for the KoQ that uses imperial units. const formatProps = await formatsProvider.getFormat("AecUnits.LENGTH_LONG"); const format = await Format.createFromJSON("testFormat", unitsProvider, formatProps!); const formatSpec = await FormatterSpec.create("TestSpec", format, unitsProvider, persistenceUnit); const result = formatSpec.applyFormatting(50); // The persistence unit is meters, so this input value is 50 m. // result in formatted value of 164'0 1/2"

Example: Retrieving KindOfQuantity and Persistence Unit

When you only have a KindOfQuantity name, you can use a SchemaContext to find the schema item and access its persistence unit:

Using SchemaContext to get KindOfQuantity and persistence unit
const formatsProvider = new SchemaFormatsProvider(schemaContext, "metric"); const unitsProvider = new SchemaUnitProvider(schemaContext); const kindOfQuantityName = "AecUnits.LENGTH"; // Get the format definition, for this example it'll return the value in meters, 4 decimal places. const formatDef = await formatsProvider.getFormat(kindOfQuantityName); if (!formatDef) throw new Error(`Format not found for ${kindOfQuantityName}`); const kindOfQuantity = await schemaContext.getSchemaItem(kindOfQuantityName, KindOfQuantity); if (!kindOfQuantity) throw new Error(`KindOfQuantity not found for ${kindOfQuantityName}`); const persistenceUnit = kindOfQuantity.persistenceUnit; if (!persistenceUnit) throw new Error(`Persistence unit not found for ${kindOfQuantityName}`); const persistenceUnitProps = await unitsProvider.findUnitByName(persistenceUnit.fullName); const format = await Format.createFromJSON(formatDef.name ?? "", unitsProvider, formatDef); const formatterSpec = await FormatterSpec.create( formatDef.name ?? "", format, unitsProvider, // Use a schema units provider persistenceUnitProps ); const _formattedValue = formatterSpec.applyFormatting(123.44445); // Returns "123.4445 m"

MutableFormatsProvider

MutableFormatsProvider extends the read-only FormatsProvider by allowing formats to be added or removed at runtime.

Characteristics:

  • Supports dynamic format management
  • Can add custom formats not in schemas
  • Can override schema-defined formats
  • Fires onFormatsChanged event when formats are modified

Example: Implementation

Example MutableFormatsProvider implementation
/** * Implements a formats provider with a cache, to allow adding/removing formats at runtime. */ class ExampleFormatProvider implements MutableFormatsProvider { private _cache: Map<string, FormatDefinition> = new Map(); public onFormatsChanged = new BeEvent<(args: FormatsChangedArgs) => void>(); public async getFormat(name: string): Promise<FormatDefinition | undefined> { return this._cache.get(name); } public async addFormat(name: string, format: FormatDefinition): Promise<void> { this._cache.set(name, format); this.onFormatsChanged.raiseEvent({ formatsChanged: [name]}); } public async removeFormat(name: string): Promise<void> { this._cache.delete(name); this.onFormatsChanged.raiseEvent({ formatsChanged: [name]}); } }

Example: Adding Formats

Adding formats to MutableFormatsProvider
const formatsProvider = new ExampleFormatProvider(); const format: FormatDefinition = { label: "NewFormat", type: "Fractional", precision: 8, formatTraits: ["keepSingleZero", "showUnitLabel"], uomSeparator: "", }; await formatsProvider.addFormat("DefaultToolsUnits.LENGTH", format); const retrievedFormat = await formatsProvider.getFormat("DefaultToolsUnits.LENGTH"); // retrievedFormat is the format we just added.

FormatSetFormatsProvider

FormatSetFormatsProvider manages formats within a FormatSet. This provider automatically updates the underlying format set when formats are added or removed, making it ideal for applications that need to persist format changes.

Key Features:

  • String Reference Resolution: Automatically resolves string references to their target FormatDefinition. When a format references another via string (e.g., "DefaultToolsUnits.LENGTH": "CivilUnits.LENGTH"), the provider resolves and returns the actual FormatDefinition.
  • Chain Resolution: Supports chains of references with circular reference detection.
  • Cascade Notifications: When adding or removing a format, the onFormatsChanged event includes not only the modified format but also all formats that reference it (directly or indirectly).
  • Fallback Provider: String references can resolve through an optional fallback provider if the target format isn't found in the format set.

FormatSetFormatsProvider also implements SyncFormatsProvider. getFormatSync resolves local entries and synchronous fallbacks without awaiting. It returns undefined when the format is missing or the fallback is asynchronous.

Both lookups forward the lookup context to the fallback provider to stop fallback cycles. The cycle check tracks providers, not format names: if a fallback calls back into the same FormatSetFormatsProvider with that context, the lookup returns undefined, even for a different format. A fallback that needs an independent lookup should call without the context.

Example: FormatSet with String References

Using FormatSetFormatsProvider with string references
const unitsProvider = new SchemaUnitProvider(schemaContext); const persistenceUnit = await unitsProvider.findUnitByName("Units.M"); // Create a format set with a base format and string references const formatSet = { name: "MyFormatSet", label: "My Custom Formats", unitSystem: "metric" as const, formats: { // Base format definition "CivilUnits.LENGTH": { composite: { includeZero: true, spacer: " ", units: [{ label: "m", name: "Units.M" }] }, formatTraits: ["keepSingleZero", "showUnitLabel"], precision: 2, type: "Decimal" } as FormatDefinition, // DISTANCE references LENGTH via string "DefaultToolsUnits.LENGTH": "CivilUnits.LENGTH", } }; // Create the provider const formatsProvider = new FormatSetFormatsProvider({ formatSet }); // Getting DefaultToolsUnits.LENGTH resolves to the CivilUnits.LENGTH format definition const lengthFormat = await formatsProvider.getFormat("DefaultToolsUnits.LENGTH"); const format = await Format.createFromJSON("length", unitsProvider, lengthFormat!); const formatSpec = await FormatterSpec.create("LengthSpec", format, unitsProvider, persistenceUnit); const result = formatSpec.applyFormatting(42.567); // result is "42.57 m"

AlternateUnitLabelsProvider

AlternateUnitLabelsProvider allows specifying alternate labels for units during parsing. This is useful for:

  • Supporting common abbreviations (e.g., "ft" and "foot" for feet)
  • Enabling easier keyboard input (e.g., "^" for degrees "°")
  • Accommodating regional variations in unit labels

Registering Providers in iTwin Applications

This section covers how to register and configure providers in your iTwin application. Proper provider registration ensures consistent quantity formatting across your application.

Registering UnitsProvider

Manual Registration

You can manually register a SchemaUnitProvider when opening an iModel:

Manual SchemaUnitProvider registration
/** Register SchemaUnitProvider when IModelConnection is opened */ export async function registerSchemaUnitProvider(iModelConnection: IModelConnection) { // Wrap SchemaUnitProvider with createUnitsProvider so basic BIS units fill any gaps await IModelApp.quantityFormatter.setUnitsProvider( createUnitsProvider({ primary: new SchemaUnitProvider(iModelConnection.schemaContext) }), ); }

Automatic Registration on IModelConnection Open

The recommended approach is to automatically register the provider when any IModelConnection opens:

Automatic registration via IModelConnection.onOpen
/** Register SchemaUnitProvider automatically when IModelConnection opens */ export function setupIModelConnectionListener() { IModelConnection.onOpen.addListener(async (iModelConnection: IModelConnection) => { await IModelApp.quantityFormatter.setUnitsProvider( createUnitsProvider({ primary: new SchemaUnitProvider(iModelConnection.schemaContext) }), ); }); }

If errors occur while configuring the units provider, they are caught within the QuantityFormatter.setUnitsProvider method, and the code reverts back to BasicUnitsProvider.

Registering FormatsProvider

Using SchemaFormatsProvider

Register a SchemaFormatsProvider to load formats from iModel schemas:

Registering SchemaFormatsProvider on IModelConnection open
const removeIModelConnectionListener = IModelConnection.onOpen.addListener((iModel: IModelConnection) => { if (iModel.isBlankConnection()) return; // Don't register on blank connections. const schemaFormatsProvider = new SchemaFormatsProvider(iModel.schemaContext, IModelApp.quantityFormatter.activeUnitSystem); const removeUnitSystemListener = IModelApp.quantityFormatter.onActiveFormattingUnitSystemChanged.addListener((args) => { schemaFormatsProvider.unitSystem = args.system; }); iModel.onClose.addOnce(() => { removeUnitSystemListener(); }); IModelApp.formatsProvider = schemaFormatsProvider; }); IModelConnection.onClose.addOnce(() => { removeIModelConnectionListener(); IModelApp.resetFormatsProvider(); });

Using FormatSetFormatsProvider

For applications that persist user format preferences:

Registering FormatSetFormatsProvider with IModelApp
// This example, assume the application has a way to load format preferences from a remote source.. const retrievedFormatSet: FormatSet = await loadFormatSetFromPreferences(); // Create provider with optional fallback const fallbackProvider = new SchemaFormatsProvider(schemaContext, IModelApp.quantityFormatter.activeUnitSystem); IModelApp.quantityFormatter.onActiveFormattingUnitSystemChanged.addListener((args) => { fallbackProvider.unitSystem = args.system; }); const formatSetProvider = new FormatSetFormatsProvider({ formatSet: retrievedFormatSet, fallbackProvider }); // Register with IModelApp IModelApp.formatsProvider = formatSetProvider;

Adding Alternate Unit Labels

Add alternate unit labels for easier input during parsing:

Adding alternate unit labels
/** Add alternate unit labels for easier input during parsing */ export function addAlternateUnitLabels() { // Use "^" as an alternate label for degrees IModelApp.quantityFormatter.addAlternateLabels("Units.ARC_DEG", "^"); // Add alternate labels for feet IModelApp.quantityFormatter.addAlternateLabels("Units.FT", "feet", "foot"); }

Configuring Unit System

Set the active unit system for the QuantityFormatter:

Configuring unit system
/** Configure the unit system for the QuantityFormatter */ export async function configureUnitSystem() { // Set the active unit system (metric, imperial, usCustomary, or usSurvey) await IModelApp.quantityFormatter.setActiveUnitSystem("metric"); }

See Also

Last Updated: 02 October, 2026