Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dollarshaveclub/shave
💈 Shave is a 0 dep JS plugin that truncates text to fit within an element based on a set max-height ✁
https://github.com/dollarshaveclub/shave
ellipsis multi-line truncate
Last synced: about 1 month ago
JSON representation
💈 Shave is a 0 dep JS plugin that truncates text to fit within an element based on a set max-height ✁
- Host: GitHub
- URL: https://github.com/dollarshaveclub/shave
- Owner: dollarshaveclub
- License: mit
- Archived: true
- Created: 2016-10-19T21:54:46.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2020-10-27T20:20:25.000Z (about 4 years ago)
- Last Synced: 2024-04-26T00:08:40.375Z (7 months ago)
- Topics: ellipsis, multi-line, truncate
- Language: JavaScript
- Homepage: https://github.com/yowainwright/shave
- Size: 30.2 MB
- Stars: 2,112
- Watchers: 61
- Forks: 121
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
This software is maintained under a new repository located at yowainwright/shave
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
***
----
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
- is fast and capable of truncating text within lots of elements [quickly](http://codepen.io/pwfisher/full/ozVAyr/)
- 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](https://en.wikipedia.org/wiki/ASCII)).
## Installing from a package manager
npm
```sh
npm install shave --save
```
bower
```sh
bower install shave --save
```
yarn
```sh
yarn add shave
```
## Usage
Add **dist/shave.js** to your html
- Or, **dist/jquery.shave.js** for jQuery/Zepto as of Shave >= v2.
Or as a module
```sh
import shave from 'shave';
```
## 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 });
```
----
You can also use **shave** as a [jQuery](http://jquery.com/) or [Zepto](http://zeptojs.com/) 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 });
```
## Examples
[Codepen example](http://codepen.io/yowainwright/pen/5f471214df90f43c7996c5914c88e858/) with plain javascript.
[Codepen example](http://codepen.io/yowainwright/pen/c35ad7a281bc58ce6f89d2adb94c5d14/) with jQuery.
[Codepen example](http://codepen.io/yowainwright/pen/wzVgMp) 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](https://caniuse.com/#feat=css-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](http://oli.me.uk/2013/06/08/searching-javascript-arrays-with-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](http://codepen.io/yowainwright/pen/yVBxGY) and [click](http://codepen.io/yowainwright/pen/PbYdvL/) 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](https://github.com/yowainwright/truncated.js) and maintained by [Jeff Wainwright](https://github.com/yowainwright) with [Dollar Shave Club Engineering](https://github.com/dollarshaveclub).