Add Canvas writingMode and textOrientation by schenney-chromium · Pull Request #12153 · whatwg/html

schenney-chromium · 2026-02-11T18:25:01Z

Add canvas text style attributes for writingMode and textOrientation, as discussed in #issue11449

The writingMode attribute determines the orientation of the text string when measured and rendered, while textOrientation controls the orientation of individual glyphs within the string.

In addition to documenting the attributes, this PR also updates the text preparation algorithm and the measureText algorithm. Some other things are re-worded to make them direction agnostic, primarily by using CSS inline direction terminology.

The choices made in defining behavior, particularly around the alignment attributes and the text metric bounding box attributes, are an attempt to capture the expectations of developers. Of particular concern is anything related to text baseline metrics which have no obvious interpretation for vertical text.

At least two implementers are interested (and none opposed):
- Chromium
- …
Tests are written and can be reviewed and commented upon at:
- https://chromium-review.googlesource.com/c/chromium/src/+/7310865
Implementation bugs are filed:
- Chromium: https://issues.chromium.org/issues/467169720
- Gecko: …
- WebKit: …
Corresponding HTML AAM & ARIA in HTML issues & PRs:
MDN issue is filed: …
[ X] The top of this comment includes a clear commit message to use.

/canvas.html ( diff )
/infrastructure.html ( diff )

zcorpan · 2026-02-12T10:40:20Z

cc @whatwg/canvas

dbaron · 2026-02-12T17:35:20Z

cc @fantasai

annevk · 2026-02-13T13:56:09Z

source

+    <p>Can be set, to change the writing mode. The possible values and their meanings are given
+    below. Other values are ignored. The default is "<code
+    data-x="dom-context-2d-writingMode-horizontal">horizontal</code>".</p>
+   </dd>


These domintro boxes are supposed to be self-contained. I see "given below" is an established pattern, but it seems wrong. Can we describe these new ones here and file an issue to redo the older ones?

The level of detail can be fairly low, just enough so someone knows what to do.

I noticed this problem too. In particular the developer version of the spec does not include the "given below" descriptions. I started another PR at some point to address this but dropped it. I can pick it up again.

annevk · 2026-02-13T13:57:42Z

source

+  object implementing the <code>CanvasTextDrawingStyles</code> interface is created, the <code
+  data-x="dom-context-2d-writingMode">writingMode</code> attribute must initially have the value
+  "<code data-x="dom-context-2d-writingMode-horizontal">horizontal</code>".</p>
+  </div>


We should make this modify an associated concept of the context instead of continuing to conflate public and private API. We should also use the modern "getter steps" and "setter steps" terminology.

annevk · 2026-02-13T13:57:46Z

source

+
+  <div algorithm>
+  <p>The <dfn attribute for="CanvasTextDrawingStyles"><code
+  data-x="dom-context-2d-textOrientation">textOrientation</code></dfn> IDL attribute, on getting,


annevk · 2026-02-13T13:58:35Z

source

  </dl>

+  <p>The <code data-x="dom-context-2d-writingMode">writingMode</code> attribute's allowed keywords
+  are as follows:</p>


I don't think this section adds much. Some of it should be inside the domintro and some of it should be part of the normative processing model probably.

Got it. Will do.

annevk · 2026-02-13T13:59:30Z

source

+      <tr>
+       <td><span>'writing-mode'</span></td>
+       <td><var>target</var>'s <code data-x="dom-context-2d-writingMode">writingMode</code>
+       using "vertical-rl" for <code data-x="dom-context-2d-writingMode-vertical">vertical</code>.


This should be marked up as a string. And maybe it should link back to its definition?

Are you referring to 'writing-mode' or "vertical-rl"?

annevk · 2026-02-13T14:01:39Z

source

-
-    <p>Horizontal position:</p>
+    <p>Apply the appropriate step from the following list to determine the value of
+    <var>inline offset</var>:</p>


We should use camel case for variable names. And I'd make the switch return a value. That seems clearer.

annevk · 2026-02-13T14:02:02Z

source

    </dl>
   </li>

+   <li><p>Set the <var>anchor point</var> as follows:</p>


Wrapping is wrong here as the <li> has multiple children.

