{"id":17230653,"url":"https://github.com/jaames/zfont","last_synced_at":"2025-04-06T14:11:07.416Z","repository":{"id":35083224,"uuid":"189750600","full_name":"jaames/zfont","owner":"jaames","description":"💬 Text plugin for Zdog - works with any .ttf font!","archived":false,"fork":false,"pushed_at":"2022-07-20T08:28:45.000Z","size":2592,"stargazers_count":184,"open_issues_count":5,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-30T13:09:48.076Z","etag":null,"topics":["3d","canvas","font","svg","text","truetype","zdog"],"latest_commit_sha":null,"homepage":"https://jaames.github.io/zfont/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jaames.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-01T15:48:28.000Z","updated_at":"2024-08-29T02:47:43.000Z","dependencies_parsed_at":"2022-08-08T05:00:24.685Z","dependency_job_id":null,"html_url":"https://github.com/jaames/zfont","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaames%2Fzfont","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaames%2Fzfont/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaames%2Fzfont/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaames%2Fzfont/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaames","download_url":"https://codeload.github.com/jaames/zfont/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247492513,"owners_count":20947544,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","canvas","font","svg","text","truetype","zdog"],"created_at":"2024-10-15T04:53:38.260Z","updated_at":"2025-04-06T14:11:07.398Z","avatar_url":"https://github.com/jaames.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003ch1 align=\"center\"\u003e\u003ca href=\"https://github.com/jaames/zfont\" target=\"blank\"\u003e\u003cimg width=\"888\" src=\"https://raw.githubusercontent.com/jaames/zfont/master/assets/banner.gif\"/\u003e\u003cbr/\u003eZfont\u003c/a\u003e\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cb\u003eA text plugin for the \u003ca href=\"https://github.com/metafizzy/zdog\"\u003eZdog\u003c/a\u003e 3D engine! Renders TrueType fonts via \u003ca href=\"https://github.com/photopea/Typr.js\"\u003eTypr.js\u003c/a\u003e | \u003ca href=\"https://jaames.github.io/zfont/\"\u003ejaames.github.io/zfont\u003c/a\u003e\n\u003c/b\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e | \u003ca href=\"#caveats\"\u003eCaveats\u003c/a\u003e | \u003ca href=\"#demo\"\u003eDemo\u003c/a\u003e | \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e | \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e | \u003ca href=\"#api\"\u003eAPI\u003c/a\u003e | \u003ca href=\"#zdogfont\"\u003eZdog.Font\u003c/a\u003e | \u003ca href=\"#zdogtext\"\u003eZdog.Text\u003c/a\u003e | \u003ca href=\"#zdogtextgroup\"\u003eZdog.TextGroup\u003c/a\u003e | \u003ca href=\"#todo\"\u003eTodo\u003c/a\u003e | \u003ca href=\"#building\"\u003eBuilding\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cbr/\u003e\n\n## Features\n\n* Built on top of [Typr.js](https://github.com/photopea/Typr.js), which supports a wide range of .ttf and .otf fonts with speed and grace\n* Less than 14kB minified and gzipped\n* No need to worry about waiting for fonts to load; text automatically pops into existence once the font is ready\n* Includes support for multiline text\n* Update font, text, color, alignment, etc at any time\n* Bonus utilities for measuring text, waiting for font load \u0026 more!\n\n## Caveats\n\n* You have to provide a .ttf to use yourself; it isn't possible to use system fonts\n* Character range is limited to whichever glyphs are supported by your chosen font, and font stacks/fallbacks aren't supported yet\n\n## Demo\n\nA live demo can be found [here](https://jaames.github.io/zfont/), there's also some more in-depth examples on [Codepen](https://codepen.io/collection/DPKGvY/)!\n\n## Installation\n\n### Install with NPM\n\n```bash\n$ npm install zfont --save\n```\n\nIf you are using a module bundler like Webpack or Rollup, import Zfont into your project: \n\n```javascript\n// Using ES6 module syntax\nimport Zfont from 'zfont';\n\n// Using CommonJS modules\nconst Zfont = require('zfont');\n```\n\n### Using the jsDelivr CDN\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/zfont/dist/zfont.min.js\"\u003e\u003c/script\u003e\n```\n\nWhen manually including the library like this, it will be globally available on `window.Zfont`\n\n### Download and Host Yourself\n\n**[Development version](https://raw.githubusercontent.com/jaames/zfont/master/dist/zfont.js)**\u003cbr/\u003e\nUncompressed at around 75kB, with source comments included\n\n**[Production version](https://raw.githubusercontent.com/jaames/zfont/master/dist/zfont.min.js)**\u003cbr/\u003e\nMinified to 45kB\n\nThen add it to the `\u003chead\u003e` of your page with a `\u003cscript\u003e` tag:\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\n    \u003c!-- ... --\u003e\n    \u003cscript src=\"./path/to/zfont.min.js\"\u003e\u003c/script\u003e\n  \u003c/head\u003e\n  \u003c!-- ... --\u003e\n\u003c/html\u003e\n```\n\n## Usage\n\n### Register Plugin\n\nAfter both Zdog and Zfont have been imported/downloaded, we need to initialize the Zfont plugin. Once it's initialized, the `Zdog.Font`, `Zdog.Text` and `Zdog.TextGroup` classes will be available:\n\n```js\nZfont.init(Zdog);\n```\n\n### Hello World\n\n(Pssst! If you prefer to dive in, check out the [basic demo over on Codepen](https://codepen.io/rakujira/pen/vqLBwz))\n\nTo draw some text in a Zdog scene, first we need to set up a new `Zdog.Font` object with the .ttf url for our desired font, then we can create a new `Zdog.Text` object and add it to the illustration like any other shape:\n\n```js\n// Initialize Zfont\nZfont.init(Zdog);\n\n\n// Create a Zdog illustration\nlet illo = new Zdog.Illustration({\n  element: '.zdog-canvas'\n});\n\n// Set up a font to use\nlet myFont = new Zdog.Font({\n  src: './path/to/font.ttf'\n});\n\n// Create a text object\n// This is just a Zdog.Shape object with a couple of extra parameters!\nnew Zdog.Text({\n  addTo: illo,\n  font: myFont,\n  value: 'Hey, Zdog!',\n  fontSize: 64,\n  color: '#fff'\n});\n\n// Animation loop\nfunction animate() {\n  illo.updateRenderGraph();\n  requestAnimationFrame(animate);\n}\nanimate();\n```\n\n### Multiline Text\n\nBoth `Zdog.Text` and `Zdog.TextGroup` support multiline text, by inserting a newline character (`\\n`) wherever you wish to add a line break:\n\n```js\nnew Zdog.Text({\n  ...\n  value: 'The quick brown fox\\njumps over the\\nlazy zdog',\n});\n```\n\nFor better readability you may prefer to use an array of strings for the `value` option. In this case, each string in the array will be treated as a seperate line of text:\n\n```js\nnew Zdog.Text({\n  ...\n  value: [\n    'The quick brown fox'\n    'jumps over the',\n    'lazy zdog'\n  ]\n});\n```\n\n### Waiting for Fonts to Load\n\nIn most cases you don't have to worry about waiting for fonts to load, as text objects will magically pop into existence once their font is ready to use. However, the plugin also provides a `Zdog.waitForFonts()` utility function if you need to delay anything until all the fonts in your scene have finished loading.\n\nFor example, let's modify the animation loop from the previous example so that it doesn't begin until the fonts are ready:\n\n```js\n// Animation loop\nfunction animate() {\n  illo.updateRenderGraph();\n  requestAnimationFrame(animate);\n}\n// Zdog.waitForFonts() returns a Promise which is resolved once all the fonts added to the scene so far have been loaded\nZdog.waitForFonts().then(() =\u003e {\n  // Once the fonts are done, start the animation loop\n  animate();\n})\n```\n\n## API\n\n### Zdog.Font\n\nRepresents a font that can be used by an instance of either [`Zdog.Text`](#zdogtext) or [`Zdog.TextGroup`](#zdogtextgroup).\n\n```js\nlet font = new Zdog.Font({\n  src: './path/to/font.ttf'\n})\n```\n\n#### Options\n\n| Param      | Details | Default |\n|:-----------|:--------|:--------|\n| `src`      | Font URL path. This can be a `.ttf` or `.otf` font, check out the [Typr.js repo](https://github.com/photopea/Typr.js) for more details about font support | `''` |\n\n#### Methods\n\n##### `measureText(text, fontSize)`\n\nGet the measurements for the specified string `text` when rendered at `fontSize` (measured in pixels), similar to [`Canvas​Rendering​Context2D.measure​Text()`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/measureText). \n\nReturns an object with `width`, `height`, `descender`, `ascender`.\n\n##### `getTextPath(text, fontSize, x=0, y=0, z=0, alignX='left', alignY='bottom')`\n\nReturns an array of [Zdog path commands](https://zzz.dog/shapes#shape-path-commands) for the specified string `text`, when rendered at `fontSize` (measured in pixels).\n\n* (`x`, `y`, `z`) is the origin point of the path\n* `alignX` is the horizontal text alignment (equivalent to the CSS `text-align` property); either `\"left\"`, `\"center\"` or `\"right\"`. \n* `alignY` is the vertical text alignment; either `\"top\"`, `\"middle\"` or `\"bottom\".`\n\n##### `waitForLoad()`\n\nReturns a Promise which resolves once this font has finished loading.\n\n### Zdog.Text\n\nAn object used for rendering text. It inherits everything from the [`Zdog.Shape`](https://zzz.dog/api#shape) class.\n\n```js\nnew Zdog.Text({\n  addTo: illo,\n  font: font,\n  value: 'Hey, Zdog!',\n  textAlign: 'center',\n  textBaseline: 'middle',\n  color: '#5222ee',\n  stroke: 1,\n})\n```\n\n#### Options\n\n`Zdog.Text` inherits all the options from the [`Zdog.Shape`](https://zzz.dog/api#shape) class, plus a couple of extras:\n\n| Param      | Details | Default |\n|:-----------|:--------|:--------|\n| `font`     | [`Zdog.Font`](#zdog-font) to use for this text. This is required. | `null` |\n| `value`    | Text string | `''` |\n| `fontSize` | Text size, measured in pixels | `64` |\n| `textAlign`| Horizontal text alignment, equivalent to the CSS `text-align` property. This can be either `'left'`, `'center'` or `'right'` | `'left'` |\n| `textBaseline`| Vertical text alignment, equivalent to the HTML5 canvas' [`textBaseline`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline) property. This can be either `'top'`, `'middle'` or `'bottom'` | `'bottom'` |\n\n#### Properties\n\n`Zdog.Text` inherits all the properties from the [`Zdog.Shape`](https://zzz.dog/api#shape) class, as well as some extras. All of these properties can be updated at any time and the rendered text will update automatically. \n\n##### `font`\n\nThe [`Zdog.Font`](#zdog-font) instance being used for this text.\n\n##### `value`\n\nText value as a string.\n\n##### `fontSize`\n\nFont size, measured in pixels.\n\n##### `textAlign`\n\nHorizontal text alignment, equivalent to the CSS `text-align` property. This can be either `'left'`, `'center'` or `'right'`\n\n##### `textBaseline`\n\nVertical text alignment, equivalent to the HTML5 canvas' [`textBaseline`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline) property. This can be either `'top'`, `'middle'` or `'bottom'`\n\n### Zdog.TextGroup\n\nThis class is very similar to [`Zdog.Text`](#zdog-text), except it acts as a [`Zdog.Group`](https://zzz.dog/api#group) instead, and each text glyph is rendered as its own shape. This is helpful for more advanced use-cases where you need control over each character.\n\n```js\nnew Zdog.TextGroup({\n  addTo: illo,\n  font: font,\n  value: 'Hey, Zdog!',\n  textAlign: 'center',\n  color: '#5222ee',\n  stroke: 2,\n})\n```\n\n#### Options\n\n`Zdog.TextGroup` inherits all the options from the [`Zdog.Group`](https://zzz.dog/api#group) class, plus a few extras:\n\n| Param      | Details | Default |\n|:-----------|:--------|:--------|\n| `font`     | [`Zdog.Font`](#zdog-font) to use for this text. This is required. | `null` |\n| `value`    | Text string | `''` |\n| `fontSize` | Text size, measured in pixels | `64` |\n| `textAlign`| Horizontal text alignment, equivalent to the CSS `text-align` property. This can be either `'left'`, `'center'` or `'right'` | `'left'` |\n| `textBaseline`| Vertical text alignment, equivalent to the HTML5 canvas' [`textBaseline`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline) property. This can be either `'top'`, `'middle'` or `'bottom'` | `'bottom'` |\n| `color` | Text color | `#333` |\n| `fill` | Text fill | `false` |\n| `stroke` | Text stroke | `stroke` |\n\n#### Properties\n\n`Zdog.TextGroup` inherits all the properties from the [`Zdog.Group`](https://zzz.dog/api#group) class, as well as some extras. All of these properties can be updated at any time and the rendered text will update automatically. \n\n##### `font`\n\nThe [`Zdog.Font`](#zdog-font) instance being used for this text.\n\n##### `value`\n\nText value as a string.\n\n##### `fontSize`\n\nFont size, measured in pixels.\n\n##### `textAlign`\n\nHorizontal text alignment, equivalent to the CSS `text-align` property. This can be either `'left'`, `'center'` or `'right'`\n\n##### `textBaseline`\n\nVertical text alignment, equivalent to the HTML5 canvas' [`textBaseline`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline) property. This can be either `'top'`, `'middle'` or `'bottom'`\n\n##### `color`\n\nText color, equivalent to [`Shape.color`](https://zzz.dog/api#shape-color). Setting this will update the color for all of the group's children.\n\n##### `fill`\n\nText fill, equivalent to [`Shape.fill`](https://zzz.dog/api#shape-fill). Setting this will update the fill for all of the group's children.\n\n##### `stroke`\n\nText stroke, equivalent to [`Shape.stroke`](https://zzz.dog/api#shape-stroke). Setting this will update the stroke for all of the group's children.\n\n### Zdog.waitForFonts\n\nReturns a Promise which resolves as soon as all the fonts currently added to the scene are loaded and ready for use.\n\n```js\nZdog.waitForFonts().then(function() {\n  // Do something once the font is ready\n}\n```\n\n## Todo\n\n* Google Fonts \u0026 Typekit integration?\n* Support for different text directions, e.g. right-to-left\n* Support for fallback fonts\n* Support for color (SVG) fonts\n\n## Building\n\n### Install Dependencies with NPM\n\n```bash\n$ npm install\n```\n\n### Run Devserver\n\n```bash\n$ npm start\n```\n\n### Build production files\n\n```bash\n$ npm run build\n```\n\n----\n\n2019 [James Daniel](//github.com/jaames)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaames%2Fzfont","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaames%2Fzfont","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaames%2Fzfont/lists"}