Symbols define the non-geographic aspects of a graphic's appearance, including color, border width, transparency, and so on. The ArcGIS API for JavaScript includes many symbol classes, each of which allows you to specify symbology in a unique way. Each symbol type is also specific to one geometry type (that is, point, line, or polygon).

A renderer defines a set of symbols that will be used for graphics in a graphics layer. You can use renderers to symbolize features with different colors or sizes based on a particular attribute.

Creating Symbols

The following table lists the available symbols and the geometries to which they apply:

Create Marker Symbols

The ArcGIS.com map viewer provides a nice collection of marker symbols that can be used to symbolize features on your map. Click here to view a sample application that allows you to select a symbol and generate the code needed to draw the symbol.

To use this sample, just click a symbol and copy the resulting code for use in your application.

For picture marker symbols, the application provides two options for generating the image. You can reference the image directly through a URL, or you can embed a string representation of the image (base 64 option in the sample app). When using the latter option the image is stored within the document instead of as an external resource so no http requests need to be made to display the image. Some browsers, notably Internet Explorer prior to version 8, do not support using base-64 data URIs in these cases the image url is used.

Create Renderer

map.graphics.setRenderer(renderer);

The ArcGIS API for JavaScript includes the following renderers:

• Simple Renderer
• Class Breaks Renderer
• Unique Value Renderer

Simple Renderer

A simple renderer uses the same symbol for every graphic. All you have to do is specify the symbol to be used by the renderer, then apply the renderer to the graphics layer.

// legacy
var symbol = new esri.symbol.SimpleMarkerSymbol();
symbol.style = esri.symbol.SimpleMarkerSymbol.STYLE_SQUARE;
symbol.setSize(8); symbol.setColor(new dojo.Color([255,255,0,0.5]));
var renderer = new esri.renderer.SimpleRenderer(symbol);

// AMD
require([
  "esri/symbols/SimpleMarkerSymbol",
  "esri/renderers/SimpleRenderer",
  "dojo/_base/Color", ... ], function(SimpleMarkerSymbol, SimpleRenderer, Color, ... ){
  var symbol = new SimpleMarkerSymbol();
  symbol.style = SimpleMarkerSymbol.STYLE_SQUARE;
  symbol.setSize(8);
  symbol.setColor(new Color([255,255,0,0.5]));
  var renderer = new SimpleRenderer(symbol);
});

Class breaks renderer

A class breaks renderer symbolizes each graphic based on the value of some numeric attribute. Graphics with similar values for the attribute get the same symbol. The "breaks" define the values at which the symbology changes.

For example, suppose you have a "buildings" layer with an attribute that defines the building age. You want to symbolize buildings constructed since the year 2000 in green, buildings constructed between 1980 and 2000 in yellow, and buildings built before 1980 with red. This would be a good scenario for a class breaks renderer.

To define a class breaks renderer, you have to add breaks. Each break specifies the symbol to use and the minimum and maximum values that will be used for that symbol. The example below shows how you can explicitly define breaks:

// legacy
var renderer = new esri.renderer.ClassBreaksRenderer(symbol, "BUILD_DATE");
renderer.addBreak(-Infinity,1980, new esri.symbol.SimpleFillSymbol().setColor(new
    dojo.Color([255, 0, 0,0.5]))); renderer.addBreak(1980,2000,new esri.symbol.SimpleFillSymbol().setColor(new
    dojo.Color([255, 255, 0,0.5]))); renderer.addBreak(2000,Infinity,new esri.symbol.SimpleFillSymbol().setColor(new
    dojo.Color([0,255,0,0.5])));

// AMD
require([
    "esri/renderers/ClassBreaksRenderer",
    "esri/symbols/SimpleFillSymbol",
    "dojo/_base/Color", ... ], function(ClassBreaksRenderer, SimpleFillSymbol, Color, ... ){
  var renderer = new ClassBreaksRenderer(symbol, "BUILD_DATE");
  renderer.addBreak(-Infinity,1980, new SimpleFillSymbol().setColor(new
    Color([255, 0, 0,0.5]))); renderer.addBreak(1980,2000,new SimpleFillSymbol().setColor(new
	    Color([255, 255, 0,0.5]))); renderer.addBreak(2000,Infinity,new SimpleFillSymbol().setColor(new
	      Color([0,255,0,0.5])));
});

Notice that if there is no maximum limit on a break, you can use "Infinity" for the maximum value. Similarly, you can use "-Infinity" when there is no minimum.

Any value that is greater than or equal to the minimum will be included in the break. Any value that is less than the maximum will be included in the break. Thus, if you have two breaks 0 - 10 and 10 - 20, the value 10 would fall in the second break (10 - 20). Avoid creating overlapping breaks or gaps between breaks.

You can also define breaks mathematically. For example, you can do some basic arithmetic to ensure that each break falls an equal distance apart given the input data (sometimes known as an "equal interval" classification):

var numRanges = 10; var breaks = (max - min) / numRanges; . . . for (var
	  i=0; i<numRanges; i++) { renderer.addBreak(parseFloat(min + (i*breaks)),
	  parseFloat(min + ((i+1)*breaks)), new esri.symbol.SimpleMarkerSymbol().setSize((i+1)*5).setColor(colors[i]).setOutline(outline));
	  }

Although the ArcGIS JavaScript API cannot natively calculate classification schemes (such as quantile and natural breaks) you can find the break values by classifying the data in ESRI's ArcMap and manually entering the values in the addBreak method. Classifying your data in ArcMap can also help you extract useful RGB color values to use for your classes.

Unique value renderer

A unique value renderer symbolizes groups of graphics that have matching attributes. This is most common with nominal, or string data. For example, you could use a unique value renderer to symbolize zoning designations: yellow for "Residential", purple for "Industrial", red for "Commercial", and so on. You can also use unique value renderers on numeric fields that are coded values, or on ordinal attributes such as "First", "Second", "Third", and so on.

Defining a unique value renderer requires you to specify a default symbol and the attribute on which to base the symbology. Then you add values individually to the renderer and specify how each will be symbolized:

// legacy
var renderer = new esri.renderer.UniqueValueRenderer(defaultSymbol, "ZONING");
renderer.addValue("Residential", new esri.symbol.SimpleFillSymbol().setColor(new
dojo.Color([255,255,0,0.5]))); renderer.addValue("Industrial", new esri.symbol.SimpleFillSymbol().setColor(new
dojo.Color([128,0,128,0.5]))); renderer.addValue("Commercial", new esri.symbol.SimpleFillSymbol().setColor(new
dojo.Color([255,0,0,0.5])));

// AMD
require([
     "esri/renderers/UniqueValueRenderer",
     "esri/symbols/SimpleFillSymbol",
     "dojo/_base/Color", ... ], function(UniqueValueRenderer, SimpleFillSymbol, Color, ... ){
  var renderer = new UniqueValueRenderer(defaultSymbol, "ZONING");
  renderer.addValue("Residential", new SimpleFillSymbol().setColor(new
  Color([255,255,0,0.5]))); renderer.addValue("Industrial", new SimpleFillSymbol().setColor(new
  Color([128,0,128,0.5]))); renderer.addValue("Commercial", new SimpleFillSymbol().setColor(new
  Color([255,0,0,0.5])));
});

Values that you don't add to the list are drawn with the default symbol.