annevk · 2026-02-13T14:02:35Z

source

-    <p>Vertical position:</p>
+   <li>
+    <p>Apply the appropriate step from the following list to determine the value of
+    <var>baseline offset</var>:</p>


Camel case plus return from the switch.

annevk · 2026-02-13T14:02:55Z

source


-   <li><p>Return <var>result</var>, <var>physical alignment</var>, and the inline
-   box.</p></li>
+   <li><p>Return <var>result</var>, the inline box and <var>anchor point</var>.</p></li>


Oxford comma.

dbaron · 2026-02-13T14:19:17Z

I think it's worth considering whether the divergence from CSS (just vertical rather than vertical-rl and vertical-lr) is going to cause problems in the long term.

(Is all canvas text today single-line? How likely is it to stay that way?)

schenney-chromium · 2026-02-13T15:02:40Z

I think it's worth considering whether the divergence from CSS (just vertical rather than vertical-rl and vertical-lr) is going to cause problems in the long term.

I've thought about these issues. My reasoning on vertical-rl and vertical-lr is that they imply different block flow directions in CSS, so developers familiar with these would expect different interpretations of textBaseline in canvas code. To me that's added complexity with little practical value.

(Is all canvas text today single-line? How likely is it to stay that way?)

All canvas text right now is single line. If you want multi-line you put the textBaseline at a point that makes sense for the font (a point that should be consistently spaced from line to line) and you draw the lines one at a time with constant offset in the block direction. I don't think distinguishing between "block" direction for each individual line help with this.

There have been various proposals for more complex text styling in canvas including methods for laying out multiple lines, but they have all been made redundant by HTML-in-Canvas. We've even got TAG feedback on other canvas text features saying they would rather we moved HTML-in-Canvas forward due to the accessibility benefits. I'm not great at predicting the future but HTML-in-Canvas seems more likely than not. Once it exists I think the desire for new canvas APIs for styled and multi-line text will disappear.

petamoriken · 2026-02-14T10:40:19Z

There have been various proposals for more complex text styling in canvas including methods for laying out multiple lines, but they have all been made redundant by HTML-in-Canvas. We've even got TAG feedback on other canvas text features saying they would rather we moved HTML-in-Canvas forward due to the accessibility benefits. I'm not great at predicting the future but HTML-in-Canvas seems more likely than not. Once it exists I think the desire for new canvas APIs for styled and multi-line text will disappear.

While I agree with the introduction of HTML-in-Canvas, I would like to see progress on multi-line text rendering via Canvas separately. This is because I want to render text even in environments that do not assume the presence of HTML. Previously, text rendering in OffscreenCanvas within Web Workers was restricted, but that restriction has now been lifted. The fact that it is now supported demonstrates that there is a clear demand for it.

berlysia · 2026-02-14T15:21:56Z

Hello, I am an end-user involved in the display of vertical text in Japanese.

I think we need to add "central" to CanvasTextBaseline.
In CSS Writing Modes, the central baseline is used as the dominant baseline in vertical typographic mode when text-orientation is mixed or upright.
https://drafts.csswg.org/css-writing-modes-3/#text-baselines

In contrast, Canvas textBaseline="middle" represents the midpoint between em-over and em-under (i.e. a geometric midpoint). This is a different concept from the typographic central baseline, so they are not interchangeable.

If this PR introduces writingMode="vertical" and textOrientation, it should be possible to select "central" to keep alignment behavior consistent with CSS.

schenney-chromium · 2026-02-14T16:14:47Z

Hello, I am an end-user involved in the display of vertical text in Japanese.

I think we need to add "central" to CanvasTextBaseline. In CSS Writing Modes, the central baseline is used as the dominant baseline in vertical typographic mode when text-orientation is mixed or upright. https://drafts.csswg.org/css-writing-modes-3/#text-baselines

Thanks very much for your input. I believe we can add a central baseline, so I'll go ahead and include it. We can say that for fonts without that baseline UAs should use middle instead.

schenney-chromium

Next iteration done.

Kaiido

Disclaimer: I am not an expert in text rendering at all, so I can't really do any technical review here.

