---

Shave ✁

Shave is a zero dependency javascript plugin that truncates multi-line text to fit within an html element based on a set pixel number max-height. It then stores the _diff_ of the original text string in a hidden element following the visible text. This means the original text remains intact!

---

Shave, compared to other truncation plugins:

- maintains the original text after truncation.
- does not require other libraries
- only requires a selector and a max height
- is very lightweight; ~1.5kb unminified
- allows for custom ellipsis strings and class names but doesn't over complicate
- new! provides ellipsis link functionality
- is fast and capable of truncating text within lots of elements quickly
- is additive. It will play nice with other javascript libraries and more truncation features can easily be built with it.
- supports non-spaced languages (Non-ascii).

Installing from a package manager

``sh
npm i shave -D
`

`
yarn add shave -D
`

`
pnpm i shave -D
`

Usage

Add dist/shave.js to your html

- Or, dist/jquery.shave.js for jQuery/Zepto as of Shave >= v2.

Or as a module

`javascript
import shave from 'shave';
`

Arguments

Argument structure is as follows:

`javascript
shave("selector", maxheight, { options });
`

Argument type breakdown:

| argument | type | required | description | example |
| :--------: | :----------: | :------: | :------: | :------: |
| "selector" | string | yes | used to select items to shave | ".js-is-shaved" |
| maxheight | number | yes | used to specify the maximum height | 50 |
| "options" | object | no | use to modify how items are shaved | { character: "..." } |

Options object breakdown:

| options | type | default | description |
| :--------: | :------: | :------: | :------: |
| character: | string | "…" | character to use for ellipsis |
| charclassname: | string | 'js-shave-char' | class name to use for ellipsis element |
| classname: | string | 'js-shave' | class to add to the element |
| spaces: | boolean | false | if true, spaces will be preserved** |
| link: | object | undefined | an object accepting any link accociated |

Syntax

Basic setup

`javascript
shave("selector", maxheight);
// shave('.shave-selector', 0) for example
`

Shave also provided options _only_ to overwrite what it uses.

If you'd like have custom class names and not use .js-shave:

`javascript
shave("selector", maxheight, { classname: "classname" });
`

Or if you'd like to have custom characters (instead of the standard ellipsis):

`javascript
shave("selector", maxheight, { character: "✁" });
`

Or both:

`javascript
shave("selector", maxheight, { classname: "classname", character: "✁" });
`

Without spaces:

`javascript
shave("selector", maxheight, { spaces: false });
`

With an (link) tag:

`javascript
/**
* @notes
* - provide your desired link attributes here!
* @note link attributes trump the character option and className of the ellipsis element
*/
shave("selector", maxheight, { link: LinkObject });
`

---

You can also use shave as a jQuery or Zepto plugin. As of Shave >= v2, use dist/jquery.shave.js for jQuery/Zepto.

`javascript
$("selector").shave(maxheight);
`

And here's a _jQuery/Zepto_ example with custom options:

`javascript
$("selector").shave(maxheight, { classname: "your-css-class", character: "✁" });
`

If you're using a non-spaced language, you can support shave by setting an option spaces to false.

`javascript
$("selector").shave(maxheight, {
classname: "your-css-class",
character: "✁",
spaces: false
});
`

With an (link) tag:

`javascript
/**
* @notes
* - provide your desired link attributes here!
* @note link attributes trump the character option and className of the ellipsis element
*/
$("selector").shave(maxheight, { link: LinkObject });
`

Prefer Link Functionality

The shave plugin provides a link option—an element which replaces the default element.
As any functionality that is needed without an href attribute can be made using the default element, the is only rendered if the href attribute is provided.

Any attributes that can be used for an element can be added to the link object when invoking shave.
Additionally textContent can be added to replace the default character option.

Here's a more in-depth example than the basic example(s) above:

`javascript
shave("selector", 50, { link: { href: 'https://www.google.com', textContent: 'Read More here' } });
`

> note: if an href is not specified, the link will not be created!

Examples

Codepen example with plain javascript.

Codepen example with jQuery.

Codepen example with a non-spaced language.

Notes

text-overflow: ellipsis is the way to go when truncating text to a single line. Shave does something very similar to text-overflow: ellipsis but for _multiple lines_ when line-clamp is not supported. Shave bypasses being a line-clamp` polyfill by only accepting a max-height number. This keeps shave a fast and light weight utility.

Shave implements a binary search to truncate text in the most optimal way possible.

Shave is meant to truncate text within a selected html element. This means it will overwrite html within an html element with just the text within the selected element.

Here are some super basic examples of shave with window resize and click events. 🙌

Shave works in all modern browsers and was tested in some not so modern browsers (like Internet Explorer 8) - it works there too. 🍻

---

Created and maintained by Jeff Wainwright with Dollar Shave Club Engineering.