Interface TextOptions

Text component options

Export

TextOptions

Date

2024.1.26

Author

yisky

interface TextOptions {
    anchorX?: string | number;
    anchorY?: string | number;
    clipRect?: number[];
    color?: ColorRepresentation;
    curveRadius?: number;
    depthOffset?: number;
    direction?: string;
    fillOpacity?: number;
    font?: string;
    fontSize?: number;
    fontStyle?: "normal" | "italic";
    fontWeight?: number | "normal" | "bold";
    glyphGeometryDetail?: number;
    lang?: string;
    letterSpacing?: number;
    lineHeight?: string | number;
    lookAt?: Vector3;
    material?: Material;
    maxWidth?: number;
    onAfterRender?: ((renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry<NormalBufferAttributes>, material: Material, group: Group<Object3DEventMap>) => void);
    onBeforeRender?: ((renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry<NormalBufferAttributes>, material: Material, group: Group<Object3DEventMap>) => void);
    orientation?: string;
    outlineBlur?: string | number;
    outlineColor?: ColorRepresentation;
    outlineOffsetX?: string | number;
    outlineOffsetY?: string | number;
    outlineOpacity?: number;
    outlineWidth?: string | number;
    overflowWrap?: string;
    position?: Vector3;
    quaternion?: Quaternion;
    queryMask?: QueryMask;
    renderOrder?: RenderOrder;
    rotation?: Euler;
    scale?: Vector3;
    sdfGlyphSize?: number;
    strokeColor?: ColorRepresentation;
    strokeOpacity?: number;
    strokeWidth?: string | number;
    text?: string;
    textAlign?: string;
    textIndent?: number;
    userData?: {
        [key: string]: any;
    };
    whiteSpace?: string;
}

Hierarchy

  • RendererOptions
    • TextOptions

Properties

anchorX? anchorY? clipRect? color? curveRadius? depthOffset? direction? fillOpacity? font? fontSize? fontStyle? fontWeight? glyphGeometryDetail? lang? letterSpacing? lineHeight? lookAt? material? maxWidth? onAfterRender? onBeforeRender? orientation? outlineBlur? outlineColor? outlineOffsetX? outlineOffsetY? outlineOpacity? outlineWidth? overflowWrap? position? quaternion? queryMask? renderOrder? rotation? scale? sdfGlyphSize? strokeColor? strokeOpacity? strokeWidth? text? textAlign? textIndent? userData? whiteSpace?

Properties

OptionalanchorX

anchorX?: string | number

Defines the horizontal position in the text block that should line up with the local origin. Can be specified as a numeric x position in local units, a string percentage of the total text block width e.g. '25%', or one of the following keyword strings: 'left', 'center', or 'right'.

Memberof

TextOptions

OptionalanchorY

anchorY?: string | number

Defines the vertical position in the text block that should line up with the local origin. Can be specified as a numeric y position in local units (note: down is negative y), a string percentage of the total text block height e.g. '25%', or one of the following keyword strings: 'top', 'top-baseline', 'top-cap', 'top-ex', 'middle', 'bottom-baseline', or 'bottom'.

Memberof

TextOptions

OptionalclipRect

clipRect?: number[]

If specified, defines a [minX, minY, maxX, maxY] of a rectangle outside of which all pixels will be discarded. This can be used for example to clip overflowing text when whiteSpace='nowrap'.

Memberof

TextOptions

Optionalcolor

color?: ColorRepresentation

This is a shortcut for setting the color of the text's material. You can use this if you don't want to specify a whole custom material. Also, if you do use a custom material, this color will only be used for this particuar Text instance, even if that same material instance is shared across multiple Text objects.

Memberof

TextOptions

OptionalcurveRadius

curveRadius?: number

Defines a cylindrical radius along which the text's plane will be curved. Positive numbers put the cylinder's centerline (oriented vertically) that distance in front of the text, for a concave curvature, while negative numbers put it behind the text for a convex curvature. The centerline will be aligned with the text's local origin; you can use anchorX to offset it.

Since each glyph is by default rendered with a simple quad, each glyph remains a flat plane internally. You can use glyphGeometryDetail to add more vertices for curvature inside glyphs.

Memberof

TextOptions

OptionaldepthOffset

depthOffset?: number