Regarding the vertical vs vertical-lr & vertical-rl, I'd be supportive of the latter option as I believe that on top of supporting a possible future multi-line API, it would be a better DX: I assume CSS computed values is a common source of context settings, and having to manually parse from there adds more complexity. But I must admit I don't fully understand your point about textBaseline; playing a bit with Chrome's SVG impl. which does support writing-mode and alignment-baseline on <text>, I didn't see a difference while switching between vertical-lr and vertical-rl.

source

Kaiido · 2026-02-17T11:56:30Z

source

+  control the orientation of text runs. Valid values are "<dfn enum-value
+  for="CanvasWritingMode"><code
+  data-x="dom-context-2d-writingMode-horizontal">horizontal</code></dfn>" and "<dfn enum-value
+  for="CanvasWritingMode"><code data-x="dom-context-2d-writingMode-vertical">vertival</code></dfn>". Initially, the <span data-x="concept-CanvasTextDrawingStyles-writing-mode">writingMode</span> must


typo: "vertival" > "vertical"

source

Kaiido · 2026-02-19T09:05:47Z

source

-    data-x="dom-context-2d-textBaseline">textBaseline</code> attribute to the top of the bounding
-    rectangle of the given text, in <span data-x="'px'">CSS pixels</span>; positive numbers
-    indicating a distance going up from the given baseline.
+    <p>The distance perpendicular to the inline direction from the <span


If I understand correctly, this means the actualBoundingBoxAscent and Descent would be dependant on the orientation, while fontBoundingBoxAscent and Descent would always return the same values?
I'm wondering if it's going to be an issue if one were to use both in some calculations. Though I don't really have an use case in mind.

To my mind the fontBoundingBoxAscent/Descent attributes are poorly named. I'm guessing they were added in the first TextMetrics proposal and then the emHeightAscent and friends were added later, because I would expect fontBoundingBoxAscent to be fontAscent given the naming of the other attributes.

With that view, fontBoundingBoxAscent is a font derived property independent of orientation, whereas actualBoundingBoxAscent is a measurement of the rendered shape which depends on orientation.

schenney-chromium · 2026-02-28T16:15:20Z

In response to comments I've added the central baseline value in all relevant places and fixed typos.

There seems to be enough support for both vertical-lr and vertical-rl to make it worth the extra spec prose. I'll do that next (and update the chromium change to account for these spec discussions).

schenney-chromium · 2026-03-16T01:23:31Z

I've updated based on the review comments so far. It's ready for another look.

schenney-chromium added 3 commits February 11, 2026 13:09

Start on writing mode.

596d67a

Work in progress.

a9ca243

Draft now ready.

c84fce4

schenney-chromium self-assigned this Feb 11, 2026

schenney-chromium requested review from Kaiido and annevk February 11, 2026 18:35

schenney-chromium added the topic: canvas label Feb 11, 2026

Fix minor indent issue.

f8de35f

annevk reviewed Feb 13, 2026

View reviewed changes

Update post review

82ddcc2

schenney-chromium commented Feb 16, 2026

View reviewed changes

Kaiido reviewed Feb 19, 2026

View reviewed changes

schenney-chromium added 2 commits February 28, 2026 09:59

Merge branch 'whatwg:main' into writing-mode

99abb66

Add central baseline and fix typos.

11939be

schenney-chromium added 2 commits March 15, 2026 21:22

Merge branch 'whatwg:main' into writing-mode

455b5fe

Update based on review comments.

061d04b

Conversation

schenney-chromium commented Feb 11, 2026 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zcorpan commented Feb 12, 2026

Uh oh!

dbaron commented Feb 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dbaron commented Feb 13, 2026

Uh oh!

schenney-chromium commented Feb 13, 2026

Uh oh!

petamoriken commented Feb 14, 2026

Uh oh!

berlysia commented Feb 14, 2026

Uh oh!

schenney-chromium commented Feb 14, 2026

Uh oh!

schenney-chromium left a comment

Choose a reason for hiding this comment

Uh oh!

Kaiido left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

schenney-chromium commented Feb 28, 2026

Uh oh!

schenney-chromium commented Mar 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

schenney-chromium commented Feb 11, 2026 •

edited by pr-preview bot

Loading