require(["esri/symbols/TextSymbol"], (TextSymbol) => { /* code goes here */ });
import TextSymbol from "@arcgis/core/symbols/TextSymbol.js";
esri/symbols/TextSymbol
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.
- See also
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
-
Parameterproperties Objectoptional
See the properties for a list of all the properties that may be passed into the constructor.
Property Overview
Name | Type | Summary | Class |
---|---|---|---|
The angle of the text. | TextSymbol | ||
The background color of the label's bounding box. | TextSymbol | ||
The border color of the label's bounding box. | TextSymbol | ||
The border size or width of the label's bounding box. | TextSymbol | ||
The color of the symbol. | Symbol | ||
The name of the class. | Accessor | ||
The Font used to style the text. | TextSymbol | ||
The color of the text symbol's halo. | TextSymbol | ||
The size in points of the text symbol's halo. | TextSymbol | ||
Adjusts the horizontal alignment of the text in multi-lines. | TextSymbol | ||
Determines whether to adjust the spacing between characters in the text string. | TextSymbol | ||
The height of the space between each line of text. | TextSymbol | ||
The maximum length in points for each line of text. | TextSymbol | ||
Determines whether every character in the text string is rotated. | TextSymbol | ||
The text string to display in the view. | TextSymbol | ||
For TextSymbol the type is always "text". | TextSymbol | ||
Adjusts the vertical alignment of the text. | TextSymbol | ||
The offset on the x-axis in points. | TextSymbol | ||
The offset on the y-axis in points. | TextSymbol |
Property Details
-
angle
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
Exampleconst 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" };
-
The background color of the label's bounding box.
Known Limitations
This property is currently not supported when labelling a FeatureLayer polyline with a "curved" labelPosition.
-
The border color of the label's bounding box.
Known Limitations
This property is currently not supported when labelling a FeatureLayer polyline with a "curved" labelPosition.
-
borderLineSize
borderLineSize Number
-
The border size or width of the label's bounding box.
Known Limitations
This property is currently not supported when labelling a FeatureLayer polyline with a "curved" labelPosition.
-
Inherited from Symbol
-
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
, anda
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 };
-
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
- The available Font.family property values depend on whether you are working with a 2D MapView or a 3D SceneView.
- See also
Examplelet textSymbol = { type: "text", // autocasts as new TextSymbol() text: "Science of Where", font: { // autocasts as new Font() family: "Merriweather", size: 12, style: "italic", weight: "bold" } };
-
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 };
-
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
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"
- This property only applies when TextSymbol is not used for labeling purposes. The
-
kerning
kerning Boolean
-
Determines whether to adjust the spacing between characters in the text string.
- Default Value:true
-
lineHeight
lineHeight Number
Since: ArcGIS Maps SDK for JavaScript 4.15TextSymbol since 4.0, lineHeight added at 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
Exampleconst textSymbol = { type: "text", // autocasts as new TextSymbol() color: "blue", haloColor: "white", haloSize: 1, lineHeight: 1.5 };
-
Since: ArcGIS Maps SDK for JavaScript 4.15TextSymbol since 4.0, lineWidth added at 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
Exampleconst textSymbol = { type: "text", // autocasts as new TextSymbol() color: "blue", haloColor: "white", haloSize: 1, lineWidth: 200 };
-
rotated
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
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
Examplessymbol.text = "You are here";
symbol.text = "Wish you were \n here";
-
type
type Stringreadonly
-
For TextSymbol the type is always "text".
-
verticalAlignment
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"
- This property only applies when TextSymbol is not used for labeling purposes. The
-
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";
-
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
Name | Return Type | Summary | Class |
---|---|---|---|
Adds one or more handles which are to be tied to the lifecycle of the object. | Accessor | ||
Creates a deep clone of the symbol. | TextSymbol | ||
* | Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product. | Symbol | |
Returns true if a named group of handles exist. | Accessor | ||
Removes a group of handles owned by the object. | Accessor | ||
Converts an instance of this class to its ArcGIS portal JSON representation. | Symbol |
Method Details
-
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25Accessor since 4.0, addHandles added at 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 } ); this.addHandles(handle); // Destroy the object this.destroy();
ParametershandleOrHandles WatchHandle|WatchHandle[]Handles marked for removal once the object is destroyed.
groupKey *optionalKey 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
clone(){TextSymbol}
-
Creates a deep clone of the symbol.
ReturnsType 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();
-
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.Parameterjson ObjectA 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.
ReturnsType Description * Returns a new instance of this class.
-
hasHandles
InheritedMethodhasHandles(groupKey){Boolean}
Inherited from AccessorSince: ArcGIS Maps SDK for JavaScript 4.25Accessor since 4.0, hasHandles added at 4.25. -
Returns true if a named group of handles exist.
ParametergroupKey *optionalA group key.
ReturnsType 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"); }
-
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25Accessor since 4.0, removeHandles added at 4.25. -
Removes a group of handles owned by the object.
ParametergroupKey *optionalA group key or an array or collection of group keys to remove.
Exampleobj.removeHandles(); // removes handles from default group obj.removeHandles("handle-group"); obj.removeHandles("other-handle-group");
-
toJSON
InheritedMethodtoJSON(){Object}
Inherited from Symbol -
Converts an instance of this class to its ArcGIS portal JSON representation. See the Using fromJSON() guide topic for more information.
ReturnsType Description Object The ArcGIS portal JSON representation of an instance of this class.