@dotcms/angular
Advanced tools
The @dotcms/angular SDK is the DotCMS official Angular library. It empowers Angular developers to build powerful, editable websites and applications in no time.
For Production Use:
For Testing & Development:
For Local Development:
For a step-by-step guide on setting up the Universal Visual Editor, check out our easy-to-follow instructions and get started in no time!
[!TIP] Make sure your API Token has read-only permissions for Pages, Folders, Assets, and Content. Using a key with minimal permissions follows security best practices.
This integration requires an API Key with read-only permissions for security best practices:
For detailed instructions, please refer to the dotCMS API Documentation - Read-only token.
npm install @dotcms/angular@latest
This will automatically install the required dependencies:
@dotcms/uve: Enables interaction with the Universal Visual Editor for real-time content editing@dotcms/client: Provides the core client functionality for fetching and managing dotCMS dataThe recommended way to configure the DotCMS client in your Angular application is to use the provideDotCMSClient function in your app.config.ts:
import { ApplicationConfig } from '@angular/core';
import { provideDotCMSClient } from '@dotcms/angular';
import { environment } from './environments/environment'; // Assuming your environment variables are here
export const appConfig: ApplicationConfig = {
providers: [
provideDotCMSClient({
dotcmsUrl: environment.dotcmsUrl,
authToken: environment.authToken,
siteId: environment.siteId
})
]
};
Then, you can inject the DotCMSClient into your components or services:
import { Component, inject } from '@angular/core';
import { DotCMSClient } from '@dotcms/angular';
@Component({
selector: 'app-my-component',
template: `<!-- Your component template -->`
})
export class MyComponent {
dotcmsClient = inject(DotCMSClient);
ngOnInit() {
this.dotcmsClient.page
.get({ url: '/about-us' })
.then(({ pageAsset }) => {
console.log(pageAsset);
});
}
}
Configure a proxy to leverage the powerful dotCMS image API, allowing you to resize and serve optimized images efficiently. This enhances application performance and improves user experience, making it a strategic enhancement for your project.
Create a proxy.conf.json file in your project:
// proxy.conf.json
{
"/dA": {
"target": "http://localhost:8080", // Your dotCMS instance URL
"secure": false, // Set to true if using HTTPS
"changeOrigin": true // Required for hosting scenarios
}
}
Add the proxy configuration to your angular.json:
// angular.json
{
"projects": {
"my-app": {
"architect": {
"serve": {
"builder": "@angular-devkit/build-angular:dev-server",
"options": {
"proxyConfig": "src/proxy.conf.json"
}
}
}
}
}
}
Once configured, image URLs in your components will automatically be proxied to your dotCMS instance:
📚 Learn more about Image Resizing and Processing in dotCMS with Angular.
// /components/my-dotcms-image.component.ts
@Component({
template: `
<img [src]="'/dA/' + contentlet.inode" alt="Asset from dotCMS" />
`
})
class MyDotCMSImageComponent {
@Input() contentlet: DotCMSBasicContentlet;
}
NgOptimizedImage Directive (Recommended)To optimize images served from dotCMS in your Angular app, we recommend using the built-in NgOptimizedImage directive. This integration supports automatic image preloading, lazy loading, and improved performance.
We provide a helper function provideDotCMSImageLoader() to configure image loading with your dotCMS instance.
Add the image loader to your app.config.ts:
// src/app/app.config.ts
import { provideDotCMSImageLoader } from '@dotcms/angular';
import { ApplicationConfig } from '@angular/core';
export const appConfig: ApplicationConfig = {
providers: [
provideDotCMSImageLoader(environment.dotcmsUrl)
]
};
Once configured, you can use the NgOptimizedImage directive to render dotCMS images:
// src/components/my-dotcms-image.component.ts
@Component({
selector: 'my-dotcms-image',
template: `
<img [ngSrc]="imagePath" alt="Asset from dotCMS" />
`,
standalone: true
})
export class MyDotCMSImageComponent {
@Input() contentlet!: DotCMSBasicContentlet;
get imagePath() {
return this.contentlet.image.versionPath;
}
}
📚 Learn more about
NgOptimizedImage
The following example demonstrates how to quickly set up a basic dotCMS page renderer in your Angular application. This example shows how to:
// /src/app/pages/dotcms-page.component.ts
import { Component, signal } from '@angular/core';
import { DotCMSLayoutBody, DotCMSEditablePageService} from '@dotcms/angular';
import { getUVEState } from '@dotcms/uve';
import { DotCMSPageAsset } from '@dotcms/types';
import { DOTCMS_CLIENT_TOKEN } from './app.config';
const DYNAMIC_COMPONENTS = {
Blog: import('./blog.component').then(c => c.BlogComponent),
Product: import('./product.component').then(c => c.ProductComponent)
};
@Component({
selector: 'app-pages',
standalone: true,
imports: [DotCMSLayoutBody],
providers: [DotCMSEditablePageService, DOTCMS_CLIENT_TOKEN],
template: `
@if (pageAsset()) {
<dotcms-layout-body
[pageAsset]="pageAsset"
[components]="components()"
/>
} @else {
<div>Loading...</div>
}
`
})
export class PagesComponent {
private readonly dotCMSClient: DotCMSClient = inject(DOTCMS_CLIENT_TOKEN);
private readonly editablePageService = inject(DotCMSEditablePageService);
readonly components = signal(DYNAMIC_COMPONENTS);
readonly pageAsset = signal<DotCMSPageAsset | null>(null);
ngOnInit() {
this.dotCMSClient.page
.get({ url: '/my-page' })
.then(({ pageAsset }) => {
if(getUVEState()) {
this.#subscribeToPageUpdates(response);
return;
}
this.pageAsset.set(pageAsset);
});
}
#subscribeToPageUpdates(response: DotCMSPageResponse) {
this.editablePageService
.listen(response)
.subscribe({ pageAsset } => this.pageAsset.set(pageAsset));
}
}
Looking to get started quickly? We've got you covered! Our Angular starter project is the perfect launchpad for your dotCMS + Angular journey. This production-ready template demonstrates everything you need:
📦 Fetch and render dotCMS pages with best practices 🧩 Register and manage components for different content types 🔍 Listing pages with search functionality 📝 Detail pages for blogs 📈 Image and assets optimization for better performance ✨ Enable seamless editing via the Universal Visual Editor (UVE) ⚡️ Leverage Angular's dependency injection and signals for optimal performance
[!TIP] This starter project is more than just an example, it follows all our best practices. We highly recommend using it as the base for your next dotCMS + Angular project!
All components, directives, and services should be imported from @dotcms/angular.
DotCMSLayoutBody is a component used to render the layout for a DotCMS page, supporting both production and development modes.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
page | DotCMSPageAsset | ✅ | - | The page asset containing the layout to render |
components | DotCMSPageComponent | ✅ | {} | Map of content type → Angular component |
mode | DotCMSPageRendererMode | ❌ | 'production' | Rendering mode ('production' or 'development') |
import { Component, signal } from '@angular/core';
import { DotCMSPageAsset } from '@dotcms/types';
import { DotCMSLayoutBody } from '@dotcms/angular';
import { DOTCMS_CLIENT_TOKEN } from './app.config';
@Component({
template: `
<dotcms-layout-body [page]="pageAsset()" [components]="components()" mode="development" />
`
})
export class MyPageComponent {
protected readonly components = signal({
Blog: import('./blog.component').then((c) => c.BlogComponent)
});
protected readonly pageAsset = signal<DotCMSPageAsset | null>(null);
private readonly dotCMSClient = inject(DOTCMS_CLIENT_TOKEN);
ngOnInit() {
this.dotCMSClient.page.get({ url: '/my-page' }).then(({ pageAsset }) => {
this.pageAsset.set(pageAsset);
});
}
}
production: Performance-optimized mode that only renders content with explicitly mapped components, leaving unmapped content empty.development: Debug-friendly mode that renders default components for unmapped content types and provides visual indicators and console logs for empty containers and missing mappings.The DotCMSLayoutBody component uses a components input to map content type variable names to Angular components. This allows you to render different components for different content types. Example:
const DYNAMIC_COMPONENTS = {
Blog: import('./blog.component').then((c) => c.BlogComponent),
Product: import('./product.component').then((c) => c.ProductComponent)
};
Blog, Product): Match your content type variable names in dotCMS[!TIP] Always use the exact content type variable name from dotCMS as the key. You can find this in the Content Types section of your dotCMS admin panel.
DotCMSEditableText is a component for inline editing of text fields in dotCMS, supporting plain text, text area, and WYSIWYG fields.
| Input | Type | Required | Description |
|---|---|---|---|
contentlet | T extends DotCMSBasicContentlet | ✅ | The contentlet containing the editable field |
fieldName | keyof T | ✅ | Name of the field to edit, which must be a valid key of the contentlet type T |
mode | 'plain' | 'full' | ❌ | plain (default): Support text editing. Does not show style controls. full: Enables a bubble menu with style options. This mode only works with WYSIWYG fields. |
format | 'text' | 'html' | ❌ | text (default): Renders HTML tags as plain text html: Interprets and renders HTML markup |
import { Component, Input } from '@angular/core';
import { RouterLink } from '@angular/router';
import { DotCMSBasicContentlet } from '@dotcms/types';
import { DotCMSEditableTextComponent } from '@dotcms/angular';
@Component({
selector: 'app-your-component',
imports: [RouterLink, NgOptimizedImage, DotCMSEditableTextComponent],
template: `
<div
class="flex overflow-hidden relative justify-center items-center w-full h-96 bg-gray-200">
<img
class="object-cover w-full"
[src]="'/dA/' + contentlet().inode"
[alt]="contentlet().title" />
<div
class="flex absolute inset-0 flex-col justify-center items-center p-4 text-center text-white">
<h2 class="mb-2 text-6xl font-bold text-shadow">
<dotcms-editable-text fieldName="title" [contentlet]="contentlet()" />
</h2>
<a
class="p-4 text-xl bg-red-400 rounded-sm transition duration-300 hover:bg-red-500"
[routerLink]="contentlet().link">
See more
</a>
</div>
</div>
`
})
export class MyBannerComponent {
@Input() contentlet: DotCMSBasicContentlet;
}
Save workflow action on blur without needing full content dialog.DotCMSBlockEditorRenderer is a component for rendering Block Editor content from dotCMS with support for custom block renderers.
| Input | Type | Required | Description |
|---|---|---|---|
blocks | BlockEditorContent | ✅ | The Block Editor content to render |
customRenderers | CustomRenderer | ❌ | Custom rendering functions for specific block types |
className | string | ❌ | CSS class to apply to the container |
style | CSSProperties | ❌ | Inline styles for the container |
import { DotCMSBasicContentlet } from '@dotcms/types';
import { DotCMSBlockEditorRenderer } from '@dotcms/angular';
const CUSTOM_RENDERERS = {
customBlock: import('./custom-block.component').then((c) => c.CustomBlockComponent),
h1: import('./custom-h1.component').then((c) => c.CustomH1Component)
};
@Component({
selector: 'app-your-component',
imports: [DotCMSShowWhen],
template: `
<dotcms-block-editor-renderer
[blocks]="contentlet.myBlockEditorField"
[customRenderers]="customRenderers()" />
`
})
export class MyBannerComponent {
@Input() contentlet: DotCMSBasicContentlet;
readonly customRenderers = signal(CUSTOM_RENDERERS);
}
DotCMSEditableTextDotCMSBlockEditorRenderer only works with Block Editor fields. For other fields, use DotCMSEditableText.📘 For advanced examples, customization options, and best practices, refer to the DotCMSBlockEditorRenderer README.
DotCMSShowWhen is a directive for conditionally showing content based on the current UVE mode. Useful for mode-based behaviors outside of render logic.
| Input | Type | Required | Description |
|---|---|---|---|
when | UVE_MODE | ✅ | The UVE mode when content should be displayed: UVE_MODE.EDIT: Only visible in edit mode UVE_MODE.PREVIEW: Only visible in preview mode UVE_MODE.PUBLISHED: Only visible in published mode |
import { UVE_MODE } from '@dotcms/types';
import { DotCMSShowWhen } from '@dotcms/angular';
@Component({
selector: 'app-your-component',
imports: [DotCMSShowWhen],
template: `
<div *dotCMSShowWhen="UVE_MODE.EDIT">Only visible in edit mode</div>
`
})
export class YourComponent {}
📚 Learn more about the UVE_MODE enum in the dotCMS UVE Package Documentation.
The DotCMSEditablePageService enables real-time page updates when using the Universal Visual Editor. It provides a single method listen that returns an Observable of page changes.
| Param | Type | Required | Description |
|---|---|---|---|
pageResponse | DotCMSPageResponse | ✅ | The page data object from client.page.get() |
When you use the listen method, the service:
import { Subscription } from 'rxjs';
import { Component, OnDestroy, OnInit, signal, inject } from '@angular/core';
import { getUVEState } from '@dotcms/uve';
import { DotCMSPageAsset } from '@dotcms/types';
import { DotCMSLayoutBody, DotCMSEditablePageService } from '@dotcms/angular';
import { DOTCMS_CLIENT_TOKEN } from './app.config';
@Component({
imports: [DotCMSLayoutBody],
providers: [DotCMSEditablePageService],
template: `
@if (pageAsset()) {
<dotcms-layout-body [page]="pageAsset()" [components]="components()" />
} @else {
<div>Loading...</div>
}
`
})
export class PageComponent implements OnInit, OnDestroy {
private subscription?: Subscription;
private readonly dotCMSClient = inject(DOTCMS_CLIENT_TOKEN);
private readonly editablePageService = inject(DotCMSEditablePageService);
readonly pageAsset = signal<DotCMSPageAsset | null>(null);
ngOnInit() {
this.dotCMSClient.page.get({ url: '/about-us' }).then((pageResponse) => {
// Only subscribe to changes when in the editor
if (getUVEState()) {
this.subscription = this.editablePageService
.listen(pageResponse)
.subscribe(({ pageAsset }) => {
this.pageAsset.set(pageAsset);
});
} else {
const { pageAsset } = pageResponse;
this.pageAsset.set(pageAsset);
}
});
}
ngOnDestroy() {
this.subscription?.unsubscribe();
}
}
DotCMSEditablePageService call to enable UVE.dotcmsUrl matches your instance URL exactlyComponents Not Rendering: Empty spaces where content should appear
components propdevelopment mode for detailed loggingAsset Loading Issues: Images or files not loading
angular.json/dA path is properly configuredBuild Errors: npm install fails
npm cache clean --forcenode_modules and reinstallRuntime Errors: Console errors about missing imports or components not rendering
@dotcms/angularEnable Development Mode
<dotcms-layout-body
[page]="pageAsset()"
[components]="components()"
mode="development"
/>
This will:
Check Browser Console
Network Monitoring
If you're still experiencing problems after trying these solutions:
We offer multiple channels to get help with the dotCMS Angular SDK:
dotcms-angular when posting questions.When reporting issues, please include:
GitHub pull requests are the preferred method to contribute code to dotCMS. We welcome contributions to the DotCMS UVE SDK! If you'd like to contribute, please follow these steps:
git checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature')git push origin feature/amazing-feature)Please ensure your code follows the existing style and includes appropriate tests.
dotCMS comes in multiple editions and as such is dual-licensed. The dotCMS Community Edition is licensed under the GPL 3.0 and is freely available for download, customization, and deployment for use within organizations of all stripes. dotCMS Enterprise Editions (EE) adds several enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see the feature page.
This SDK is part of dotCMS's dual-licensed platform (GPL 3.0 for Community, commercial license for Enterprise).
Learn more at dotcms.com.
FAQs
Official Angular Components library to render a dotCMS page.
The npm package @dotcms/angular receives a total of 106 weekly downloads. As such, @dotcms/angular popularity was classified as not popular.
We found that @dotcms/angular demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Bun 1.2.19 introduces isolated installs for smoother monorepo workflows, along with performance boosts, new tooling, and key compatibility fixes.
Security News
Popular npm packages like eslint-config-prettier were compromised after a phishing attack stole a maintainer’s token, spreading malicious updates.
Security News
/Research
A phishing attack targeted developers using a typosquatted npm domain (npnjs.com) to steal credentials via fake login pages - watch out for similar scams.