ngx-ellipsis-v10 v2.3.2
ngx-ellipsis
Plugin for angular (>= 6.0.0) providing a directive to display an ellipsis if the containing text would overflow.
Supports text only - No HTML contents! (If you really do need html contents to be truncated, you might want to take a look at my spin-off lib: ngx-nested-ellipsis. It is able to do just that, but takes slightly more processing power to perform its task.)
Demo
For a demo either just checkout this project and run npm install && npm run start or visit the StackBlitz demo page.
Installation
For use in an existing angular project run npm install ngx-ellipsis --save.
Then add the installed module to your app.module.ts:
import { EllipsisModule } from 'ngx-ellipsis';
// ...
@NgModule({
// ...
imports: [
// ...
EllipsisModule
]
// ...
})
export class AppModule {}Usage
Anywhere in your template:
<div style="width: 100px; height: 100px;" ellipsis>Your very long text</div>
<!-- Or for dynamic content: -->
<div style="width: 100px; height: 100px;" ellipsis [ellipsis-content]="yourDynamicContent"></div>As you can see, you need to define the dimensions of your element yourself. (ngx-ellipsis doesn't automatically add any element styles.) But of course you don't need to use fixed widths/heights like in these examples. Flex layout shold work just fine for example.
Extra options
You may add the following attributes to change the directive's behavior:
| attribute | meaning |
|---|---|
| ellipsis | required If you pass an attribute value (e.g. ellipsis=" More ...") you can override the text that will be appended, should it be necessary to truncate the text (default: "...") |
| ellipsis-content | Use this for dynamic content, that will be subject to asynchronous changes (e.g.: [ellipsis-content]="myVar") |
| ellipsis-word-boundaries | If you pass this attribute, the text won't be truncated at just any character but only at those in the attribute's value. For example ellipsis-word-boundaries=" \n" will allow the text to break at spaces and newlines only |
| ellipsis-substr-fn | substr function to use for string splitting. Defaults to the native String#substr. (This may for example be used to avoid splitting surrogate pairs - used by some emojis - by providing a lib such as runes.) |
| ellipsis-resize-detection | How resize events should be detected - these are the possible values: element-resize-detector: default Use wnr/element-resize-detector with its scroll strategy. (-> Even when you change the element's width using javascript, the ellipsis will auto-adept)element-resize-detector-object: deprecated Use wnr/element-resize-detector with its object strategywindow: Only listen if the whole window has been resized/changed orientation (Possibly better performance, but obviously won't trigger on resize caused directly or indirectly by javascript.)manual: Ellipsis is never applied automatically. Instead the consuming app may use #ell="ellipsis" in the template and this.ell.applyEllipsis() in the component code. |
| ellipsis-click-more | Event emitter - If set, the text defined by the ellipsis attribute will be converted into a clickable link. For example (ellipsis-click-more)="moreClicked()" will call your component's moreClicked() method when the user clicks on the link. |
| ellipsis-change | Event emitter - Will be emitted whenever the ellipsis has been recalculated (depending on ellipsis-resize-detection). If the text had to be truncated the position of the last visible character will be emitted, else null. |
Build & publish on npm
In case you want to contribute/fork:
- Run
npm install - Adept version and author in
./projects/ngx-ellipsis/package.jsonand commit the changes to your fork. - Run
npm run build-libwhich outputs the build to./dist/ngx-ellipsis. - Copy README.md to
./dist/ngx-ellipsisand modify it accordingly. - Run
cd ./dist/ngx-ellipsis && npm publish.
Running unit tests
Run npm run test ngx-ellipsis to execute the unit tests via Karma.
Thank you...
- ... Lucas Wiener for writing the element-resize-detector package which is internally used by this module.
License
MIT