js-snip

!GitHub
!GitHub issues
!npm bundle size

Universal JavaScript library for clamping HTML text elements.

#### Key features:
* two snipping modes (CSS / JavaScript)
* no need to specify line heights
* re-snipping on element resize
* no dependencies


To get a hands-on experience try the Interactive Demo.

Installation

``bash


install with npm

npm install js-snip

or with yarn

yarn add js-snip
`

Core API

`typescript
export interface Snip {
(element: HTMLElement, options?: Partial>, onSnipped?: OnSnipped): void
}

export interface Unsnip {
(element: HTMLElement): void
}
`

Usage

`typescript
import { snip, unsnip } from 'js-snip'

// minimal example
snip(element)

// with options
snip(element, { lines: 3 })

// with several options
snip(element, { lines: 3, mode: 'js', midWord: false })

// with options and callback
snip(element, { lines: 3 }, (newState, oldState) => {
// ...
})

// unsnipping the element
unsnip(element)
`

Options

`typescript
export interface SnipOptions {
mode: 'css' | 'js'
lines: number
ellipsis: string
midWord: boolean
textContent: string
}

// your options will get merged with the defaults
export const defaultOptions: Readonly = {
mode: 'css',
lines: 3,
ellipsis: '.\u200A.\u200A.',
midWord: true,
textContent: null,
}
`

State

Each snipped element has an internal state:

`typescript
export interface SnipState {
hasEllipsis: boolean
}
`

Callback

Callback will be executed immediately after the initial snipping and after each subsequent snipping (after resize etc.). It allows you to react to state changes:

`typescript
export interface OnSnipped {
(newState: Readonly, oldState: Readonly): void
}
`

How it works

- CSS mode is based on the -webkit-line-clamp.
- JavaScript mode works by cutting the element's textContent in a loop until the content fits into the given number of lines.

Note: CSS mode is faster (preferred), but does not work in older browsers / in all situations (f.e. does not work in IE11, when you need the text to flow around a floated element, or when you want a custom ellipsis).

$3

For the library to be able to determine the number of lines / hide the text-overflow properly, the height of the element should be the same as the height of the text. Be wary of any CSS steps that will affect the height of the element. Some of the common examples:
* vertical paddings
* fixed height / fixed min-height
* making the element a flex-item (flex container's align-items defaults to stretch)
* making the element height grow with the flex-grow in the column flex layout.

Note: You can still use the directive with flexbox, just make sure to change the default align-items / align-self value to flex-start or whatever fits your case.

IE11 Support

IE11 does not support -webkit-line-clamp (falls back to the JS mode), and the ResizeObserver API. This API needs to be polyfilled if you want to re-snip the elements on the resize in IE11 (they would still get snipped when inserted / on data change without the polyfill). Recommended: @juggle/resize-observer

` javascript
import { ResizeObserver as Polyfill } from '@juggle/resize-observer';

window.ResizeObserver = window.ResizeObserver || Polyfill;
``

Change Log

All changes are documented in the change log.