{"id":16229570,"url":"https://github.com/nick-mazuk/balanced-text","last_synced_at":"2025-03-19T14:30:20.661Z","repository":{"id":57156070,"uuid":"286592236","full_name":"Nick-Mazuk/balanced-text","owner":"Nick-Mazuk","description":"A performance-optimized script for balancing text in browser.","archived":false,"fork":false,"pushed_at":"2023-03-19T13:28:15.000Z","size":1342,"stargazers_count":17,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-15T18:08:17.690Z","etag":null,"topics":["balanced-text","css","javascript","js","polyfills"],"latest_commit_sha":null,"homepage":"https://nickmazuk.com/balanced-text/","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/Nick-Mazuk.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-10T22:36:38.000Z","updated_at":"2024-03-22T20:04:03.000Z","dependencies_parsed_at":"2024-11-06T17:42:34.519Z","dependency_job_id":"19ca7c0c-fb6a-4e85-be2f-bca46c6ac7f8","html_url":"https://github.com/Nick-Mazuk/balanced-text","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nick-Mazuk%2Fbalanced-text","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nick-Mazuk%2Fbalanced-text/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nick-Mazuk%2Fbalanced-text/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nick-Mazuk%2Fbalanced-text/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nick-Mazuk","download_url":"https://codeload.github.com/Nick-Mazuk/balanced-text/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244444361,"owners_count":20453708,"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":["balanced-text","css","javascript","js","polyfills"],"created_at":"2024-10-10T12:58:37.311Z","updated_at":"2025-03-19T14:30:20.656Z","avatar_url":"https://github.com/Nick-Mazuk.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Balanced Text\n\n\u003c!-- ![Github](https://img.shields.io/github/v/release/nick-mazuk/balanced-text?logo=Github\u0026style=flat-square) --\u003e\n[![npm](https://img.shields.io/npm/v/balanced-text.svg?style=flat-square)][npm-link]\n[![npm](https://img.shields.io/npm/dm/balanced-text.svg?style=flat-square)][npm-link]\n[![jsdeliver](https://data.jsdelivr.com/v1/package/npm/balanced-text/badge)](https://www.jsdelivr.com/package/npm/balanced-text)\n\n![balanced text demo](https://raw.githubusercontent.com/Nick-Mazuk/balanced-text/master/example.gif)\n\nA performance-optimized script for balancing text in browser. `text-wrap: balance` is in the CSS Text Module Level 4 draft. This JS script is a polyfill and is dependency-free.\n\nInitial benchmarks are faster than both Adobe's and NY Time's polyfills.\n\n[Demo](https://nickmazuk.com/balanced-text/)\n\n## Quick Install\n\n```shell\nnpm i balanced-text\n```\n\n### Import\n\nAfter installation, you can import the JS file into your project using this snippet:\n\n```js\nimport { balanceText } from 'balanced-text'\n```\n\nThen run:\n\n`balanceText()`\n\n### HTML\n\n```html\n\u003celement class='has-text-balanced'\u003eLorem…\u003c/element\u003e\n```\n\n### CSS (optional)\n\n```css\n/* For when the CSS spec is available */\n.has-text-balanced {\n    text-wrap: balance;\n}\n```\n\n*The JS will only run if your browser does not support `text-wrap: balance`.*\n\n### CDN (Alternative)\n\n[https://www.jsdelivr.com/package/npm/balanced-text](https://www.jsdelivr.com/package/npm/balanced-text)\n\n```html\n\u003cscript src='https://cdn.jsdelivr.net/npm/balanced-text@latest/balance-text.min.js'\u003e\n    balanceText()\n\u003c/script\u003e\n\n```\n\n## Options\n\nOptions are passed as an optional object.\n\n```js\nbalanceText({\n    elements: '.has-text-balanced',\n    watch: false,\n    debounce: 200,\n    lazyBalance: false,\n    disableWait: false\n})\n```\n\n### Elements\n\nChange which elements are balanced.\n\n- Type: `String`\n- Default: `'.has-text-balanced'`\n\n```js\nbalanceText({ elements: '.balance-text' })\n```\n\nAny string that works with `document.querySelectorAll()` is valid.\n\n### Watch\n\nIf the window is resized, rebalance the text.\n\n- Type: `Boolean`\n- Default: `false`\n\n```js\nbalanceText({ watch: true })\n```\n\n### Debounce\n\nWhen `watch: true`, `balanceText` is debounced by default. That reduces jank whenever the window is resized. Use debounce to change the timing.\n\n- Type: `Integer` (milliseconds)\n- Default: `200`\n\n```js\nbalanceText({ debounce: 200 })\n```\n\nSet debounce to `0` to eliminate it.\n\n### Lazy Balance\n\nIf you have many elements on your page that need balanced text, consider enabling lazy balancing.\n\nWhen set to true, `balanceText` will only affect visible elements. Using `IntersectionObserver`, text will be automatically balanced when it enters the viewport. Because `balanceText` is fast, it should not introduce scroll jank.\n\n- Type: `Boolean`\n- Default: `false`\n\n```js\nbalanceText({ lazyBalance: true })\n```\n\n### Disable Wait\n\nBy default, `balanceText` waits until the main thread is idle (see [Timing](#timing)). Enabling this option will make `balanceText` run as soon as possible. It may become render blocking. However, it can prevent the \"flash\" of unbalanced text.\n\n- Type: `Boolean`\n- Default: `False`\n\n```js\nbalanceText({ disableWait: true })\n```\n\n## How it works\n\n1. Wraps every word in a span\n2. Gets the width of every word and space\n3. Calculates the average line length\n4. Places a `br` tag where the line breaks should go\n\nThis limits many performance drawbacks of other algorithms.\n\n## Limitations\n\nThis script does assume a few things about the HTML contents:\n\n- The HTML elements only contain text (no sub elements, including `b`, `strong`, `a` tags). Will be fixed in future versions.\n- The only line-break opportunities are spaces `' '`\n\n## Timing\n\nThe script uses `requestIdleCallback` if available (~75% support). This reduces the likelihood that it interrupts important functions.\n\nIf not, it uses `requestAnimationFrame` to minimize the chances of dropping a frame.\n\n`requestAnimationFrame` is always used during `lazyBalancing` to minimize scroll jank.\n\n## Report Bug / Feature Request\n\n[https://github.com/Nick-Mazuk/balanced-text/issues](https://github.com/Nick-Mazuk/balanced-text/issues)\n\n## Copyright and license ![Github](https://img.shields.io/github/license/nick-mazuk/balanced-text?logo=Github\u0026style=flat-square)\n\n©2020 Nick Mazuk. Code released under [the MIT license](https://github.com/Nick-Mazuk/balanced-text/blob/master/LICENSE).\n\n[npm-link]: https://www.npmjs.com/package/balanced-text\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnick-mazuk%2Fbalanced-text","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnick-mazuk%2Fbalanced-text","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnick-mazuk%2Fbalanced-text/lists"}