This is a shortcut for setting the material's polygonOffset and related properties, which can be useful in preventing z-fighting when this text is laid on top of another plane in the scene. Positive numbers are further from the camera, negatives closer.

Memberof

TextOptions

Optionaldirection

direction?: string

Sets the base direction for the text. The default value of "auto" will choose a direction based on the text's content according to the bidi spec. A value of "ltr" or "rtl" will force the direction.

Memberof

TextOptions

OptionalfillOpacity

fillOpacity?: number

WARNING: This API is experimental and may change. The opacity of the glyph's fill from 0 to 1. This behaves like the material's opacity but allows giving the fill a different opacity than the strokeOpacity. A fillOpacity of 0 makes the interior of the glyph invisible, leaving just the strokeWidth. Defaults to 1.

Memberof

TextOptions

Optionalfont

font?: string

URL of a custom font to be used. Font files can be in .ttf, .otf, or .woff (not .woff2) formats. Defaults to Noto Sans.

Memberof

TextOptions

OptionalfontSize

fontSize?: number

The size at which to render the font in local units; corresponds to the em-box height of the chosen font.

Memberof

TextOptions

OptionalfontStyle

fontStyle?: "normal" | "italic"

The style of the font. Currently only used for fallback Noto fonts.

Memberof

TextOptions

OptionalfontWeight

fontWeight?: number | "normal" | "bold"

The weight of the font. Currently only used for fallback Noto fonts.

Memberof

TextOptions

OptionalglyphGeometryDetail

glyphGeometryDetail?: number

Controls number of vertical/horizontal segments that make up each glyph's rectangular plane. Defaults to 1. This can be increased to provide more geometrical detail for custom vertex shader effects, for example.

Memberof

TextOptions

Optionallang

lang?: string

The language code of this text; can be used for explicitly selecting certain CJK fonts.

Memberof

TextOptions

OptionalletterSpacing

letterSpacing?: number

Sets a uniform adjustment to spacing between letters after kerning is applied. Positive numbers increase spacing and negative numbers decrease it.

Memberof

TextOptions

OptionallineHeight

lineHeight?: string | number

Sets the height of each line of text, as a multiple of the fontSize. Defaults to 'normal' which chooses a reasonable height based on the chosen font's ascender/descender metrics.

Memberof

TextOptions

OptionallookAt

lookAt?: Vector3

Rotates the object to face a point in world space.

Memberof

LightformerOptions

Optionalmaterial

material?: Material

Defines a base material to be used when rendering the text. This material will be automatically replaced with a material derived from it, that adds shader code to decrease the alpha for each fragment (pixel) outside the text glyphs, with antialiasing. By default it will derive from a simple white MeshBasicMaterial, but you can use any of the other mesh materials to gain other features like lighting, texture maps, etc.

Also see the color shortcut property.

Memberof

TextOptions

OptionalmaxWidth

maxWidth?: number

The maximum width of the text block, above which text may start wrapping according to the whiteSpace and overflowWrap properties.

Memberof

TextOptions

OptionalonAfterRender

onAfterRender?: ((renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry<NormalBufferAttributes>, material: Material, group: Group<Object3DEventMap>) => void)

After render callback

Memberof

RendererOptions

OptionalonBeforeRender

onBeforeRender?: ((renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry<NormalBufferAttributes>, material: Material, group: Group<Object3DEventMap>) => void)

Before render callback

Memberof

RendererOptions

Optionalorientation

orientation?: string

Defines the axis plane on which the text should be laid out when the mesh has no extra rotation transform. It is specified as a string with two axes: the horizontal axis with positive pointing right, and the vertical axis with positive pointing up. By default this is '+x+y', meaning the text sits on the xy plane with the text's top toward positive y and facing positive z. A value of '+x-z' would place it on the xz plane with the text's top toward negative z and facing positive y.

Memberof

TextOptions

OptionaloutlineBlur

outlineBlur?: string | number

WARNING: This API is experimental and may change. A blur radius applied to the outer edge of the text's outline. If the outlineWidth is zero, the blur will be applied at the glyph edge, like CSS's text-shadow blur radius. Can be specified as either an absolute number in local units, or as a percentage string e.g. "12%" which is treated as a percentage of the fontSize. Defaults to 0.

Memberof

TextOptions

OptionaloutlineColor

outlineColor?: ColorRepresentation

WARNING: This API is experimental and may change. The color of the text outline, if outlineWidth/outlineBlur/outlineOffsetX/Y are set. Defaults to black.

Memberof

TextOptions

OptionaloutlineOffsetX

outlineOffsetX?: string | number

WARNING: This API is experimental and may change. A horizontal offset for the text outline. Can be specified as either an absolute number in local units, or as a percentage string e.g. "12%" which is treated as a percentage of the fontSize. Defaults to 0.

Memberof

TextOptions

OptionaloutlineOffsetY

outlineOffsetY?: string | number

WARNING: This API is experimental and may change. A vertical offset for the text outline. Can be specified as either an absolute number in local units, or as a percentage string e.g. "12%" which is treated as a percentage of the fontSize. Defaults to 0.

Memberof

TextOptions

OptionaloutlineOpacity

outlineOpacity?: number

WARNING: This API is experimental and may change. The opacity of the outline, if outlineWidth/outlineBlur/outlineOffsetX/Y are set. Defaults to 1.

Memberof

TextOptions

OptionaloutlineWidth

outlineWidth?: string | number

WARNING: This API is experimental and may change. The width of an outline/halo to be drawn around each text glyph using the outlineColor and outlineOpacity. Can be specified as either an absolute number in local units, or as a percentage string e.g. "12%" which is treated as a percentage of the fontSize. Defaults to 0, which means no outline will be drawn unless an outlineOffsetX/Y or outlineBlur is set.

Memberof

TextOptions

OptionaloverflowWrap

overflowWrap?: string

Defines how text wraps if the whiteSpace property is normal. Can be either 'normal' to break at whitespace characters, or 'break-word' to allow breaking within words. Defaults to 'normal'.

Memberof

TextOptions

Optionalposition

position?: Vector3

Local position

Memberof

TextOptions

Optionalquaternion

quaternion?: Quaternion

Local quaternion

Memberof

TextOptions

OptionalqueryMask

queryMask?: QueryMask

Query mask

Memberof

RendererOptions

OptionalrenderOrder

renderOrder?: RenderOrder

Render order

Memberof

RendererOptions

Optionalrotation

rotation?: Euler

Local rotation

Memberof

TextOptions

Optionalscale

scale?: Vector3

Local scale

Memberof

TextOptions

OptionalsdfGlyphSize

sdfGlyphSize?: number

The size of each glyph's SDF (signed distance field) used for rendering. This must be a power-of-two number. Defaults to 64 which is generally a good balance of size and quality for most fonts. Larger sizes can improve the quality of glyph rendering by increasing the sharpness of corners and preventing loss of very thin lines, at the expense of increased memory footprint and longer SDF generation time.

Memberof

TextOptions

OptionalstrokeColor

strokeColor?: ColorRepresentation

WARNING: This API is experimental and may change. The color of the text stroke, if strokeWidth is greater than zero. Defaults to gray.

Memberof

TextOptions

OptionalstrokeOpacity

strokeOpacity?: number

WARNING: This API is experimental and may change. The opacity of the stroke, if strokeWidth is greater than zero. Defaults to 1.

Memberof

TextOptions

OptionalstrokeWidth

strokeWidth?: string | number

WARNING: This API is experimental and may change. The width of an inner stroke drawn inside each text glyph using the strokeColor and strokeOpacity. Can be specified as either an absolute number in local units, or as a percentage string e.g. "12%" which is treated as a percentage of the fontSize. Defaults to 0.

Memberof

TextOptions

Optionaltext

text?: string

The string of text to be rendered.

Memberof

TextOptions

OptionaltextAlign

textAlign?: string

The horizontal alignment of each line of text within the overall text bounding box.

Memberof

TextOptions

OptionaltextIndent

textIndent?: number

Indentation for the first character of a line; see CSS text-indent.

Memberof

TextOptions

OptionaluserData

userData?: {
    [key: string]: any;
}

The component user data, default is {}

Memberof

ComponentOptions

OptionalwhiteSpace

whiteSpace?: string

Defines whether text should wrap when a line reaches the maxWidth. Can be either 'normal' (the default), to allow wrapping according to the overflowWrap property, or 'nowrap' to prevent wrapping. Note that 'normal' here honors newline characters to manually break lines, making it behave more like 'pre-wrap' does in CSS.

Memberof

TextOptions

Settings

Member Visibility

On This Page

Properties