ngx-highlightjs

Angular Highlight.js

Instant code highlighting, auto-detect language, super easy to use

---

Table of Contents

• Live Demo | Stackblitz
• Installation
• Usage
• Development
• Issues
• Author
• More plugins

Installation

Install with NPM

npm i ngx-highlightjs

Usage

Provide the config for HIGHLIGHT_OPTIONS in main.ts file

import { HIGHLIGHT_OPTIONS } from 'ngx-highlightjs';

bootstrapApplication(AppComponent, {
  providers: [
    {
      provide: HIGHLIGHT_OPTIONS,
      useValue: {
        fullLibraryLoader: () => import('highlight.js')
      }
    }
  ]
})

Note: This will add highlight.js library including all languages to your bundle.

To avoid import everything from highlight.js library, you should import each language you want to highlight manually.

Import only the core library and the needed highlighting languages

import { HIGHLIGHT_OPTIONS } from 'ngx-highlightjs';

bootstrapApplication(AppComponent, {
  providers: [
    {
      provide: HIGHLIGHT_OPTIONS,
      useValue: {
        coreLibraryLoader: () => import('highlight.js/lib/core'),
        lineNumbersLoader: () => import('ngx-highlightjs/line-numbers'), // Optional, only if you want the line numbers
        languages: {
          typescript: () => import('highlight.js/lib/languages/typescript'),
          css: () => import('highlight.js/lib/languages/css'),
          xml: () => import('highlight.js/lib/languages/xml')
        },
        themePath: 'path-to-theme.css' // Optional, and useful if you want to change the theme dynamically
      }
    }
  ]
})

HighlightOptions API

Name	Description
fullLibraryLoader	A function that returns a promise that loads highlight.js full script
coreLibraryLoader	A function that returns a promise that loads highlight.js core script
lineNumbersLoader	A function that returns a promise that loads line-numbers script which adds line numbers to the highlight code
languages	The set of languages to register
config	Set highlight.js config, see configure-options
themePath	The path to highlighting theme CSS file

NOTE: Since the update of highlight.js@v10.x.x, should use coreLibraryLoader: () => import('highlight.js/lib/core') instead of coreLibraryLoader: () => import('highlight.js/lib/highlight')

Import highlighting theme

In version >=6.1.0, A new way is available to load the theme dynamically! this is OPTIONAL, you can still use the traditional way.

Dynamic way

Set the theme path in the global config, this makes it possible to change the theme on the fly, which is useful if you have light and dark theme in your app.

 providers: [
  {
    provide: HIGHLIGHT_OPTIONS,
    useValue: {
      // ...
      themePath: 'assets/styles/solarized-dark.css'
    }
  }
]

If you want to import it from the app dist folder, then copy the themes you want to your assets directory, or you can just use a CDN link to the theme.

When switching between the app themes you need to call the setTheme(path) from the HighlightLoader service.

import { HighlightLoader } from 'ngx-highlightjs';

export class AppComponent {

  constructor(private hljsLoader: HighlightLoader) {
  }

  // Assume you have a callback function when your app theme is changed
  onAppThemeChange(appTheme: 'dark' | 'light') {
    this.hljsLoader.setTheme(appTheme === 'dark' ? 'assets/styles/solarized-dark.css' : 'assets/styles/solarized-light.css');
  }
}

You can still use the traditional way

Traditional way

To import highlight.js theme from the node_modules directory in angular.json

"styles": [
  "styles.css",
  "../node_modules/highlight.js/styles/github.css",
]

Or directly in src/style.scss

@import '~highlight.js/styles/github.css';

List of all available themes from highlight.js

Use highlight directive

The following line will highlight the given code and append it to the host element

import { HighlightModule } from 'ngx-highlightjs';

@Component({
  selector: 'app-root',
  template: `
    <pre><code [highlight]="code"></code></pre>
  `,
  standalone: true,
  imports: [
    HighlightModule
  ]
})
export class AppComponent {
}

Demo stackblitz

Options

Name	Type	Description
[highlight]	string	Accept code string to highlight, default null
[languages]	string[]	An array of language names and aliases restricting auto detection to only these languages, default: null
[lineNumbers]	boolean	A flag that indicates adding line numbers to highlighted code element
(highlighted)	HighlightAutoResult	Stream that emits the result object when element is highlighted

NOTE

