API Reference › core-frontend› QuantityFormatting › QuantityFormatter

QuantityFormatter Class

The QuantityFormatter class provides methods for formatting and parsing quantities. There are a set of standard quantity types identified by the QuantityType enum. CustomQuantityTypeDefinition can be registered to extend the available quantity types available by frontend tools. The QuantityFormatter also allows the default formats to be overriden.

Implements

Methods

Name Description
constructor(showMetricOrUnitSystem?: boolean | UnitSystemKey): QuantityFormatter constructor  
[dispose](): void    
addAlternateLabels(key: string, ...labels: string[]): void Add one or more alternate labels for a unit - these labels are used during string parsing.  
addFormattingSpecsToRegistry(args: AddFormattingSpecArgs): Promise<void> Populates the registry with a new FormatterSpec and ParserSpec entry for the given format name.  
clearAllOverrideFormats(): Promise<void> Clear formatting override for all quantity types, but only for the "active" Unit System.  
clearOverrideFormats(type: QuantityTypeArg): Promise<void> Clear any formatting override for specified quantity type, but only for the "active" Unit System.  
createFormatterSpec(props: CreateFormattingSpecProps): Promise<FormatterSpec> Creates a FormatterSpec for a given persistence unit name and format properties, using the UnitsProvider to resolve the persistence unit.  
createParserSpec(props: CreateFormattingSpecProps): Promise<ParserSpec> Creates a ParserSpec for a given persistence unit name and format properties, using the UnitsProvider to resolve the persistence unit.  
findFormatterSpecByQuantityType(type: QuantityTypeArg, _unused?: boolean): undefined | FormatterSpec Synchronous call to get a FormatterSpec of a QuantityType.  
findParserSpecByQuantityType(type: QuantityTypeArg): undefined | ParserSpec Synchronous call to get a ParserSpec for a QuantityType.  
findUnit(unitLabel: string, schemaName?: string, phenomenon?: string, unitSystem?: string): Promise<UnitProps> Find [UnitProp] for a specific unit label.  
findUnitByName(unitName: string): Promise<UnitProps> Find [UnitProp] for a specific unit name.  
formatQuantity(props: { kindOfQuantityName: string, value: number, valueUnitName: string }): Promise<string> Generates a formatted string asynchronously for a quantity given the provided properties.  
formatQuantity(magnitude: number, formatSpec?: FormatterSpec): string Generates a formatted string for a quantity given its format spec.  
generateFormatterSpecByType(type: QuantityTypeArg, formatProps: FormatProps): Promise<FormatterSpec> Asynchronous Call to get a FormatterSpec for a QuantityType.  
getConversion(fromUnit: UnitProps, toUnit: UnitProps): Promise<UnitConversionProps> Returns data needed to convert from one Unit to another in the same Unit Family/Phenomenon.  
getFormatPropsByQuantityType(quantityType: QuantityTypeArg, requestedSystem?: UnitSystemKey, ignoreOverrides?: boolean): undefined | FormatProps Get the cached FormatProps give a quantity type.  
getFormatSpecHandle(koqName: string, persistenceUnit: string, system?: UnitSystemKey): FormatSpecHandle Create a cacheable handle to formatting specs for a specific KoQ and persistence unit.  
getFormatterSpecByQuantityType(type: QuantityTypeArg, isImperial?: boolean): Promise<undefined | FormatterSpec> Asynchronous Call to get a FormatterSpec for a QuantityType.  
getFormatterSpecByQuantityTypeAndSystem(type: QuantityTypeArg, system?: UnitSystemKey): Promise<undefined | FormatterSpec> Asynchronous Call to get a FormatterSpec for a QuantityType and a Unit System.  
getParserSpecByQuantityType(type: QuantityTypeArg, isImperial?: boolean): Promise<undefined | ParserSpec> Asynchronous Call to get a ParserSpec for a QuantityType.  
getParserSpecByQuantityTypeAndSystem(type: QuantityTypeArg, system?: UnitSystemKey): Promise<undefined | ParserSpec> Asynchronous Call to get a ParserSpec for a QuantityType.  
getQuantityDefinition(type: QuantityTypeArg): undefined | QuantityTypeDefinition Return QuantityTypeDefinition if type has been registered.  
getQuantityTypeKey(type: QuantityTypeArg): string Converts a QuantityTypeArg into a QuantityTypeKey/string value that can be used to lookup custom and standard quantity types.  
getSpecsByName(name: string): undefined | ReadonlyMap<string, FormattingSpecEntry> Returns a map of FormattingSpecEntry keyed by persistence unit for a given name, typically a KindOfQuantity full name.  
getSpecsByNameAndUnit(args: FormattingSpecArgs): undefined | FormattingSpecEntry Returns a FormattingSpecEntry for a given name and persistence unit.  
getUnitsByFamily(phenomenon: string): Promise<UnitProps[]> Returns all defined units for the specified Unit Family/Phenomenon.  
getUnitSystemFromString(inputSystem: string, fallback?: UnitSystemKey): UnitSystemKey Get a UnitSystemKey from a string that may have been entered via a key-in.  
hasActiveOverride(type: QuantityTypeArg, checkOnlyActiveUnitSystem?: boolean): boolean Return true if the QuantityType is using an override format.  
initializeQuantityTypesRegistry(): Promise<void> Protected Method used to register all QuantityTypes defined in QuantityType enum.  
parseToQuantityValue(props: { kindOfQuantityName: string, value: string, valueUnitName: string }): Promise<QuantityParseResult> Parse input string asynchronously into a quantity given the provided properties.  
parseToQuantityValue(inString: string, parserSpec?: ParserSpec): QuantityParseResult Parse input string into quantity given the ParserSpec  
registerQuantityType(entry: CustomQuantityTypeDefinition, replace?: boolean): Promise<boolean> Async call to register a CustomQuantityType and load the FormatSpec and ParserSpec for the new type.  
reinitializeFormatAndParsingsMaps(overrideFormatPropsByUnitSystem: Map<UnitSystemKey, Map<string, FormatProps>>, unitSystemKey?: UnitSystemKey, fireUnitSystemChanged?: boolean, startDefaultTool?: boolean): Promise<void> Reinitialize caches.  
resetToUseInternalUnitsProvider(): Promise<void> Async call typically used after an iModel is closed to reset the UnitsProvider to the default one  
setActiveUnitSystem(isImperialOrUnitSystem: boolean | UnitSystemKey, restartActiveTool?: boolean): Promise<void> Set the Active unit system to one of the supported types.  
setOverrideFormat(type: QuantityTypeArg, overrideFormat: FormatProps): Promise<void> Set Override Format for a quantity type, but only in the "active" Unit System.  
setOverrideFormats(type: QuantityTypeArg, overrideEntry: OverrideFormatEntry): Promise<void> Set formatting override for specified quantity type, but only for the "active" Unit System.  
setUnitFormattingSettingsProvider(provider: UnitFormattingSettingsProvider): Promise<void> Set the settings provider and if not iModel specific initialize setting for user.  
setUnitsProvider(unitsProvider: UnitsProvider): Promise<void> Async method to set a units provider and reload caches.  

