Get started with graphics

Graphics are an essential component of the ArcGIS API for JavaScript. You can use them to display locations on a map with simple symbols or for displaying the results of a Query or other task. The more comfortable you are with working with graphics, the more fluent you will become in working with geometries, layers, tasks, and Popups.

This tutorial will show you how to add simple graphics to a map, style them with a custom symbol, and add attributes to them.

Prior to completing the following steps, you should be familiar with views and Map. If necessary, complete the following tutorials first:

• Get started with MapView
• Get started with SceneView

1. Create a simple map

First create a simple Map and reference it in a View. Your JavaScript may look something like the code below:

require([
  "esri/Map",
  "esri/views/MapView",
  "dojo/domReady!"
], function(
  Map,
  MapView
) {

  // Create the Map
  var map = new Map({
    basemap: "hybrid"
  });

  // Create the MapView
  var view = new MapView({
    container: "viewDiv",
    map: map,
    center: [-80, 35],
    zoom: 3
  });
});

2. Learn the properties of a graphic

Each graphic has the four main properties:

The remaining steps will walk you through how to work with each one of these properties.

3. Create a line geometry

We want to add a line graphic to our map showing a generalized version of the proposed location of the Keystone Pipeline.

Require the Polyline module and create a new polyline geometry representing this location. You will use the paths property to add vertices to the line.

require([
  "esri/Map",
  "esri/views/MapView",
  "esri/geometry/Polyline",
  "dojo/domReady!"
], function(
  Map,
  MapView,
  Polyline
) {

  //
  // This is where you created a Map and MapView in the previous steps
  //

  // Create a line geometry with the coordinates of the line
  var polyline = new Polyline({
    paths: [
      [-111.30, 52.68],
      [-98, 49.5],
      [-93.94, 29.89]
    ]
  });
});

4. Create a line symbol

Now that you have a geometry for the location of the pipeline, you need a symbol to render the line in the view. Require the SimpleLineSymbol module and create a line symbol for the pipeline.

require([
  "esri/Map",
  "esri/views/MapView",
  "esri/geometry/Polyline",
  "esri/symbols/SimpleLineSymbol",
  "dojo/domReady!"
], function(
  Map,
  MapView,
  Polyline,
  SimpleLineSymbol
) {

  //
  // This is where you created a Map, MapView,
  // and geometry in the previous steps
  //

  // Create a simple line symbol for rendering the line in the view
  var lineSymbol = new SimpleLineSymbol({
    color: [226, 119, 40],  // RGB color values as an array
    width: 4
  });
});

5. Create attributes to store in the graphic

Attributes can provide key information about the graphic that can enhance the usefulness of your application. In this step, we'll add three basic attributes to the line graphic: name, owner, length.

require([
  "esri/Map",
  "esri/views/MapView",
  "esri/geometry/Polyline",
  "esri/symbols/SimpleLineSymbol",
  "dojo/domReady!"
], function(
  Map,
  MapView,
  Polyline,
  SimpleLineSymbol
) {

  //
  // This is where you created a Map, MapView,
  // geometry, and symbol in the previous steps
  //

  // Create a simple object containing useful information relating to the feature
  var lineAtt = {
    Name: "Keystone Pipeline",  // The name of the pipeline
    Owner: "TransCanada",  // The owner of the pipeline
    Length: "3,456 km"  // The length of the pipeline
  };
});

6. Create a graphic and assign its geometry, symbol and attributes

Require the Graphic module, create the graphic, and add it to the graphics property on the MapView

require([
  "esri/Map",
  "esri/views/MapView",
  "esri/geometry/Polyline",
  "esri/symbols/SimpleLineSymbol",
  "esri/Graphic",
  "dojo/domReady!"
], function(
  Map,
  MapView,
  Polyline,
  SimpleLineSymbol,
  Graphic
) {

  //
  // This is where you created a Map, MapView,
  // geometry, symbol, and attributes in the previous steps
  //

  // Create the graphic
  var polylineGraphic = new Graphic({
    geometry: polyline,   // Add the geometry created in step 4
    symbol: lineSymbol,   // Add the symbol created in step 5
    attributes: lineAtt   // Add the attributes created in step 6
  });

  // Add the graphic to the view's default graphics view
  // If adding multiple graphics, use addMany and pass in the array of graphics.
  view.graphics.add(polylineGraphic);
});

