Angular Highlight.js


Instant code highlighting directives
___

Table of Contents

- Live Demo | Stackblitz
- Installation
- Usage
- Lazy-load highlight.js script
- Import highlight.js theme
- Highlight usage
- HighlightAuto usage
- Line numbers addon usage
- Plus package
- Issues
- Author
- More plugins

Installation

Install with NPM

``bash
npm i ngx-highlightjs
`



Usage

$3

`typescript
import { provideHighlightOptions } from 'ngx-highlightjs';

export const appConfig: ApplicationConfig = {
providers: [
provideHighlightOptions({
fullLibraryLoader: () => import('highlight.js')
})
]
};
`

> Note: This includes the entire Highlight.js library with all languages.

You can also opt to load only the core script and the necessary languages.

$3

`typescript
import { provideHighlightOptions } from 'ngx-highlightjs';

export const appConfig: ApplicationConfig = {
providers: [
provideHighlightOptions({
coreLibraryLoader: () => import('highlight.js/lib/core'),
lineNumbersLoader: () => import('ngx-highlightjs/line-numbers'), // Optional, add line numbers if needed
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, useful for dynamic theme changes
})
]
};
`

$3

| Name | Description |
|--------------------|--------------------------------------------------------------------------------------------------------------------------------|
| fullLibraryLoader | A function returning a promise to load the entire highlight.js script |
| coreLibraryLoader | A function returning a promise to load the core highlight.js script |
| lineNumbersLoader | A function returning a promise to load the lineNumbers script for adding line numbers |
| languages | The languages to register with Highlight.js (Needed only if you opt to use coreLibraryLoader) |
| config | Set Highlight.js configuration, see configure-options |
| lineNumbersOptions | Set line numbers plugin options |
| themePath | The path to the CSS file for the highlighting theme |

$3

Dynamic Approach

Set the theme path in the global configuration to enable dynamic theme changes:

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

Alternatively, import the theme from the app's distribution folder or use a CDN link.

When switching between app themes, call the setTheme(path) method from the HighlightLoader service.

`ts
import { HighlightLoader } from 'ngx-highlightjs';

export class AppComponent {

private hljsLoader: HighlightLoader = inject(HighlightLoader);

onAppThemeChange(appTheme: 'dark' | 'light') {
this.hljsLoader.setTheme(appTheme === 'dark' ? 'assets/styles/solarized-dark.css' : 'assets/styles/solarized-light.css');
}
}
`

Traditional Approach

In angular.json:

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

Or directly in src/style.scss:

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

_List of all available themes from highlight.js_

$3

To apply code highlighting, use the highlight directive. It requires setting the target language, with an optional feature to ignore illegal syntax.

`ts
import { Highlight } from 'ngx-highlightjs';

@Component({
selector: 'app-root',
template:

,
imports: [Highlight]
})
export class AppComponent {
}
`

#### Options

| Name | Type | Description |
|----------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [highlight] | string | Code to highlight. |
| [language] | string | Parameter must be present and specify the language name or alias of the grammar to be used for highlighting. |
| [ignoreIllegals] | boolean | An optional parameter that when true forces highlighting to finish even in case of detecting illegal syntax for the language instead of throwing an exception. |
| (highlighted) | HighlightResult | Stream that emits the result object when element is highlighted |




$3

The highlightAuto directive works the same way but automatically detects the language to apply highlighting.

`ts
import { HighlightAuto } from 'ngx-highlightjs';

@Component({
selector: 'app-root',
template:

,
imports: [HighlightAuto]
})
export class AppComponent {
}
`

#### Options

| Name | Type | Description |
|---------------------|---------------------|------------------------------------------------------------------------------------------------------------|
| [highlightAuto] | 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 |
| (highlighted) | AutoHighlightResult | Stream that emits the result object when element is highlighted |




Line Numbers Directive Usage

The lineNumbers directive extends highlighted code with line numbers. It functions in conjunction with the highlight and highlightAuto directives.

`ts
import { HighlightAuto } from 'ngx-highlightjs';
import { HighlightLineNumbers } from 'ngx-highlightjs/line-numbers';

@Component({
selector: 'app-root',
template:

,
imports: [HighlightAuto, HighlightLineNumbers]
})
export class AppComponent {
}
`

#### Options

| Name | Type | Description |
|------------------|---------|--------------------------------------------------------------|
| [singleLine] | boolean | Enable plugin for code block with one line, default false. |
| [startFrom] | number | Start numbering from a custom value, default 1. |

$3

During the project build process, you may encounter a warning stating WARNING in ... CommonJS or AMD dependencies can cause optimization bailouts.

To address this warning, include the following configuration in your angular.json file:

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

Read more about CommonJS dependencies configuration

Plus package

This package provides the following features:

- Utilizes the gists API to highlight code snippets directly from GitHub gists.
- Supports direct code highlighting from URLs.

$3

To integrate this addon into your project, ensure the presence of HttpClient by importing it into your main.ts file.

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

export const appConfig: ApplicationConfig = {
providers: [
provideHttpClient()
]
};
`

$3

1. Use [gist] directive, passing the gist ID as its attribute, to retrieve the response through the (gistLoaded) output event.
2. Upon the emission of (gistLoaded), gain access to the gist response.
3. Use gistContent pipe to extract the file's content from the gist response based on the specified file name.

Example:

`ts
import { HighlightPlusModule } from 'ngx-highlightjs';

@Component({
selector: 'app-root',
template:

,
imports: [HighlightPlusModule]
})
export class AppComponent {
}
`

$3

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

To highlight all files within a gist, iterate through gist.files and utilize the keyvalue pipe to pass the file name into the gistContent pipe.

Example:

`ts
import { HighlightPlusModule } from 'ngx-highlightjs';

@Component({
selector: 'app-root',
template:

@for (file of gist?.files | keyvalue; track file.key) {

}

,
imports: [HighlightPlusModule, CommonModule]
})
export class AppComponent {
}
`

$3

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

Example:

`ts
import { HighlightPlusModule } from 'ngx-highlightjs';

@Component({
selector: 'app-root',
template:

,
imports: [HighlightPlusModule, CommonModule]
})
export class AppComponent {
}
`

$3

The package offers the provideHighlightOptions function, allowing you to set your clientId and clientSecret for the gist HTTP requests.
You can provide these options in your app.config.ts file as demonstrated below:

`ts
import { provideHttpClient } from '@angular/common/http';
import { provideHighlightOptions } from 'ngx-highlightjs/plus'

export const appConfig: ApplicationConfig = {
providers: [
provideHttpClient(),
provideGistOptions({
clientId: 'CLIENT_ID',
clientSecret: 'CLIENT_SECRET'
})
]
};
``

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