/multiline-clamp

Enables text on a website to be truncated over multiple lines which is not widely supported in CSS natively.

Primary LanguageJavaScriptMIT LicenseMIT

Multiline Clamp

license fossa gzipped size dev deps build status npm jsDelivr

An lightweight and performance-minded library that minipulates DOM content in a respectful and transparent manor.

Even in the modern age of browsers, technologies and API's alike; we still don't have a full-proof method that enables a designers vision when they show off some cool multiline text with an ellipsis at the end. I needed a solution for a project that not only allowed me to clamp text over multiple lines but also over multiple breakpoints too.

Looking around the web I found a couple of decent libraries but nothing that has decent breakpoint support out-of-the-box.

So How Does It Work?

Good question!

Rather than calculating positions, widths etc., my solution is allowing a developer to specifically define how many characters should be displayed before a clamp is applied. This solution also takes HTML elements into account which can break the clamp entitely, so instead I also allow a configurable regular expression to be defined which automatically strips elements out if they are at the end which has the added benifit of not destroying the original intention of the text.

Browser Support

I don't claim to have 100% browser support but if you find an issue please create one and I'll try and get to it.

Chrome Firefox Safari Opera Edge IE
Latest ✔ Latest ✔ Latest ✔ Latest ✔ Latest ✔ 10+ ✔

Installation

Using npm:

$ npm install multiline-clamp --save

Using Yarn:

$ yarn add multiline-clamp

Using CDN:

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/multiline-clamp/dist/multiline-clamp.min.js"></script>

<!-- unpkg -->
<script src="https://unpkg.com/multiline-clamp/dist/multiline-clamp.min.js"></script>

Usage

If you are using a tool such as Webpack or Rollup, you may use ES6 or CommonJS imports which expose the MultilineClamp class.

var MultilineClamp = require('multiline-clamp');
import MultilineClamp from 'multiline-clamp';

Example

Getting set up is quick and simple, simply define the element you wish to clamp on your page and you're good to go.

new MultilineClamp(document.querySelector('p'))

Bind to a NodeList

There may also come a time when you need to bind a clamp to many targets, this can be accomplished by passing a collection to the constructor.

new MultilineClamp(document.querySelectorAll('p'))

Responsive

You can also define per breakpoint clamps for any resolution you choose. This can be done by setting the responsive property which accepts an object.

new MultilineClamp(document.querySelector('p'), {
  responsive: {
    768: 50,
    480: 30
  }
})

API

MultilineClamp(target, options)

parameter description
target Type: Element, NodeList
Required: Yes
options Type: Object
Default: {}
Required: No

Please see the options list below for a complete list.

Options

clamp

string | element, defaults to ....

A string or element that is appended after the clamped content. When using an element you can simply pass the HTMLElement node as the value.

clampSize

number, defaults to 72.

The number of characters that should appear before the ellipsis.

partialTags

string, defaults to complete.

Defines how partial/invalid tags are handled when found in a clamped string. Valid values are:

  • complete — Completes the partial tag by restoring the closing end of the tag (only works for partial closing tags)
  • pull — Pulls the clamp back to just before the tag, this strips all content within it
  • pull-and-retain — Removes the tag but retains any content that was within it

responsive

boolean | { [number]: number }, defaults to false.

Allows an object of clamps to be defined for different breakpoints. Please see the example above.

tagsExpression

expression, defaults to /<(.|\n)*?>/g.

Regular expression for matching certain tags within the content.

trimWhitespace

boolean | expression, defaults to true.

Defines whether the whitespace before/after the content should be stripped out. false disables this functionality, setting a regular expression allows more finite control over how the spaces are handled.

Performance

I am constantly trying new ways to improve the performance of Multiline Clamp through the use of modern API's but it's not possible to promise your result will match mine. Through my testing in Google Chrome and Firefox, performance exceeds my expectations with a respectful amount of elements on the page.

If you have ideas for improving my implementation feel free to make a pull request.

Todo

  • Ignore tags in the clamping process, this will ensure the correct clamp size is maintained instead of counting tags which can increase/decrease the amount of content left

Resources

License

MIT