TextSymbol

AMD: require(["esri/symbols/TextSymbol"], (TextSymbol) => { /* code goes here */ });
ESM: import TextSymbol from "@arcgis/core/symbols/TextSymbol";
Class: esri/symbols/TextSymbol
Inheritance: TextSymbol Symbol Accessor
Since: ArcGIS API for JavaScript 4.0

Text symbols are used to define the graphic for displaying labels on a FeatureLayer, CSVLayer, Sublayer, and StreamLayer in a 2D MapView. Text symbols can also be used to define the symbol property of Graphic if the geometry type is Point or Multipoint. With this class, you may alter the color, font, halo, and other properties of the label graphic.

TextSymbol may be used to label Point, Polyline, or Polygon features. The image below depicts a polygon FeatureLayer that uses a TextSymbol to label its features.

text-sample

See also
Example
let textSymbol = {
  type: "text",  // autocasts as new TextSymbol()
  color: "white",
  haloColor: "black",
  haloSize: "1px",
  text: "You are here",
  xoffset: 3,
  yoffset: 3,
  font: {  // autocasts as new Font()
    size: 12,
    family: "Josefin Slab",
    weight: "bold"
  }
};

Constructors

new TextSymbol(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 Working with Properties topic.
Show inherited properties Hide inherited properties
Name Type Summary Class
Number

The angle of the text.

more details
TextSymbol
Color

The background color of the label's bounding box.

more details
TextSymbol
Color

The border color of the label's bounding box.

more details
TextSymbol
Number

The border size or width of the label's bounding box.

more details
TextSymbol
Color

The color of the symbol.

more details
Symbol
String

The name of the class.

more details
Accessor
Font

The Font used to style the text.

more details
TextSymbol
Color

The color of the text symbol's halo.

more details
TextSymbol
Number

The size in points of the text symbol's halo.

more details
TextSymbol
String

Adjusts the horizontal alignment of the text in multi-lines.

more details
TextSymbol
Boolean

Determines whether to adjust the spacing between characters in the text string.

more details
TextSymbol
Number

The height of the space between each line of text.

more details
TextSymbol
Number

The maximum length in points for each line of text.

more details
TextSymbol
Boolean

Determines whether every character in the text string is rotated.

more details
TextSymbol
String

The text string to display in the view.

more details
TextSymbol
String For TextSymbol the type is always "text". more detailsTextSymbol
String

Adjusts the vertical alignment of the text.

more details
TextSymbol
Number

The offset on the x-axis in points.

more details
TextSymbol
Number

The offset on the y-axis in points.

more details
TextSymbol

Property Details

angle Number

The angle of the text. 0 is horizontal and the angle moves clockwise.

Known Limitations

This property is currently not supported in 3D SceneViews.

Default Value:0
Example
const textSymbol = {
  type: "text", // autocasts as new TextSymbol()
  angle: 90,
  color: "green",
  font: {
    // autocast as new Font()
    family: "Just Another Hand",
    size: 12
  },
  haloColor: "black",
  haloSize: 1,
  horizontalAlignment: "right",
  verticalAlignment: "bottom"
};
backgroundColor Colorautocast
Autocasts from Object|Number[]|String

The background color of the label's bounding box. This property is only supported for MapImageLayer.

See also
borderLineColor Colorautocast
Autocasts from Object|Number[]|String

The border color of the label's bounding box. This property is only supported for MapImageLayer.

See also
borderLineSize Number

The border size or width of the label's bounding box. This property is only supported for MapImageLayer.

See also
Autocasts from Object|Number[]|String

The color of the symbol. This can be autocast with an array of rgb(a) values, named string, hex string or an hsl(a) string, an object with r, g, b, and a properties, or a Color object.

Default Value:black
Examples
// CSS color string
symbol.color = "dodgerblue";
// HEX string
symbol.color = "#33cc33";
// array of RGBA values
symbol.color = [51, 204, 51, 0.3];
// object with rgba properties
symbol.color = {
  r: 51,
  g: 51,
  b: 204,
  a: 0.7
};
declaredClass Stringreadonly inherited
Since: ArcGIS API for JavaScript 4.7

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

The Font used to style the text. This property allows the developer to set the font's family, decoration, size, style, and weight properties.

See the Labeling guide page for more information and known limitations.

Known Limitations

See also
Example
let textSymbol = {
  type: "text",  // autocasts as new TextSymbol()
  text: "Science of Where",
  font: {  // autocasts as new Font()
    family: "Merriweather",
    size: 12,
    style: "italic",
    weight: "bold"
  }
};
haloColor Colorautocast
Autocasts from Object|number[]|string

The color of the text symbol's halo. To include a halo in the TextSymbol, you must also set the size of the halo in haloSize.

Known Limitations

  • Sub-pixel halo (i.e. fractional size such as 1.25px) renders inconsistently in various browsers.
Examples
// CSS color string
symbol.haloColor = "dodgerblue";
// HEX string
symbol.haloColor = "#33cc33";
// array of RGBA values
symbol.haloColor = [51, 204, 51, 0.3];
// object with rgba properties
symbol.haloColor = {
  r: 51,
  g: 51,
  b: 204,
  a: 0.7
};
haloSize Numberautocast
Autocasts from Number|String

The size in points of the text symbol's halo. This value may be autocast with a string expressing size in points or pixels (e.g. 12px). To include a halo in the TextSymbol, you must also set the color of the halo in haloColor.

Known Limitations

  • Sub-pixel halo (i.e. fractional size such as 1.25px) renders inconsistently in various browsers.
  • Halo size should not be 1/4 larger than the text size. For example, if your text size is 12, the halo size should not be larger than 3.
Examples
// haloSize in points
symbol.haloSize = 1;
// haloSize in pixels
symbol.haloSize = "2px";
// haloSize in points
symbol.haloSize = "1pt";
horizontalAlignment String

Adjusts the horizontal alignment of the text in multi-lines.

Known Limitations

  • This property only applies when TextSymbol is not used for labeling purposes. The horizontalAlignment for labels is inferred from the labelPlacement value.

Possible Values:"left"|"right"|"center"

Default Value:"center"
kerning Boolean

Determines whether to adjust the spacing between characters in the text string.

Default Value:true
lineHeight Number
Since: ArcGIS API for JavaScript 4.15

The height of the space between each line of text. Only applies to multiline text.

This property can be considered as a multiplier of the default value of 1.0 (e.g. a value of 2.0 will be two times the height of the default height). The range of possible values is: 0.1 - 4.0. If a value of 0 is specified, the default value of 1.0 will be used.

Default Value:1.0
Example
const textSymbol = {
  type: "text", // autocasts as new TextSymbol()
  color: "blue",
  haloColor: "white",
  haloSize: 1,
  lineHeight: 1.5
};
lineWidth Numberautocast
Autocasts from Number|String
Since: ArcGIS API for JavaScript 4.15

The maximum length in points for each line of text. This value may be autocast with a string expressing size in points or pixels (e.g. 72px).

The default value is 192 points. The range of possible values is: 32px - 512px.

If text extends farther than the lineWidth value, then the line will break at the whitespace before the text that extends past the limit if possible, and a new line will be created.

Known Limitations

  • This property is currently not supported in 3D SceneViews.
  • The default value is subject to change in future releases.
Default Value:192
Example
const textSymbol = {
  type: "text", // autocasts as new TextSymbol()
  color: "blue",
  haloColor: "white",
  haloSize: 1,
  lineWidth: 200
};
rotated Boolean

Determines whether every character in the text string is rotated.

Known Limitations

This property is currently not supported in 3D SceneViews.

Default Value:false
text String

The text string to display in the view. Long text strings will be split into multiple lines. The length of the line is controlled by the lineWidth property. To manually create a new line, use the \n escape character.

Known Limitations

This property only applies when TextSymbol is used to define the symbol property of a Graphic, and not for labeling purposes.

See also
Examples
symbol.text = "You are here";
symbol.text = "Wish you were \n here";
type Stringreadonly

For TextSymbol the type is always "text".

verticalAlignment String

Adjusts the vertical alignment of the text.

Known Limitations

  • This property only applies when TextSymbol is not used for labeling purposes. The verticalAlignment for labels is inferred from the labelPlacement value.

Possible Values:"baseline"|"top"|"middle"|"bottom"

Default Value:"baseline"
xoffset Numberautocast
Autocasts from Number|String

The offset on the x-axis in points. This value may be autocast with a string expressing size in points or pixels (e.g. 12px).

Known Limitations

This property is currently not supported in 3D SceneViews.

Default Value:0
Examples
// xoffset in points
symbol.xoffset = 3;
// xoffset in pixels
symbol.xoffset = "6px";
// xoffset in points
symbol.xoffset = "3pt";
yoffset Numberautocast
Autocasts from Number|String

The offset on the y-axis in points. This value may be autocast with a string expressing size in points or pixels (e.g. 12px).

Known Limitations

This property is currently not supported in 3D SceneViews.

Default Value:0
Examples
// yoffset in points
symbol.yoffset = 3;
// yoffset in pixels
symbol.yoffset = "6px";
// yoffset in points
symbol.yoffset = "3pt";

Method Overview

Show inherited methods Hide inherited methods
Name Return Type Summary Class

Adds one or more handles which are to be tied to the lifecycle of the object.

more details
Accessor
TextSymbol

Creates a deep clone of the symbol.

more details
TextSymbol
*

Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product.

more details
Symbol
Boolean

Returns true if a named group of handles exist.

more details
Accessor

Removes a group of handles owned by the object.

more details
Accessor
Object

Converts an instance of this class to its ArcGIS portal JSON representation.

more details
Symbol

Method Details

addHandles(handleOrHandles, groupKey)inherited
Since: ArcGIS API for JavaScript 4.25

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 }
);

// Handle gets removed when the object is destroyed.
this.addHandles(handle);
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(){TextSymbol}

Creates a deep clone of the symbol.

Returns
Type Description
TextSymbol A deep clone of the object that invoked this method.
Example
// Creates a deep clone of the graphic's symbol
let symLyr = graphic.symbol.clone();
fromJSON(json){*}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
* Returns a new instance of this class.
hasHandles(groupKey){Boolean}inherited
Since: ArcGIS API for JavaScript 4.25

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(groupKey)inherited
Since: ArcGIS API for JavaScript 4.25

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(){Object}inherited

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.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.