In Angular 10, when building your project, you might get a warning WARNING in ... CommonJS or AMD dependencies can cause optimization bailouts.

To avoid this warning, add the following in your angular.json

{
  "projects": {
    "project-name": {
      "architect": {
        "build": {
          "options": {
            "allowedCommonJsDependencies": [
              "highlight.js"
            ]
          }
        }
      }
    }
  }
}

Read more about CommonJS dependencies configuration

Plus package

This package contains the following features:

• Highlight gists using gists API
• Highlight code directly from URL

Usage

The plus package relies on HttpClient to make the http requests, ensure that it is imported in your main.ts file

import { provideHttpClient } from '@angular/common/http';

bootstrapApplication(AppComponent, {
  providers: [
    provideHttpClient(),
    {
      provide: HIGHLIGHT_OPTIONS,
      useValue: // ...
    }
  ]
})

Highlight a gist file

1. Use [gist] directive with the gist id to get the response through the output (gistLoaded).
2. Once (gistLoaded) emits, you will get access to the gist response.
3. Use gistContent pipe to extract the file content from gist response using gist file name.

Example:

import { HighlightPlusModule } from 'ngx-highlightjs';

@Component({
  selector: 'app-root',
  template: `
    <pre [gist]="gistId" (gistLoaded)="gist = $event">
      <code [highlight]="gist | gistContent: 'main.js'"></code>
    </pre>
  `,
  standalone: true,
  imports: [HighlightPlusModule]
})
export class AppComponent {
}

Highlight all gist files

To loop over gist?.files, use keyvalue pipe to pass file name into gistContent pipe.

Example:

import { HighlightPlusModule } from 'ngx-highlightjs';

@Component({
  selector: 'app-root',
  template: `
    <ng-container [gist]="gistId" (gistLoaded)="gist = $event">
      <pre *ngFor="let file of gist?.files | keyvalue">
        <code [highlight]="gist | gistContent: file.key"></code>
      </pre>
    </ng-container>
  `,
  standalone: true,
  imports: [HighlightPlusModule, CommonModule]
})
export class AppComponent {
}

Highlight code from URL directly

Use the pipe codeFromUrl with the async pipe together to get the code text from a raw URL.

Example:

import { HighlightPlusModule } from 'ngx-highlightjs';

@Component({
  selector: 'app-root',
  template: `
   <pre>
     <code [highlight]="codeUrl | codeFromUrl | async"></code>
   </pre>
  `,
  standalone: true,
  imports: [HighlightPlusModule, CommonModule]
})
export class AppComponent {
}

Providing Gist API secret (Optional)

To take full advantage of the gist loader feature, the package provides GIST_OPTIONS token to set your clientId and clientSecret with the gist http requests, you can provide it in main.ts like in this example:

import { GIST_OPTIONS } from 'ngx-highlightjs/plus'

bootstrapApplication(AppComponent, {
  providers: [
    provideHttpClient(),
    {
      provide: HIGHLIGHT_OPTIONS,
      useValue: // ...
    },
    {
      provide: GIST_OPTIONS,
      useValue: {
        clientId: 'CLIENT_ID',
        clientSecret: 'CLIENT_SECRET'
      }
    },
  ]
})

Development

This project uses Angular CLI to build the package.

$ ng build ngx-highlightjs

Issues

If you identify any errors in the library, or have an idea for an improvement, please open an issue.

Author

Murhaf Sousli

• github/murhafsousli
• twitter/murhafsousli

More plugins

• ngx-scrollbar
• ngx-sharebuttons
• ngx-gallery
• ngx-progressbar
• ngx-bar-rating
• ngx-disqus
• ngx-wordpress
• ngx-teximate

Changelog

10.0.0

• feat: Migrate to Angular standalone components, closes #260 in cadcd11.
• fix: Add line-numbers as a sub package, closes #234 in 7f8f551.
• refactor: Update deprecated rxjs usage.

Breaking changes

• When using HighlightPlusModule, you must have provideHttpClient() provided in your main.ts file in order to make the http requests work.
• The line numbers plugin is now included within the package, the import path should point to the new sub-package ngx-highlightjs/line-numbers

providers: [
  {
    provide: HIGHLIGHT_OPTIONS,
    useValue: {
      lineNumbersLoader: () => import('ngx-highlightjs/line-numbers')
    }
  }
]