7. Add a PopupTemplate to the graphic

Popups can give users access to all the attributes in a graphic. Setting a simple PopupTemplate will allow users to view the attributes of the feature when it is clicked in the view. For more information about how to work with Popups and PopupTemplate, see the Get started with popups tutorial and other Popup samples.

Add a new PopupTemplate to the graphic. This step must either be done in the constructor for the graphic or prior to adding the graphic to the GraphicsLayer.

require([
  "esri/Map",
  "esri/views/MapView",
  "esri/geometry/Polyline",
  "esri/symbols/SimpleLineSymbol",
  "esri/Graphic",
  "dojo/domReady!"
], function(
  Map,
  MapView,
  Polyline,
  SimpleLineSymbol,
  Graphic
) {

  //
  // This is where you created a Map, MapView,
  // geometry, symbol, and attributes in the previous steps
  //

  // Create the graphic
  var polylineGraphic = new Graphic({
    geometry: polyline,   // Add the geometry created in step 4
    symbol: lineSymbol,   // Add the symbol created in step 5
    attributes: lineAtt,  // Add the attributes created in step 6
    popupTemplate: {
      title: "{Name}",
      content: [{
        type: "fields",
        fieldInfos: [{
          fieldName: "Name"
        }, {
          fieldName: "Owner"
        }, {
          fieldName: "Length"
        }]
      }]
    }
  });

  // Add the graphic to the view's default graphics view
  view.graphics.add(polylineGraphic);
});

8. Conclusion

Now you have a simple map showing the location of the Keystone pipeline. You can click the line and view the attributes you added to the graphic.

Your final JavaScript code should look like the following:

require([
  "esri/Map",
  "esri/views/MapView",
  "esri/geometry/Polyline",
  "esri/symbols/SimpleLineSymbol",
  "esri/Graphic",
  "esri/PopupTemplate",
  "dojo/domReady!"
], function(
  Map,
  MapView,
  Polyline,
  SimpleLineSymbol,
  Graphic,
  PopupTemplate
) {

  var map = new Map({
    basemap: "hybrid"
  });

  var view = new MapView({
    center: [-80, 35],
    container: "viewDiv",
    map: map,
    zoom: 3
  });

  // First create a line geometry (this is the Keystone pipeline)
  var polyline = new Polyline({
    paths: [
      [-111.30, 52.68],
      [-98, 49.5],
      [-93.94, 29.89]
    ]
  });

  // Create a symbol for drawing the line
  var lineSymbol = new SimpleLineSymbol({
    color: [226, 119, 40],
    width: 4
  });

  // Create an object for storing attributes related to the line
  var lineAtt = {
    Name: "Keystone Pipeline",
    Owner: "TransCanada",
    Length: "3,456 km"
  };

  /*******************************************
   * Create a new graphic and add the geometry,
   * symbol, and attributes to it. You may also
   * add a simple PopupTemplate to the graphic.
   * This allows users to view the graphic's
   * attributes when it is clicked.
   ******************************************/
  var polylineGraphic = new Graphic({
    geometry: polyline,
    symbol: lineSymbol,
    attributes: lineAtt,
    popupTemplate: {
      title: "{Name}",
      content: [{
        type: "fields",
        fieldInfos: [{
          fieldName: "Name"
        }, {
          fieldName: "Owner"
        }, {
          fieldName: "Length"
        }]
      }]
    }
  });

  // Add the line graphic to the view's GraphicsLayer
  view.graphics.add(polylineGraphic);
});

Adding graphics to a GraphicsLayer is convenient when working with features of various geometry types. If working exclusively with graphics of the same geometry type, however, we recommend you use a client-side FeatureLayer to take advantage of its rendering and querying capabilities. See the Create a FeatureLayer with client side graphics sample for an example of how to do this.