Feature layer

Version 3.7

Feature layers are used to display features from one single layer of either a feature or map service. The layer can be either a spatial layer or non-spatial table. The ArcGIS API for Flex version 2.0 and above offers a FeatureLayer for working with client-side graphic features. You may be familiar with the GraphicsLayer from previous releases. The feature layer inherits from the graphics layer and offers additional capabilities such as the ability to perform queries and selections. Feature layers are also used for web editing if based on a layer in a feature service.

Feature layers differ from tiled and dynamic map service layers because they bring geometry information across to the client computer to be drawn by the client. Feature layers potentially cut down on round-trips to the server. A client can request the features it needs, then perform selections and queries on those features without having to request more information from the server. Feature layers are especially appropriate for layers that respond to user interaction, such as a mouse click or hover.

A feature layer honors any definition queries, scale dependencies, and other properties configured on the layer in the map service. Using a feature layer, you can access related tables, perform queries, display periods of time, and work with feature attachments.

How do I create a feature layer?

A feature layer references a single layer from either a map service or a feature service. The feature service is required for editing, but both will honor any feature templates configured in the source map document as long as you connect to an ArcGIS 10.0 service or higher. For earlier versions of ArcGIS for Server, no symbology can be retrieved from the server, but you can still use it with a feature layer.

Choosing the display mode

When you create a feature service, you also need to specify one of these modes for retrieving features:

  • On demand mode (the default) retrieves features as they are needed, requesting only the features within your current view extent. On demand mode potentially requires more round trips between the client and server. However, it protects you from retrieving more features than you need.
  • Snapshot mode retrieves all the features from the layer immediately after the layer is added to the map. This reduces subsequent traffic to the server, but can become cumbersome if the layer contains many features. The browser may be overwhelmed by the number of features it needs to draw, or the service may reach its limit of how many features it can return at once. The default is 500 for ArcGIS 9.3.1 and 1,000 for ArcGIS 10.x.

    Use snapshot mode primarily with smaller datasets or with temporal data.

  • Selection mode does not initially request any features. Features are added only when a selection is made. This mode is useful when you cannot or do not want to bring all features into the client, but you want to highlight one or more features for a certain reason, for example, editing, querying, or accessing related tables. Selections are drawn using a client-side selection color that you specify on the feature layer.

    Two common examples for using Selection mode:

    1. Query: you can use a dynamic service for your general map representation, but when doing an identify or query you want to highlight the selected features.
    2. Editing: only the selected feature will be highlighted on the map within the feature layer. Once editing is complete, the selection is removed from the feature layer and the user can update the dynamic map service layer to see the updated feature.


No matter which of the display modes you choose for your feature layer, selected features are always held on the client. For example, if you are using the on demand display mode and you have selected some features, panning away from those selected features will still result in the features being available on the client. Your application will not have to reselect the features or make any other request to the server if you pan back to the original area. For this reason, it is a good practice to clear your selected features once they are no longer needed.

Choosing the attributes you need

Feature layers retrieve both feature geometries and attribute information. When you create the feature layer, you can set the outFields property to specify which attributes will be retrieved for your features. It is possible to use the asterisk (*) to get all the fields, but to reduce the amount of information sent between the client and server, you should request only the fields you need in your application. If you later perform a query using the feature layer, the query will honor the outfields you set.

What can I do with a feature layer?

Feature layers make it possible for you to do all of the following:


Feature layers are the key to editing features with the web APIs. The editing components included in the APIs are designed to work with feature layers. You can only perform editing on feature layers that reference an editable layer within a feature service. See Editing to learn more about this requirement and how to create a feature service.

Definition expressions

There may be times where you want to work with features that satisfy certain attribute criteria and disregard the rest. In this type of situation, you can set a definition expression on the feature layer to retrieve just the features you need. Every feature layer has a definitionExpression property, which comes from the definition query set in the source map document.


When using a feature layer in snapshot mode, you can retrieve features that meet a certain temporal criteria using the timeDefinition property on the feature layer. This property temporarilty defines the features in the layer to match a specified TimeExtent. This option is only available with features loaded in snapshot mode. For example, you might want to only load houses that were built before 1930. You would set the feature layer's timeDefinition to a TimeExtent prior to 1930.


This option is only available with features loaded in snapshot mode.

You can track and render observations using a feature layer as well. The TemporalRenderer renderer can highlight the latest observation and render a group of individual features within a feature layer. This renderer uses the time field set on the feature layer. See Symbols and Renderers for additional discussion on temporal renderers.

The feature layer also has a FeatureCollection property. This property is used when you want to initialize the feature layer with a collection of features originating outside of ArcGIS Server. See the sample Time Rendered 5k run (gpx) which uses the feature layer's property to pass in GPX data to a feature layer.

Selection and display

The feature layer supports a selection, which represents a subset of features that the user has chosen to isolate for viewing, editing, or analytical purposes. Users can add or remove features from the selection based on spatial or attribute criteria. The feature layer makes it easy to draw the selection set with a different type of symbol than the other features. If you don't specify the symbol, a default symbol will be applied. This was previously challenging to do without using two graphics layers.

A selection set can be used as input for statistical calculations, geoprocessing tools, and graphing. Therefore, opening the possibility for interactive GIS analysis and exploration. For example, users can draw a polygon to select a set of buildings, then push a button to calculate the solar potential of those buildings. Selections also play an important role in some editing workflows where the feature currently undergoing edits is highlighted.

To make your selection, use the selectFeatures method on feature layer which takes a query object as an argument. If you are interested in querying your feature layer without adding the results to the selection set, you can use either queryFeatures or queryRelatedFeatures instead. With any of these methods, you cannot request features outside of any definition expressions set in the map document or on the feature layer.


The ArcGIS API for Flex has several samples that show how to work with feature layers. Here are a few you may find useful: