ngx-nested-ellipsis

ngx-nested-ellipsis

Library for angular (>= 12.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 installed module to your app.module.ts:

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

// ...

@NgModule({
  // ...
  imports: [
    // ...
    NestedEllipsisModule
  ]
  // ...
})
export class AppModule {}

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.

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 or a ponyfill if not implemented by the browser (See Web/API/ResizeObserver and @juggle/resize-observer) 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:

• Run npm ci
• Adept version and author in ./projects/ngx-nested-ellipsis/package.json and commit the changes to your fork.
• Run npm run build-lib which outputs the build to ./dist/ngx-nested-ellipsis.
• Copy README.md to ./dist/ngx-nested-ellipsis and modify it accordingly.
• Run cd ./dist/ngx-nested-ellipsis && npm publish.

Running unit tests

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

Thank you...

• ... Tremayne Christ for writing the @juggle/resize-observer package which is internally used by this module.

License

MIT