{"id":13422321,"url":"https://github.com/ceteio/chakra-capsize","last_synced_at":"2025-05-06T21:23:03.759Z","repository":{"id":38679070,"uuid":"438266195","full_name":"ceteio/chakra-capsize","owner":"ceteio","description":"The power of capsize inside Chakra UI","archived":false,"fork":false,"pushed_at":"2022-03-20T23:53:17.000Z","size":141,"stargazers_count":73,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-05-02T08:09:50.370Z","etag":null,"topics":["capsize","chakra-ui","design-system","spacing","typography"],"latest_commit_sha":null,"homepage":"https://githubbox.com/ceteio/chakra-capsize/tree/main/example","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/ceteio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2021-12-14T13:37:05.000Z","updated_at":"2025-02-11T15:51:30.000Z","dependencies_parsed_at":"2022-08-20T21:11:01.900Z","dependency_job_id":null,"html_url":"https://github.com/ceteio/chakra-capsize","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ceteio%2Fchakra-capsize","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ceteio%2Fchakra-capsize/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ceteio%2Fchakra-capsize/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ceteio%2Fchakra-capsize/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ceteio","download_url":"https://codeload.github.com/ceteio/chakra-capsize/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252770088,"owners_count":21801471,"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":["capsize","chakra-ui","design-system","spacing","typography"],"created_at":"2024-07-30T23:00:41.569Z","updated_at":"2025-05-06T21:23:03.735Z","avatar_url":"https://github.com/ceteio.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","🛠️ Tools"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"500\" src=\"./img/logo.png\" alt=\"chakra + capsize\"\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n  \u003cp\u003e\n    The power of \u003ca href=\"https://seek-oss.github.io/capsize/\"\u003eCapsize\u003c/a\u003e inside \u003ca href=\"https://chakra-ui.com/\"\u003eChakra UI\u003c/a\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\n    \u003csup\u003e\n      \u003ca href=\"https://githubbox.com/ceteio/chakra-capsize/tree/main/example\" target=\"_blank\"\u003eTry it on Codesandbox\u003c/a\u003e\n    \u003c/sup\u003e\n  \u003c/p\u003e\n    \u003cbr\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n\u003c/div\u003e\n\n```\nyarn add @ceteio/chakra-capsize\n```\n\n**Usage**\n\n```javascript\nimport { withCappedText } from \"@ceteio/chakra-capsize/theme\";\nimport { CappedText, CappedHeading } from \"@ceteio/chakra-capsize\";\nimport { ChakraProvider, extendTheme } from \"@chakra-ui/react\";\nimport robotoFontMetrics from \"@capsizecss/metrics/roboto\";\n\nconst theme = extendTheme(\n  defaultTheme,\n  {\n    fonts: {\n      heading: \"Roboto\",\n      body: \"Roboto\"\n    },\n    capHeights: {\n      sm: 10,\n      md: 14,\n      lg: 18,\n      xl: 24\n    }\n  },\n  withCappedText({\n    fontMetrics: {\n      Roboto: robotoFontMetrics\n    }\n  })\n);\n\nconst App = () =\u003e {\n  return (\n    \u003cChakraProvider theme={theme}\u003e\n      \u003cdiv\u003e\n        \u003cCappedHeading as=\"h1\" size=\"2xl\"\u003e\n          Hi!\n        \u003c/CappedHeading\u003e\n        \u003cCappedText\u003e\n          This paragraph will have surrounding whitespace trimmed. It will also\n          have space between the lines of text reduced to 0.\n        \u003c/CappedText\u003e\n        \u003cCappedText capHeight=\"lg\" lineGap={4}\u003e\n          Setting a capHeight overrides any fontSize prop for more exact sizing.\n          Meanwhile, a lineGap uses the Chakra 'spacings' scale to insert space\n          between lines of text just like any other Chakra element.\n        \u003c/CappedText\u003e\n      \u003c/div\u003e\n    \u003c/ChakraProvider\u003e\n  );\n};\n```\n\n## Theming\n\nSetting up your theme requires the following:\n\n- A defined body \u0026 heading font\n- Font metrics for each defined font\n- Text size theme keys\n- Extending the theme with `withCappedText`\n\n### Body \u0026 Heading font\n\n[Capsize recommends using non-system / non-fallback\nfonts](https://seek-oss.github.io/capsize/) to get the best results \u0026 most\naccurate trimming.\n\nSpecying fonts can be done in the following ways;\n\n1. Using [chakra's fonts theme\n   key](https://chakra-ui.com/docs/theming/theme#typography) _(default)_\n   - `chakra-capsize` will use the theme's `fonts.body` \u0026\n     `fonts.heading` theme values for `\u003cCappedText\u003e` \u0026 `\u003cCappedHeading\u003e`\n     respectively unless a more specific font family is passed in.\n1. Setting `fontFamily` on `components.Text` / `components.Heading`.\n   - This is particularly useful when you have variants that use different font\n     faces such as pull quotes or buttons.\n1. Passing `fontFamily` directly to a `\u003cCappedText\u003e` / `\u003cCappedHeading\u003e`.\n   - The `fontFamily` prop passed will override any value on `Components.Text` /\n     `components.Heading` or the fonts theme key.\n\n### Font metrics for each defined font\n\nOnce your component has a font, `chakra-capsize` requires the corresponding font\nmetrics to be available for calculating the correct trim values.\n\nImportantly, the key used when passing metrics to the\n`withCappedText##fontMetrics` option must exactly match the font family name.\n\nFor example, when using the `Open Sans` font, you must set it up like so:\n\n```javascript\nwithCappedText({\n  fontMetrics: {\n    'Open Sans': { ... }\n  }\n})\n\n// ...\n\n\u003cCappedText fontFamily=\"Open Sans\"\u003e...\n```\n\n### Text size theme keys\n\n`chakra-capsize` has two primary configuration methods, mapping to the\nunderlaying implementation of `capsize`:\n\n1. Text size\n1. Space between lines of text\n\n#### Text size\n\n`chakra-capsize` allows defining the Text size as either a `fontSize` value, or\na `capHeight` value, where `capHeight` will override `fontSize` if set.\n\nBy default, `chakra-capsize` will use `fontSize` as it's the easiest to get\nstarted with, and often more closely matches measurements from design tools such\nas Figma \u0026 Sketch.\n\nWhen you're ready to have more accurate control over the exact size of text, you\ncan use the `capHeight` prop by setting the `capHeights` key in your Chakra\ntheme:\n\n```javascript\nconst theme = {\n  capHeights: {\n    sm: 10,\n    md: 12,\n    lg: 14\n    // ...\n  }\n};\n```\n\nThen the corresponding values can be passed either directly to a `\u003cCappedText\u003e`\n/ `\u003cCappedHeading\u003e` component:\n\n```javascript\n\u003cCappedText capHeight=\"lg\"\u003e...\n```\n\nor on variants, etc, in your component theme:\n\n```javascript\nconst theme = {\n  components: {\n    Text: {\n      variants: {\n        huge: {\n          capHeight: \"2xl\"\n        }\n      }\n    }\n  }\n};\n```\n\n#### Space between lines\n\nWhen multiple lines of text are displayed, a default gap of `0px` is applied,\nresulting in lines of text whos capital letters press up againt each other.\n\nThis gap can be configured in multiple ways, two of which (`lineGap` \u0026\n`leading`) are closely related while the third (`lineHeight`) is available to\nsupport values supplied in Chakra's default theme.\n\n`lineGap` is the number of pixels between the bottom of one capital letter and\nthe top of a capital letter on the next line. `lineGap` uses the `spacings`\ntheme key.\n\n`leading` can be thought of as `lineGap + capHeight`. Or, to put it another way;\nthe distance from the bottom of one capital letter to the bottom of a capital\nletter on the next line. `leading` uses the `sizes` theme key.\n\n`lineHeight` will set the value directly onto the text, however it's important\nto note that it will _not_ affect the spacing at the top/bottom of the text\nelement (it will remain trimmed).\n\nAs with `capHeight`, `lineGap` \u0026 `leading` can be specified on the component\ndirectly:\n\n```javascript\n\u003cCappedText lineGap={6}\u003e...\n```\n\nor on variants, etc, in your component theme:\n\n```javascript\nconst theme = {\n  components: {\n    Text: {\n      variants: {\n        huge: {\n          lineGap: 12\n        }\n      }\n    }\n  }\n};\n```\n\n## `\u003cCappedText\u003e` \u0026 `\u003cCappedHeading\u003e`\n\nExtending Chakra's [`\u003cText\u003e`](https://chakra-ui.com/docs/typography/text) and\n[`\u003cHeading\u003e`](https://chakra-ui.com/docs/typography/heading) components,\n`\u003cCappedText\u003e` / `\u003cCappedHeading\u003e` uses `capsize` to trim space surrounding and\nbetween lines of text.\n\nNote when using `isTruncated` or `noOfLines` props: To avoid ascenders and\ndescenders from being cut off (due to `overflow: hidden`), an extra `\u003cspan\u003e`\nelement is inserted inside the element when either `isTruncated` or `noOfLines`\nis set.\n\n### Props\n\nAll of `\u003cText\u003e` / `\u003cHeading\u003e`'s props are fully supported. In addition,\nthe following props are available:\n\nA note on responsive values: Each of the following props fully support\nresponsive formats (both array and object) with one restriction: a `base` size\n_must_ be set, otherwise an error is thrown.\n\n#### `capHeight`\n\nSpecifies the height, in pixels, of a capital letter in the line of text.\nInternally, `chakra-capsize` trims surrounding whitespace via capsize which\nmakes `capHeight` equivalent to setting `min-height` on a `\u003cdiv\u003e`.\n\nCan be a number, or one of the `capHeights` theme key (which resolves to a\nnumber).\n\nWhen set, `capHeight` will override any `fontSize` values set.\n\n#### `lineGap`\n\nDefault: `0`.\n\nWhen multiple lines of text are displayed, `lineGap` specifies the gap, in\npixels, between those lines.\n\n`lineGap` uses the `spacings` theme scale.\n\nWhen set, `lineGap` will override any `leading` or `lineHeight` values set.\n\n#### `leading`\n\nWhen multiple lines of text are displayed, `leading` specifies the distance\nbetween one baseline to the next.\n\n`leading` uses the `sizes` theme scale.\n\n#### `sx`\n\nUsing the `sx` prop is fully supported, however behaviour is undefined when\nattempting to set any of `fontSize`, `lineHeight`, `::before`, or `:;after`. It\nis recommended to only set `fontSize` and `lineHeight` via props, and avoid\nsetting `::before` or `::after` at all.\n\n#### `truncatedRef`\n\n`\u003cCappedText\u003e` and `\u003cCappedHeading\u003e` can be passed a `ref` to access the React\nDOM node under the hood. However, when either `isTruncated` or `noOfLines` is\nset, an extra inner `\u003cspan\u003e` is rendered; to access this inner DOM node, use the\n`truncatedRef` prop.\n\n## `withCappedText(options)`\n\n```\nimport { withCappedText } from '@ceteio/chakra-capsize/theme'\n```\n\nAdd support for capsize to your Chakra theme via `withCappedText`. It must be\npassed in as an argument to Chakra's `extendTheme` to correctly extend the the\nvalues required.\n\n### `options.fontMetrics`\n\n[Capsize](https://seek-oss.github.io/capsize/) requires a set of known font\nmetrics to correctly trim whitespace from around and between lines of text.\n\n`chakra-capsize` also uses font metrics to support theming with Chakra.\n\nThe easiest way to generate font metrics is with the\n[`@capsizecss/metrics`](https://github.com/seek-oss/capsize/tree/master/packages/metrics)\npackage:\n\n```javascript\nimport robotoFontMetrics from \"@capsizecss/metrics/roboto\";\n// ...\nextendTheme(\n  withCappedText({\n    fontMetrics: {\n      Roboto: robotoFontMetrics\n    }\n  })\n);\n```\n\n_(See the [capsize docs](https://github.com/seek-oss/capsize#font-metrics) for\nmore ways of obtaining the necessary font metrics.)_\n\n### `options.defaultFontSize`\n\n_Default: `'md'`_\n\nFor `chakra-capsize` to work correctly out of the box, a default font size must\nbe set for all `\u003cText\u003e` / `\u003cCappedText\u003e` / `\u003cHeading\u003e` / `\u003cCappedHeading\u003e`\ncomponents. The `defaultFontSize` option will use the `fontSizes` theme scale.\n\n### `options.htmlFontSize`\n\n_Default: `16`_\n\nTo safely convert between `rem` \u0026 `px` font sizes needed by Capsize,\n`chakra-capsize` must know what the html font size is. All modern browsers set\nthis default to `16px`, and `chakra-capsize` does too.\n\nYou should only ever need to set this if you explicitly change the `font-size`\nof the `html` element.\n\n## Frequently Asked Questions\n\n### Why are descenders cut off when using `isTruncated` or `noOfLines`?\n\nTo fix it, add a `lineGap` that is at least the height of the descenders.\n\nThis occurs due to `chakra-capsize`s default of `lineGap = 0` which instructs\ncapsize to set the container to be the same height as a capital letter. Then\nwhen `isTruncated` sets `overflow: hidden`, the ascenders \u0026 descenders are cut\noff. By setting a `lineGap` (or `leading` or `lineHeight`), the height of the\ncontainer is increased to stop the cut off while maintaining the correct\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fceteio%2Fchakra-capsize","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fceteio%2Fchakra-capsize","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fceteio%2Fchakra-capsize/lists"}