Skip to content

Cuttr is a javascript plugin that truncates multi-line text content with multiple truncation methods and custom ellipsis.

License

Notifications You must be signed in to change notification settings

d-e-v-s-k/cuttr-js

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

43 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Cuttr.js

preview

npm License Known Vulnerabilities License

Cuttr is a zero dependency, easy to use JS / jQuery library that truncates multiple line text content (Line Clampin’) to fit within given specifications. It adds an ending string like a ellipsis (...) to indicate that there is more text available than currently visible.

  • Multiple truncation methods
  • Truncate text without breaking the HTML
  • Custom ellipsis strings
  • Optional "Read more" anchor to expand original content

Demos online | Codepen Example


Overview

Install

Download

CDN

Link directly to Cuttr files on unpkg.

<script src="https://unpkg.com/cuttr@1/dist/cuttr.min.js"></script>
<!-- or -->
<script src="https://unpkg.com/cuttr@1/dist/cuttr.js"></script>

Link directly to Cuttr files on cdnjs.

<script src="https://cdnjs.cloudflare.com/ajax/libs/cuttr/1.4.3/cuttr.min.js"></script>
<!-- or -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/cuttr/1.4.3/cuttr.js"></script>

Package managers

npm

npm install cuttr -D

yarn

yarn add cuttr -D

bower

bower install d-e-v-s-k/cuttr-js --save

License

Commercial license

If you want to use Cuttr to develop commercial sites, themes, projects, and applications, the Commercial license is the appropriate license. With this option, your source code is kept proprietary. [Purchase a Cuttr Commercial License]

Open source license

If you are creating an open source application under a license compatible with the GNU GPL license v3, you may use Cuttr under the terms of the GPLv3.

The credit comments in the JavaScript files should be kept intact (even after combination or minification).

Read more about Cuttr's licenses.

Usage

As you can see in the example files, you will need to include:

  • The JavaScript file cuttr.js (or its minified version cuttr.min.js)

Including files:

<script type="text/javascript" src="cuttr.js"></script>

Or as a module

import Cuttr from 'Cuttr';

Initialization

Initialization with Vanilla Javascript

All you need to do is call cuttr.js before the closing </body> tag.

new Cuttr('.element', {
    //options here
    truncate: 'words',
    length: 12
});

Initialization with jQuery

You can use cuttr.js also as a jQuery plugin if you want to!

$(document).ready(function() {
    $('.element').Cuttr({
        //options here
        truncate: 'words',
        length: 12
    });
});

Options

let truncateElement = new Cuttr( '.container', {
    // DEFAULTS LISTED

    licenseKey: 'YOUR_KEY_HERE',
    // this option is compulsory 
    // use the license key provided on the purchase of the Cuttr Commercial License
    // if your project is open source and it is compatible with the GPLv3 license you can request a license key
    // please read more about licenses here https://github.com/d-e-v-s-k/cuttr-js#license
    
    truncate: 'characters',
    // Truncate method
    // How to truncate the text
    // ['characters'|'words'|'sentences']
    
    length: 100,
    // Truncation limit
    // After how much [characters|words|sentences] should the text be truncated
    // note: character truncation also counts html characters
    
    ending: '...',
    // Truncation ending string
    
    loadedClass: 'cuttr--loaded',
    // Class to set on truncated element when truncation finished

    title: false,
    // add original, full content to elements title attribute
    // [true|false]
    
    readMore: false,
    // enables / disables the "read more" button
    // [true|false]
    
    readMoreText: 'Read more',
    // text to show as "Read more" button to show full content
    
    readLessText: 'Read less',
    // text to show as "Read less" button to show truncated content
    
    readMoreBtnPosition: 'after',
    // "Read more" button position
    // ['after'|'inside']
    // 'after' = button will be appended after the truncated element
    // 'inside' = button will be appended inside the truncated element, at the end of the truncated content
    
    readMoreBtnTag: 'button',
    // "Read-more" button HTML tag
    //  ['button'|'a'|...]
    
    readMoreBtnSelectorClass: 'cuttr__readmore',
    // "Read-more" button class selector
    
    readMoreBtnAdditionalClasses: '',
    // "Read-more" button additional classes to be added
})

Methods

Each plugin instance comes with some public methods to call. See them in action inside the examples folder at methods.html.

Example Initialization:

let truncateElement = new Cuttr('.element', {
    //options here
    truncate: 'words',
    length: 12
});

After the plugin is fired, a series of methods are available.

expandContent()

Expands the given instance content.

truncateElement.expandContent();

truncateContent()

Truncates the given instance content.

truncateElement.truncateContent();

destroy()

Completely restores the Element to its pre-init state.

truncateElement.destroy();

Method usage with jQuery

In order to access the public methods via jQuery, you need to do it through jQuery's .data() function.

Example:

$(document).ready(function() {
    
    //  Cuttr initialization
    let truncateElement = $('.element').Cuttr({
        //options here
        truncate: 'words',
        length: 12
    });

    //  access html element's prototype via jQuery's .data()
    let truncData = truncateElement.data('Cuttr');
    //  call Cuttr method
    truncData.expandContent();
    
});

Callbacks

Each plugin instance provides some callbacks. See them in action inside the examples folder at callbacks.html.

At plugin initialization, a series of callbacks are available:

afterTruncate()

Callback fired once the original content has been truncated.

let truncateElement = new Cuttr('.element', {
    //options here
    truncate: 'words',
    length: 12,
    
    //  callbacks
    afterTruncate: function(){
        let truncateElement = this;
        console.log(this);
        alert('"afterTruncate" callback fired!');
    }
});

afterExpand()

Callback fired once the original content has been expanded.

let truncateElement = new Cuttr('.element', {
    //options here
    truncate: 'words',
    length: 12,
    
    //  callbacks
    afterExpand: function(){
        let truncateElement = this;
        console.log(this);
        alert('"afterExpand" callback fired!');
    }
});

Demos & Examples

Checkout our demos & examples page

More examples on Codepen:

Development

This project uses Gulp (v4) to minify the JS file. If you are unfamiliar with Gulp, check this tutorial on how to get started.
Run gulp in the command-line to put out a build on the files.

Browser support

The Cuttr javascript / jQuery string truncation plugin targets modern browsers that support ES5, meaning Internet Explorer 10 and earlier are not supported, but with IE11 and above you are fine.


Created and maintained by DEVSK.