FieldConfiguration | API Reference | ArcGIS Maps SDK for JavaScript

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 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 when featureReduction (e.g., clustering) is enabled (e.g., clustering).
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 property is used for date and number formatting when applied to unsupported layer types or contexts.
When displaying date/time fields, set the timeStyle property to either long or full if the view’s 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

FieldConfiguration Constructor new FieldConfiguration(properties)

Parameter

properties Object

optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

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

Show inherited properties

Hide inherited properties

Type	Summary	Class
String\|null\|undefined	The alias (or display name) for the field.	FieldConfiguration
String	The name of the class.	Accessor
DateTimeFieldFormat\|NumberFieldFormat\|null\|undefined	The format of the field.	FieldConfiguration
String	The name of the field as defined by the feature layer.	FieldConfiguration

Property Details

alias Property alias 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

FeatureLayer.getFieldAlias()

declaredClass Inherited Property declaredClass Stringreadonly Inherited from Accessor

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

fieldFormat Property fieldFormat DateTimeFieldFormat |NumberFieldFormat |null |undefinedautocast

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 name String

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

Method Overview

Show inherited methods

Hide inherited methods

Return Type	Summary	Class
	Adds one or more handles which are to be tied to the lifecycle of the object.	Accessor
this	Creates a deep clone of this object.	FieldConfiguration
*\|null\|undefined	Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product.	FieldConfiguration
Boolean	Returns true if a named group of handles exist.	Accessor
	Removes a group of handles owned by the object.	Accessor
Object	Converts an instance of this class to its ArcGIS portal JSON representation.	FieldConfiguration

Method Details

addHandles Inherited Method addHandles(handleOrHandles, groupKey) Inherited from Accessor

Adds one or more handles which are to be tied to the lifecycle of the object. The handles will be removed when the object is destroyed.

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

this.addHandles(handle);

// Destroy the object
this.destroy();

Parameters

handleOrHandles WatchHandle|WatchHandle []

Handles marked for removal once the object is destroyed.

groupKey *

optional

Key identifying the group to which the handles should be added. All the handles in the group can later be removed with Accessor.removeHandles(). If no key is provided the handles are added to a default group.

clone Method clone(){this}

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

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

fromJSON Method fromJSON(json){* |null |undefined}static

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.

Parameter

json Object

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

Type	Description
* \| null \| undefined	Returns a new instance of this class.

hasHandles Inherited Method hasHandles(groupKey){Boolean} Inherited from Accessor

Returns true if a named group of handles exist.

Parameter

groupKey *

optional

A group key.

Returns

Type	Description
Boolean	Returns `true` if a named group of handles exist.

Example

// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

removeHandles Inherited Method removeHandles(groupKey) Inherited from Accessor

Removes a group of handles owned by the object.

Parameter

groupKey *

optional

A group key or an array or collection of group keys to remove.

Example

obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

toJSON Method toJSON(){Object}

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

Returns

Type	Description
Object	The ArcGIS portal JSON representation of an instance of this class.