Skip to content
import FieldConfiguration from "@arcgis/core/layers/support/FieldConfiguration.js";
Inheritance:
FieldConfigurationAccessor
Since
ArcGIS Maps SDK for JavaScript 4.34

The FieldConfiguration class defines how fields in a layer are displayed and formatted within widgets and UI components. It provides a standardized way to customize field presentation, including display names, alias, and formatting rules for numbers and dates. Using field configurations ensures consistent formatting across components that consume the layer's data.

Previously, field information was defined using FieldInfo objects. Although compatibility with FieldInfo is maintained for existing applications, FieldConfiguration is the preferred pattern for new development and for updating existing code.

Field configurations are typically assigned to a layer's FeatureLayer.fieldConfigurations property before initializing components such as FeatureTable or Popup components. Configurations are created with the FieldConfiguration class, where the fieldFormat property can be set to either a DateTimeFieldFormat or NumberFieldFormat object, depending on the field type.

Note that field configurations affect only how field values are displayed in the UI. They do not modify the underlying data in the feature layer.

Known Limitations and Considerations:

  • Field configuration support is currently limited to feature service-based FeatureLayer instances, including tables. Additional layer types and data sources, such as client-side graphics or feature collections, are not supported at this time. Support for additional layer types is planned for future releases.
  • Field configurations are not supported in expression or relationship contexts in Arcade expressions. For example, fields referenced as expression/abc123 or relationships/0/field do not currently support field configurations.
  • The FieldInfo.format property is used for date and number formatting when applied to unsupported layer types or contexts.
  • When displaying date/time fields, set the DateTimeFieldFormat.timeStyle property to either long or full if the view’s MapView.timeZone is set to unknown and the field includes time information.
See also
Examples
// Create a number field format
const numberFormat = new NumberFieldFormat ({
minimumFractionDigits: 2,
maximumFractionDigits: 4,
useGrouping: "always"
});
// Create a field configuration object containing the number format
const numFieldConfiguration = new FieldConfiguration ({
name: "lat", // name of the field in the service
fieldFormat: numberFormat,
alias: "Latitude"
});
// Create a date-time field format
const dateTimeFormat = new DateTimeFieldFormat ({
dateStyle: "medium",
timeStyle: "short",
hour12: "never"
});
// Create a field configuration object containing the date format
const dateFieldConfiguration = new FieldConfiguration ({
name: "collectionDate", // name of the field in the service
fieldFormat: dateTimeFormat,
alias: "Date Collected"
});
// Create a feature layer and pass in the field configurations
const featureLayer = new FeatureLayer ({
url: "url to feature layer",
outFields: ["*"],
fieldConfigurations: [numFieldConfiguration, dateFieldConfiguration] // add as many field configurations as needed
});
// Adding a new field configuration
const addNewConfig = (layer, fieldName, alias,
fieldFormat) => {
const existingConfig = layer.getFieldConfiguration(fieldName);
if (!existingConfig) {
const newConfig = new FieldConfiguration ({ name: fieldName, alias, fieldFormat });
const newConfigs = clone(layer.fieldConfigurations);
newConfigs.push(newConfig);
layer.fieldConfigurations = newConfigs;
}
};
// Updating an existing field configuration
const updateConfig = (layer, fieldName, alias,
fieldFormat) => {
const existingConfig = layer.getFieldConfiguration(fieldName);
if (existingConfig) {
const newConfig = existingConfig.clone();
newConfig.alias = alias;
newConfig.fieldFormat = fieldFormat;
const index = layer.fieldConfigurations.indexOf(existingConfig);
const newConfigs = clone(layer.fieldConfigurations);
newConfigs[index] = newConfig;
layer.fieldConfigurations = newConfigs;
}
};
// Deleting an existing field configuration
const deleteConfig = (layer, fieldName) => {
const existingConfig = layer.getFieldConfiguration(fieldName);
if(existingConfig) {
const index = layer.fieldConfigurations.indexOf(existingConfig);
var newConfigs = clone(layer.fieldConfigurations);
newConfigs.splice(index, 1);
layer.fieldConfigurations = newConfigs;
}
};

Constructors

Constructor

Constructor
Parameters
ParameterTypeDescriptionRequired
properties
See the properties table for a list of all the properties that may be passed into the constructor.

Properties

Any properties can be set, retrieved or listened to. See the Watch for changes topic.

alias

Property
Type
string | null | undefined

The alias (or display name) for the field. This is used in place of the field name when displaying the field in a widget or UI component. If not specified, the field's Field.alias is used. If the layer does not define an alias for the field, the field name itself is used.

See also

declaredClass

readonlyinherited Property
Type
string
Inherited from: Accessor

The name of the class. The declared class name is formatted as esri.folder.className.

fieldFormat

autocast Property
Type
FieldFormatUnion | null | undefined

The format of the field. This can be either a DateTimeFieldFormat or NumberFieldFormat object. This is dependent upon the type of field.

See also
Example
const fieldConfig = new FieldConfiguration({
"name": "install_date",
"alias": "Date of Installation",
"fieldFormat": { // Autocast to DateTimeFieldFormat
"type": "date-time",
"dateStyle": "short",
"timeStyle": "medium"
}
});

name

Property
Type
string

The name of the field as defined by the feature layer.

Methods

MethodSignatureClass
fromJSON
inherited static
fromJSON(json: any): any
clone
inherited
clone(): this
toJSON
inherited
toJSON(): any

fromJSON

inheritedstatic Method
Signature
fromJSON (json: any): any
Inherited from: JSONSupportMixin

Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product. The object passed into the input json parameter often comes from a response to a query operation in the REST API or a toJSON() method from another ArcGIS product. See the Using fromJSON() topic in the Guide for details and examples of when and how to use this function.

Parameters
ParameterTypeDescriptionRequired
json
any

A JSON representation of the instance in the ArcGIS format. See the ArcGIS REST API documentation for examples of the structure of various input JSON objects.

Returns
any

Returns a new instance of this class.

clone

inherited Method
Signature
clone (): this
Inherited from: ClonableMixin

Creates a deep clone of this object. Any properties that store values by reference will be assigned copies of the referenced values on the cloned instance.

Returns
this

A deep clone of the class instance that invoked this method.

toJSON

inherited Method
Signature
toJSON (): any
Inherited from: JSONSupportMixin

Converts an instance of this class to its ArcGIS portal JSON representation. See the Using fromJSON() guide topic for more information.

Returns
any

The ArcGIS portal JSON representation of an instance of this class.