TextMaterial
TextMaterial represents a material for text rendering.
Properties
Section titled “Properties”backgroundColor
Section titled “backgroundColor”Type: Color | undefined
Description: Specifies the text background color as a Color instance.
Default: undefined
Example:
import { Color } from "@navaramap/three";
{ text: { backgroundColor: new Color().setHex(0xffffff) // White background }}borderColor
Section titled “borderColor”Type: Color | undefined
Description: Specifies the text background border color as a Color instance.
Default: undefined
Example:
import { Color } from "@navaramap/three";
{ text: { borderColor: new Color().setHex(0x000000) // Black border }}borderWidth
Section titled “borderWidth”Type: number | undefined
Description: Specifies the text border width. Specified as a ratio to the frame height, between 0 and 0.5.
Default: undefined
Example:
{ text: { borderWidth: 2 }}center
Section titled “center”Type: Vec2 | undefined
Description: Specifies the shift amount from the center. The range is between 0 and 1.
Default: undefined
Example:
{ text: { center: { x: 0.5, y: 0.0 } }}clampToGround
Section titled “clampToGround”Type: boolean | undefined
Description: Specifies whether to clamp the text to the ground.
Default: undefined
Example:
{ text: { clampToGround: true }}Type: Color | undefined
Description: Specifies the text color as a Color instance.
Default: undefined
Example:
import { Color } from "@navaramap/three";
{ text: { color: new Color().setHex(0x000000) }}declutter
Section titled “declutter”Type: boolean | undefined
Description: Participate in screen-space decluttering: when labels/sprites overlap on screen, lower-priority ones are hidden. Enabled by default; set to false to draw every label unconditionally.
Default: true
Example:
{ text: { declutter: false }}declutterPriority
Section titled “declutterPriority”Type: number | undefined
Description: Placement priority for decluttering; higher wins. Only meaningful when declutter is enabled. Can be overridden per feature via FeatureEvaluator.evaluate().
Default: 0.0
Example:
{ text: { declutter: true, declutterPriority: 1 }}depthTest
Section titled “depthTest”Type: boolean | undefined
Description: A variable that determines whether front-facing models occlude back-facing models.
Default: true
Example:
{ text: { depthTest: true }}Type: string | undefined
Description: Specifies either the URL of a single font file or the family name of a font family previously registered with view.addFontFamily(). Supported file formats are ttf, otf, woff, and woff2.
When a family name is used, only the face files whose unicode ranges cover the characters in text are fetched, so large scripts (CJK, etc.) can be split into multiple faces and loaded on demand.
For each codepoint, the first face (in faces order) whose unicodeRanges include the codepoint is used, so earlier entries win when ranges overlap. Codepoints not covered by any face fall back to the first face (faces[0]), which may therefore be downloaded even for characters outside its declared ranges. See addFontFamily() for details.
Faces and their unicode ranges can also be derived from a stylesheet’s @font-face rules (e.g. the Google Fonts CSS API) instead of being written by hand — see Font Family from CSS.
Default: undefined (no font is loaded, and the text layer will not render until a font is specified).
Example (single font file):
{ text: { font: "https://example.com/fonts/NotoSansJP-Regular.ttf" }}Example (registered font family):
view.addFontFamily({ family: "MapFont", faces: [ { url: "/fonts/latin.woff2", unicodeRanges: [{ from: 0x0000, to: 0x024f }] }, { url: "/fonts/cjk.woff2", unicodeRanges: [{ from: 0x4e00, to: 0x9fff }] }, ],});
// Later, in a text layer material:{ text: { font: "MapFont" }}height
Section titled “height”Type: number | undefined
Description: Specifies the altitude of the text. The unit is meters.
Default: undefined
Example:
{ text: { height: 100 // 100 meters }}Type: string | undefined
Description: Specifies the language code for text shaping (e.g., “en”, “ja”, “ar”). Used to correctly render text.
Default: undefined
Example:
{ text: { lang: "ja" }}lineHeight
Section titled “lineHeight”Type: number | undefined
Description: Specifies the line height of multi-line text as a multiplier of the font’s natural line height (ascender − descender + line gap).
Default: 1.0
Example:
{ text: { lineHeight: 1.2 }}maxWidth
Section titled “maxWidth”Type: number | undefined
Description: Specifies the maximum line width in ems (multiples of size) before the text wraps at word boundaries. 0 disables wrapping. Explicit \n characters in text always break lines regardless of this setting. Because the value is in ems, the wrap width stays proportional to the text size whether sizeInMeters is on or off.
Default: 0 (no wrapping)
Example:
{ text: { maxWidth: 10 // Wrap lines longer than 10 ems }}offsetDepth
Section titled “offsetDepth”Type: boolean | undefined
Description: Avoids overlap with the earth’s surface. Use this to prevent the text from clipping into the earth’s surface.
Default: undefined
Example:
{ text: { offsetDepth: true }}opacity
Section titled “opacity”Type: number | undefined
Description: Specifies the opacity of the text. The range is 0.0 (fully transparent) to 1.0 (fully opaque).
Default: 1.0
Example:
{ text: { opacity: 0.5 }}outlineColor
Section titled “outlineColor”Type: Color | undefined
Description: Specifies the text outline color as a Color instance.
Default: undefined
Example:
import { Color } from "@navaramap/three";
{ text: { outlineColor: new Color().setHex(0x000000) // Black outline }}outlineOpacity
Section titled “outlineOpacity”Type: number | undefined
Description: Specifies the opacity of the text outline. The range is 0.0 to 1.0.
Default: undefined
Example:
{ text: { outlineOpacity: 0.8 }}outlineWidth
Section titled “outlineWidth”Type: number | undefined
Description: Specifies the outline thickness in CSS pixels.
Default: 0.0
Example:
{ text: { outlineWidth: 2 }}highQuality
Section titled “highQuality”Type: boolean | undefined
Description: Enables high-quality glyph rendering. When true, text uses an MSDF atlas, which preserves sharp corners at large sizes but is significantly slower to rasterize per glyph. When false or omitted, the default single-channel SDF atlas is used, which is dramatically faster with slightly soft corners at extreme zoom.
Default: false
Example:
{ text: { highQuality: true }}sizeInMeters
Section titled “sizeInMeters”Type: boolean | undefined
Description: Whether the size is specified in meters. If false, the size is in pixels.
Default: true
Example:
{ text: { sizeInMeters: true }}Type: boolean | undefined
Description: Specifies whether to show the text.
Default: undefined
Example:
{ text: { show: true }}Type: number | undefined
Description: Specifies the size of the text. The unit is pixels.
Default: undefined
Example:
{ text: { size: 16 }}Type: string | undefined
Description: Specifies the text content to display.
Default: undefined
Example:
{ text: { text: "Tokyo Station" }}textAlign
Section titled “textAlign”Type: string | undefined
Description: Specifies the horizontal alignment of lines within a multi-line text block. One of "left", "center", or "right". Has a visible effect only when the text spans multiple lines (via maxWidth or explicit \n characters).
Default: "center"
Example:
{ text: { textAlign: "left" }}transparent
Section titled “transparent”Type: boolean | undefined
Description: Enables transparency and alpha blending. When enabled, the opacity property can be used to control transparency.
Default: true
Example:
{ text: { transparent: true, opacity: 0.5 }}