Provides simple single/multi-line text layout capabilities, with single-line support for horizontal alignment and character spacing; multi-line support for explicit line breaks as well as automatic line breaks and vertical alignment.

The following properties can be adjusted in this example.

Inherited from

• DisplayObject

The position of a text/text block is described by a text anchor point around which it adjusts itself through properties such as textBaseline (single/multi-line), textAlign (multi-line), etc.

text

Text content, which can contain line breaks, e.g. "test text \n another line"

textTransform

Consistent with CSS text-transform, the following enumeration values are supported for text content transformation.

• 'capitalize'
• 'uppercase'
• 'lowercase'
• 'none' default value

dx / dy

Corresponds to the SVG dx / dy attribute to add offsets in the horizontal and vertical directions.

Both px and em units are supported, and the default px unit when using the number type.

{
    dx: 10;
    dx: '10px';
    dx: '0.5em';
}

isBillboard

Whether or not to always face the camera in 3D scenes, defaults to false, also known as the "billboard effect".

In example, the text is rendered compressed when the camera is rotated without being turned on:

Turning it on doesn't change the position of the text, but it will always face the camera. This is in line with what is usually required for 2D graphics like text in 3D scenes:

billboardRotation

Rotation angle in billboard mode, clockwise in radians.

In example, we add a rotation angle to the text:

label.style.isBillboard = true;
label.style.billboardRotation = Math.PI / 8;

isSizeAttenuation

Whether or not to apply size attenuation in perspective projection. This option can be turned on if you want to keep the size consistent regardless of depth, following the "near big, far small" visual effect in perspective projection.

In example, we enable size attenuation for text:

label.style.isSizeAttenuation = true;

Font Related

fontFamily

Font type, e.g. 'PingFang SC' 'Microsoft Yahei'

Corresponds to the CSS font-family.

fontSize

Corresponds to the CSS font-size.

fontWeight

Corresponds to the CSS font-weight.

• 'normal' Normal font weight. Same as 400.
• 'bold' Bold font weight. Same as 700.
• 'bolder'
• 'lighter'
• number A number value between 1 and 1000.

fontStyle

Corresponds to the CSS font-style.

Font style, for example, the image below shows the tilted italic effect.

fontVariant

Corresponds to the CSS font-variant.

Font style, for example, the following image is the small-cap effect.

Single row layout

textBaseline

Corresponds to the Canvas textBaseline.

Alignment in the vertical direction is achieved by textBaseline, and the following figure shows the effect of alignment with different values.

Using the current position of the text as the anchor point, the following figure shows the effect of top, middle and bottom in turn. In addition to single line also applies to multi-line text blocks.

letterSpacing

Corresponds to the Canvas letterSpacing.

Multi-row layout

Line feeds occur in the following two cases:

1. Line breaks in text
2. When wordWrap is turned on, the part beyond wordWrapWidth will be automatically line wrapped, similar to word-break in CSS.

Therefore, both cases need to be considered when parsing raw text. However, when dealing with CJK (Chinese/Japanese/Korean) characters, their special language specification needs to be taken into account. In fact, the CSS word-break also provides a value that takes into account the CJK case.

textAlign

Corresponds to the CSS text-align.

In multi-line text, each line can be horizontally aligned with an anchor

• 'start'
• 'center'
• 'end'
• 'left' Same as 'start'.
• 'right' Same as 'end'.

The following figure shows the effect of left, center and right in that order:

wordWrap

Whether to turn on automatic line feed, default value is false.

wordWrapWidth

When wordWrap is turned on, the line will break beyond that width.

textOverflow

Used to determine how to prompt the user for the presence of hidden text overflow content, such as direct cropping, appending an ellipsis or a custom string. Need to be used with wordWrap, wordWrapWidth and [maxLines](/en/api/ basic/text#maxlines) are used together.

Corresponds to the CSS text-overflow.

The following values are supported.

• 'clip' truncates the text directly
• 'ellipsis' uses ... to indicate the truncated text
• Custom strings, using it to indicate the truncated text

Caution.

• 'clip' and 'ellipsis' are reserved words, so custom strings cannot use them.
• If the length of custom text exceeds wordWrapWidth, it will be truncated directly, and the effect is the same as 'clip'.
• The truncation only affects the visual effect, the original text content text is not affected

maxLines

Max lines, text overflow will be truncated, need to use with wordWrap, wordWrapWidth and textOverflow are used together.

The following figure shows limiting text to be displayed on one line and truncated with an ellipsis after it is exceeded.

lineHeight

Corresponds to the CSS line-height.

leading

Methods

getLineBoundingRects

Get the bounding box for each line of text, e.g.:

text.getLineBoundingRects(); // Rectangle[]

where the enclosing box structure is as follows, where x/y is relative to the local coordinate system of the text:

interface Rectangle {
    x: number;
    y: number;
    width: number;
    height: number;
}

In example, we draw the bounding box for each line of the multi-line text, and we can implement advanced text features such as underline and strikethrough based on the bounding box information:

text.getLineBoundingRects().forEach(({ x, y, width, height }) => {
    const block = new Rect({
        style: {
            x,
            y,
            width,
            height,
            stroke: 'black',
            lineWidth: 2,
        },
    });
    text.appendChild(block);
});

isOverflowing

Used to determine if there is overflow content. Useful for Tooltip-like components to determine if the full text needs to be displayed.

text.isOverflowing(); // true

Note that the presence of a line break does not necessarily mean that there is overflow. For example, in the following figure, even though maxLines and wordWrapWidth are set, there is no content overflow and the method returns false.

And only if the content does overflow, i.e. the textOverflow attribute does take effect (whatever its value is), will it return true.

Loading Fonts

In addition to the system default fonts, sometimes we want to load third-party fonts.

In this case, you can use Web Font Loader, which is created in the active callback function when it is loaded successfully, example:

import WebFont from 'webfontloader';

WebFont.load({
    google: {
        families: ['Gaegu'],
    },
    active: () => {
        const text = new Text({
            style: {
                x: 100,
                y: 100,
                fontFamily: 'Gaegu',
                text: 'Almost before we knew it, we had left the ground.',
                fontSize: 30,
                fill: '#1890FF',
                stroke: '#F04864',
                lineWidth: 5,
            },
        });
        canvas.appendChild(text);
    },
});

More CanvasKit-based configuration items

CanvasKit provides enhanced paragraph drawing capabilities. We've integrated them into our g-canvaskit renderer.

FAQ

The bounding box acquisition is not accurate

Since many properties of Text are inheritable, this means that if their values are not explicitly passed in, the correct inherited value can only be obtained after adding the document, so as to calculate an accurate bounding box. If you really want to get the size of the bounding box before adding the document, for example, to get the exact bounding box immediately after instantiation, you need to manually pass in their values:

const text = new Text({
    style: {
        text: 'abcde',
    },
});
text.getBounds(); // Wrong empty bounding box.

text.attr({
    fontSize: '16px',
    fontFamily: 'sans-serif',
    fontWeight: 'normal',
    fontVariant: 'normal',
    fontStyle: 'normal',
    textAlign: 'start',
    textBaseline: 'alphabetic',
    lineWidth: 0,
});
text.getBounds(); // Right bounding box.