ngx-nested-ellipsis

ngx-nested-ellipsis

Library for angular (>= 16.0.0) providing a directive to display an ellipsis if the containing text would overflow.

Supports dynamic html contents. (If you require text contents only, you might want to take a look at ngx-ellipsis, which offers better performance, but escapes any html contents to text.)

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-nested-ellipsis --save.

Then add the directive to the component, in which you want to use the ellipsis:

import { NestedEllipsisDirective } from 'ngx-nested-ellipsis';

@Component({
  // ...
  imports: [
    // ...
    NestedEllipsisDirective
  ]
  standalone: true
})
export class YourFancyComponent {}

Usage

Anywhere in your template:

<div style="width: 130px; height: 18px;">
  <ng-template [nestedEllipsis]>Your very long <em>rich</em> text</ng-template>
</div>

As you can see, you need to define the dimensions of your element yourself. (ngx-nested-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.

Module import

Should you not be using angular standalone components in your project (available since angular 16), import NestedEllipsisModule in your module instead - see old instructions for an example.

Extra options

You may add the following attributes to change the directive's behavior:

attribute	meaning
nestedEllipsis	required Passing true (default) will perform the directive's task otherwise the template will be rendered without truncating its contents.
nestedEllipsisIndicator	Passing a string (default: '...') will append it when the passed template has been truncated. Passing a template will append that template instead.
nestedEllipsisWordBoundaries	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 nestedEllipsisWordBoundaries=" " will allow the text to break at spaces only
nestedEllipsisMayTruncateAtFn	Function that lets you specify whether the contents may be truncated at a certain point or not. (see callback API)
nestedEllipsisResizeDetection	How resize events should be detected - these are the possible values: resize-observer: default Use native ResizeObserver (See Web/API/ResizeObserver) window: 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="ngxNestedEllipsis" in the template and this.ell.applyEllipsis() in the component code.
nestedEllipsisChange	Event emitter - Will be emitted whenever the ellipsis has been recalculated (depending on nestedEllipsisResizeDetection). If the text had to be truncated the position of the last visible character will be emitted, else null.

nestedEllipsisMayTruncateAtFn API

Callback function parameters:

name	type	description
node	CharacterData	Text node that is checked for truncation
position	number	Position within that text node where the text might be truncated

Return true if truncating at this point in this node should be allowed.

Build & publish on npm

In case you want to contribute/fork:

1. Run npm ci
2. Adept version and author in ./projects/ngx-nested-ellipsis/package.json and ./README and commit the changes to your fork.
3. Run npm run build-lib which outputs the build to ./dist/ngx-nested-ellipsis.
4. To publish your build, run npm run publish-lib.

Running unit tests

Run npm run test to execute the unit tests via Karma.

License

MIT