Properties

Name Type Description
_activeFormatSpecsByType Protected Map<string, FormatterSpec> Map of FormatSpecs for all available QuantityTypes, keyed by quantity type  
_activeParserSpecsByType Protected Map<string, ParserSpec> Map of ParserSpecs for all available QuantityTypes, keyed by quantity type  
_activeUnitSystem Protected UnitSystemKey Active UnitSystem key - must be one of "imperial", "metric", "usCustomary", or "usSurvey".  
_formatSpecsRegistry Protected Map<string, Map<string, Map<UnitSystemKey, FormattingSpecEntry>>> Registry containing available FormatterSpec and ParserSpec, mapped by keys.  
_overrideFormatPropsByUnitSystem Protected Map<UnitSystemKey, Map<string, FormatProps>> Map of FormatSpecs that have been overriden from the default.  
_quantityTypeRegistry Protected Map<string, QuantityTypeDefinition> Registry containing available quantity type definitions.  
_unitFormattingSettingsProvider Protected undefined | UnitFormattingSettingsProvider Optional object that gets called to store and retrieve format overrides.  
activeUnitSystem Accessor ReadOnly UnitSystemKey Retrieve the active UnitSystemKey which is used to determine what formats are to be used to display quantities  
alternateUnitLabelsProvider Accessor ReadOnly AlternateUnitLabelsProvider Return the class the contain map of all alternate labels for units.  
isReady Accessor ReadOnly boolean Whether the QuantityFormatter has completed at least one successful reload and is ready to format/parse.  
onActiveFormattingUnitSystemChanged Readonly BeUiEvent<FormattingUnitSystemChangedArgs> Called after the active unit system is changed.  
onBeforeFormattingReady Readonly BeEvent<(collector: FormattingReadyCollector) => void> Event for formatting providers to register async work before the formatter signals ready.  
onFormattingReady Readonly BeUnorderedUiEvent<void> Fired after every reload path completes (initialization, unit system change, provider change, reinitialize).  
onQuantityFormatsChanged Readonly BeUiEvent<QuantityFormatsChangedArgs> Called when the format of a QuantityType is overriden or the override is cleared.  
onUnitsProviderChanged Readonly BeUiEvent<void> Fired when the active UnitsProvider is updated.  
quantityTypesRegistry Accessor ReadOnly Map<string, QuantityTypeDefinition> Return a map that serves as a registry of all standard and custom quantity types.  
unitsProvider Accessor UnitsProvider Get/Set the active UnitsProvider class.  
unitsProvider Setter unitsProvider(unitsProvider: UnitsProvider): void    
whenInitialized Accessor ReadOnly Promise<void> A promise that resolves after the first successful initialization.  

Defined in

Last Updated: 25 April, 2026