Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ceteio/chakra-capsize
The power of capsize inside Chakra UI
https://github.com/ceteio/chakra-capsize
capsize chakra-ui design-system spacing typography
Last synced: about 2 months ago
JSON representation
The power of capsize inside Chakra UI
- Host: GitHub
- URL: https://github.com/ceteio/chakra-capsize
- Owner: ceteio
- License: mit
- Created: 2021-12-14T13:37:05.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2022-03-20T23:53:17.000Z (over 2 years ago)
- Last Synced: 2024-10-11T12:04:33.920Z (2 months ago)
- Topics: capsize, chakra-ui, design-system, spacing, typography
- Language: JavaScript
- Homepage: https://githubbox.com/ceteio/chakra-capsize/tree/main/example
- Size: 138 KB
- Stars: 74
- Watchers: 0
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-chakra-ui - Chakra Capsize - oss.github.io/capsize/) inside Chakra UI. (🛠️ Tools)
- awesome - ceteio/chakra-capsize - The power of capsize inside Chakra UI (JavaScript)
README
```
yarn add @ceteio/chakra-capsize
```
**Usage**
```javascript
import { withCappedText } from "@ceteio/chakra-capsize/theme";
import { CappedText, CappedHeading } from "@ceteio/chakra-capsize";
import { ChakraProvider, extendTheme } from "@chakra-ui/react";
import robotoFontMetrics from "@capsizecss/metrics/roboto";
const theme = extendTheme(
defaultTheme,
{
fonts: {
heading: "Roboto",
body: "Roboto"
},
capHeights: {
sm: 10,
md: 14,
lg: 18,
xl: 24
}
},
withCappedText({
fontMetrics: {
Roboto: robotoFontMetrics
}
})
);
const App = () => {
return (
Hi!
This paragraph will have surrounding whitespace trimmed. It will also
have space between the lines of text reduced to 0.
Setting a capHeight overrides any fontSize prop for more exact sizing.
Meanwhile, a lineGap uses the Chakra 'spacings' scale to insert space
between lines of text just like any other Chakra element.
);
};
```
## Theming
Setting up your theme requires the following:
- A defined body & heading font
- Font metrics for each defined font
- Text size theme keys
- Extending the theme with `withCappedText`
### Body & Heading font
[Capsize recommends using non-system / non-fallback
fonts](https://seek-oss.github.io/capsize/) to get the best results & most
accurate trimming.
Specying fonts can be done in the following ways;
1. Using [chakra's fonts theme
key](https://chakra-ui.com/docs/theming/theme#typography) _(default)_
- `chakra-capsize` will use the theme's `fonts.body` &
`fonts.heading` theme values for `` & ``
respectively unless a more specific font family is passed in.
1. Setting `fontFamily` on `components.Text` / `components.Heading`.
- This is particularly useful when you have variants that use different font
faces such as pull quotes or buttons.
1. Passing `fontFamily` directly to a `` / ``.
- The `fontFamily` prop passed will override any value on `Components.Text` /
`components.Heading` or the fonts theme key.
### Font metrics for each defined font
Once your component has a font, `chakra-capsize` requires the corresponding font
metrics to be available for calculating the correct trim values.
Importantly, the key used when passing metrics to the
`withCappedText##fontMetrics` option must exactly match the font family name.
For example, when using the `Open Sans` font, you must set it up like so:
```javascript
withCappedText({
fontMetrics: {
'Open Sans': { ... }
}
})
// ...
...
```
### Text size theme keys
`chakra-capsize` has two primary configuration methods, mapping to the
underlaying implementation of `capsize`:
1. Text size
1. Space between lines of text
#### Text size
`chakra-capsize` allows defining the Text size as either a `fontSize` value, or
a `capHeight` value, where `capHeight` will override `fontSize` if set.
By default, `chakra-capsize` will use `fontSize` as it's the easiest to get
started with, and often more closely matches measurements from design tools such
as Figma & Sketch.
When you're ready to have more accurate control over the exact size of text, you
can use the `capHeight` prop by setting the `capHeights` key in your Chakra
theme:
```javascript
const theme = {
capHeights: {
sm: 10,
md: 12,
lg: 14
// ...
}
};
```
Then the corresponding values can be passed either directly to a ``
/ `` component:
```javascript
...
```
or on variants, etc, in your component theme:
```javascript
const theme = {
components: {
Text: {
variants: {
huge: {
capHeight: "2xl"
}
}
}
}
};
```
#### Space between lines
When multiple lines of text are displayed, a default gap of `0px` is applied,
resulting in lines of text whos capital letters press up againt each other.
This gap can be configured in multiple ways, two of which (`lineGap` &
`leading`) are closely related while the third (`lineHeight`) is available to
support values supplied in Chakra's default theme.
`lineGap` is the number of pixels between the bottom of one capital letter and
the top of a capital letter on the next line. `lineGap` uses the `spacings`
theme key.
`leading` can be thought of as `lineGap + capHeight`. Or, to put it another way;
the distance from the bottom of one capital letter to the bottom of a capital
letter on the next line. `leading` uses the `sizes` theme key.
`lineHeight` will set the value directly onto the text, however it's important
to note that it will _not_ affect the spacing at the top/bottom of the text
element (it will remain trimmed).
As with `capHeight`, `lineGap` & `leading` can be specified on the component
directly:
```javascript
...
```
or on variants, etc, in your component theme:
```javascript
const theme = {
components: {
Text: {
variants: {
huge: {
lineGap: 12
}
}
}
}
};
```
## `` & ``
Extending Chakra's [``](https://chakra-ui.com/docs/typography/text) and
[``](https://chakra-ui.com/docs/typography/heading) components,
`` / `` uses `capsize` to trim space surrounding and
between lines of text.
Note when using `isTruncated` or `noOfLines` props: To avoid ascenders and
descenders from being cut off (due to `overflow: hidden`), an extra ``
element is inserted inside the element when either `isTruncated` or `noOfLines`
is set.
### Props
All of `` / ``'s props are fully supported. In addition,
the following props are available:
A note on responsive values: Each of the following props fully support
responsive formats (both array and object) with one restriction: a `base` size
_must_ be set, otherwise an error is thrown.
#### `capHeight`
Specifies the height, in pixels, of a capital letter in the line of text.
Internally, `chakra-capsize` trims surrounding whitespace via capsize which
makes `capHeight` equivalent to setting `min-height` on a `
`.
Can be a number, or one of the `capHeights` theme key (which resolves to a
number).
When set, `capHeight` will override any `fontSize` values set.
#### `lineGap`
Default: `0`.
When multiple lines of text are displayed, `lineGap` specifies the gap, in
pixels, between those lines.
`lineGap` uses the `spacings` theme scale.
When set, `lineGap` will override any `leading` or `lineHeight` values set.
#### `leading`
When multiple lines of text are displayed, `leading` specifies the distance
between one baseline to the next.
`leading` uses the `sizes` theme scale.
#### `sx`
Using the `sx` prop is fully supported, however behaviour is undefined when
attempting to set any of `fontSize`, `lineHeight`, `::before`, or `:;after`. It
is recommended to only set `fontSize` and `lineHeight` via props, and avoid
setting `::before` or `::after` at all.
#### `truncatedRef`
`` and `` can be passed a `ref` to access the React
DOM node under the hood. However, when either `isTruncated` or `noOfLines` is
set, an extra inner `` is rendered; to access this inner DOM node, use the
`truncatedRef` prop.
## `withCappedText(options)`
```
import { withCappedText } from '@ceteio/chakra-capsize/theme'
```
Add support for capsize to your Chakra theme via `withCappedText`. It must be
passed in as an argument to Chakra's `extendTheme` to correctly extend the the
values required.
### `options.fontMetrics`
[Capsize](https://seek-oss.github.io/capsize/) requires a set of known font
metrics to correctly trim whitespace from around and between lines of text.
`chakra-capsize` also uses font metrics to support theming with Chakra.
The easiest way to generate font metrics is with the
[`@capsizecss/metrics`](https://github.com/seek-oss/capsize/tree/master/packages/metrics)
package:
```javascript
import robotoFontMetrics from "@capsizecss/metrics/roboto";
// ...
extendTheme(
withCappedText({
fontMetrics: {
Roboto: robotoFontMetrics
}
})
);
```
_(See the [capsize docs](https://github.com/seek-oss/capsize#font-metrics) for
more ways of obtaining the necessary font metrics.)_
### `options.defaultFontSize`
_Default: `'md'`_
For `chakra-capsize` to work correctly out of the box, a default font size must
be set for all `` / `` / `` / ``
components. The `defaultFontSize` option will use the `fontSizes` theme scale.
### `options.htmlFontSize`
_Default: `16`_
To safely convert between `rem` & `px` font sizes needed by Capsize,
`chakra-capsize` must know what the html font size is. All modern browsers set
this default to `16px`, and `chakra-capsize` does too.
You should only ever need to set this if you explicitly change the `font-size`
of the `html` element.
## Frequently Asked Questions
### Why are descenders cut off when using `isTruncated` or `noOfLines`?
To fix it, add a `lineGap` that is at least the height of the descenders.
This occurs due to `chakra-capsize`s default of `lineGap = 0` which instructs
capsize to set the container to be the same height as a capital letter. Then
when `isTruncated` sets `overflow: hidden`, the ascenders & descenders are cut
off. By setting a `lineGap` (or `leading` or `lineHeight`), the height of the
container is increased to stop the cut off while maintaining the correct
