Updating the library never moves text your users have already saved. This page explains how that works, what each kind of release can change, and the one setting that decides what happens to older text.
Saved text never moves
Each document records the text version it was made with, in renderVersion. A document draws with that version's
rules wherever it opens, with every later release of the library: the same line breaks, the same letter positions,
on screen and in print. Editing it doesn't change that. Typing, restyling or adding a paragraph to a saved text box
keeps the box on its version.
A document with no renderVersion was made before versions existed, and is version 1. Leave the field as the library
writes it.
New text gets the latest version
A text box created with no document, and every document the library creates (such as createDocumentFromText), uses
the latest text version. The version belongs to the whole box: text pasted into a box takes that box's version, and a
duplicated box keeps the version of the box it was copied from.
Choosing when older text moves
upgradeOlderText decides whether text saved with an older version moves to the latest one:
const rt = enableRichText(stage, { upgradeOlderText: "never" });
// Plain canvas: createCanvasRichText({ onChange: render, upgradeOlderText: "never" })
| Value | Older text |
|---|---|
"never" (default) |
Keeps drawing exactly as it was saved, line breaks included, whether or not anyone edits it |
"immediately" |
Moves to the latest version as it loads. It may shift slightly; saving keeps the change. |
Use "immediately" only if your app has no saved designs that people expect to stay exactly as they were, such as a
tool whose documents are made fresh each session. A version change applies to a whole text box at once, so its lines
can re-wrap anywhere in the box, not only where someone typed.
What each release can change
Version numbers follow semantic versioning: major.minor.patch.
| Release | Can change | Never changes |
|---|---|---|
| Patch (1.0.1) | Bug fixes | Saved text, the API |
| Minor (1.1.0) | New features, and possibly a new text version for new text | Saved text, existing API |
| Major (2.0.0) | Removes or renames parts of the API, each listed in the changelog with what to use instead | Saved text |
A rendering fix that would move existing text always ships as a new text version, so only new text gets it. The changelog lists every new text version with what it changes.
Text version 2
Version 2 is the latest. Compared with version 1, it:
- measures text the way Chrome shapes it, so on-screen text and print match more closely;
- keeps a word whole when only part of it is styled, so underlining part of "Opening" no longer wraps it across two lines;
- fits a word by the width its line reports, so text in a box sized to it no longer wraps its last word;
- places tabs on default stops every 3 font sizes when a paragraph has no stops, as word processors do;
- never justifies a line with tabs, and keeps a long label clear of a price on a tab stop;
- picks a weight a family doesn't ship the way the browser does, and uses the weights a design recorded when your fonts lookup isn't installed;
- underlines and strikes through every word on a line with mixed sizes;
- draws underlines and strikethroughs with a gradient or image fill, and shows an image fill on curved text;
- spaces curved text by its letters' middles, so text bending up and bending down is spaced alike;
- measures an empty line in its own font, and draws a bold-only family's bullets in that face.
Documents saved with version 1 keep drawing as version 1.