ng-bootstrap: Bootstrap 5 widgets built for Angular, not wrapped around it

The problem ng-bootstrap solves for Angular teams

Bootstrap 5 ships CSS plus a small amount of JavaScript for interactive behaviour: modals, dropdowns, tooltips, accordions, carousels. That JavaScript manipulates the DOM directly and assumes it owns the elements it touches. Angular assumes the opposite. It renders templates from component state and expects to be the only thing mutating the DOM. Drop Bootstrap's JavaScript into an Angular app and you get two systems fighting over the same nodes, plus a jQuery-shaped API that does not participate in change detection.

ng-bootstrap's answer is to throw away Bootstrap's JavaScript entirely. The README describes the project as "Angular widgets built from the ground up using only Bootstrap 5 CSS with APIs designed for the Angular ecosystem." So the CSS classes, the markup structure and the visual result come from Bootstrap, while the behaviour comes from Angular components and directives. A datepicker becomes a component with inputs and outputs. A modal becomes a service you call. A tooltip becomes a directive you attach.

The audience is narrow and specific: teams that have already committed to Bootstrap as their visual layer and to Angular as their framework, and who do not want to hand-write the interaction layer for every widget. If you are not using Bootstrap's CSS, most of the value disappears, because the components assume those class names exist.

How the components are wired: CSS from Bootstrap, behaviour from Angular

The dependency list is short by design. Angular and Popper are listed as peer dependencies. Bootstrap is deliberately not a peer dependency, and the README explains why: Bootstrap does not release its CSS separately, so the project cannot depend on the CSS package alone. Instead the README publishes a table mapping each ng-bootstrap major to the exact Bootstrap CSS version it is tested against. Version 21.x.x maps to Angular ^22.0.0, Bootstrap CSS 5.3.8 and Popper ^2.11.8.

Popper is what makes the positioning work. Dropdowns, tooltips and popovers need to be placed relative to a trigger element and flipped when they would overflow the viewport, and Popper is the library that computes those coordinates. That is why it appears as a peer dependency rather than being bundled.

The repository layout reflects the split between library and demonstration. The src/ directory holds the library itself, while demo/, e2e-app/, ssr-app/ and test-app/ are separate Angular applications used for documentation, end-to-end tests, server-side rendering checks and integration testing. The e2e-app is driven by Playwright, as the playwright.config.ts file under demo/ and the ngb:e2e script in package.json indicate. The build script runs a production Angular build and then a post-processing step, misc/unexposeUtils.mjs, which strips internal utilities from the published output. That is a deliberate signal: the public API surface is smaller than what exists inside the source tree.

Installing ng-bootstrap and rendering a first widget

The README recommends Angular CLI and provides a schematic, which is the shortest path. Run this in the root of an Angular CLI project:

ng add @ng-bootstrap/ng-bootstrap

The schematic installs the library for the default application declared in angular.json. According to the README, if the workspace contains multiple projects you can target one explicitly:

ng add @ng-bootstrap/ng-bootstrap --project myProject

If you would rather not use schematics, the README points to the manual installation instructions on the project site at ng-bootstrap.github.io under getting-started, and does not reproduce those steps in the README itself.

Once installed, a widget is used as an ordinary Angular component. The demo site at ng-bootstrap.github.io lists every component with a live example, and each example links to a StackBlitz fork, which is also the format the maintainers ask for in bug reports. The accordion is a representative entry point because it needs no Popper and no service injection: you place an ngb-accordion element in a template and nest ngb-panel children inside it, with the panel body projected through a template. What you should see is a Bootstrap-styled accordion whose expand and collapse behaviour is driven by Angular bindings rather than by any script you wrote. For a modal the pattern is different: you inject a service, call open with a component type, and subscribe to the returned result. Check the component page for the exact inputs before copying an example, since the demo is the authoritative source for each widget's API.

Where ng-bootstrap is the wrong choice

The version table is the sharpest constraint in the whole project. Each ng-bootstrap major is bound to one Angular major: 21.x.x to Angular ^22.0.0, 20.x.x to ^21.0.0, 19.x.x to ^20.0.0, and so on down the table. There is no line of ng-bootstrap that supports two Angular majors at once. If your application is on Angular 19 and you want the newest widgets, you do not get them; you take the 18.x.x line, which is tied to Bootstrap CSS 5.3.3 rather than 5.3.8. Upgrading Angular therefore forces an ng-bootstrap upgrade in the same step, and vice versa. Teams that deliberately lag one Angular major behind will lag here too.

The second limitation is scope. The topics list covers accordion, alert, buttons, carousel, collapse, datepicker, dropdown, modal, pagination, popover, progress bar, rating, tabs, timepicker, tooltip and typeahead. There is no data table, no tree view, no virtual scroll list, no chart. If your application needs a grid with sorting, filtering and column resizing, ng-bootstrap will not provide it, and you will be pairing it with something else. That is a reasonable outcome, but it means ng-bootstrap is rarely the only UI dependency in a project.

The third issue is the support policy. The README is explicit that general support questions should not be filed as issues and that such issues "will be systematically closing" and be redirected to StackOverflow under the ng-bootstrap tag. For bug reports, the maintainers insist on a minimal reproduction on StackBlitz and state that issues without one will be marked non-actionable and closed if the reporter does not respond. That is a defensible policy for a volunteer-maintained project, but it means the GitHub issue tracker is not a place to ask how something works. It is a place to report a confirmed defect with a reproduction attached.

ng-bootstrap compared with ngx-bootstrap and Angular Material

The two comparisons people search for most are ngx-bootstrap and Angular Material, and they differ from ng-bootstrap in ways that matter more than feature lists.

Angular Material is a complete design system. It brings its own components, its own typography, its own theming system and its own visual identity, and it does not depend on Bootstrap CSS at all. If you adopt it, you are choosing Material Design as the look of your application. ng-bootstrap makes the opposite bet: it contributes no styling of its own and inherits whatever Bootstrap 5 CSS you have already loaded. That means a Bootstrap 5 theme, including third-party themes, applies to ng-bootstrap components for free, and it means ng-bootstrap components will never look out of place next to hand-written Bootstrap markup. The trade-off is that ng-bootstrap's visual quality is exactly as good as your Bootstrap theme, and no better.

ngx-bootstrap is the closer comparison, since both projects provide Bootstrap widgets for Angular. The difference is in the version contract. ng-bootstrap publishes an explicit table tying each release to a specific Angular major and a specific Bootstrap CSS version, and it is on Bootstrap 5 CSS from version 12.x.x onward. If you need Bootstrap 4 markup, the ng-bootstrap table shows that support ended at 11.x.x, which was tied to Bootstrap CSS 4.6.0. Checking whether a given ngx-bootstrap release targets Bootstrap 4 or 5, and which Angular majors it accepts, is the practical way to choose between them for a legacy codebase. For a new project on current Angular, ng-bootstrap's table makes the compatibility question answerable in one glance.

Maintenance cadence, licensing and what an upgrade costs

The repository is not archived, and the most recent push recorded is 2026-06-22, the same day version 21.0.0 was published. Version 21.0.0-rc.0 landed a week earlier on 2026-06-15, and version 20.0.0 was published on 2025-12-12. That pattern, a release candidate followed by a final release, suggests the project cuts a major roughly twice a year in step with Angular's own release cadence. The package.json sets engines.node to >=24.11.1 and declares [email protected] as the package manager, with the npm field carrying the message "Please use Yarn to install dependencies". That constraint applies to building the library from source, not to consuming it from npm.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the whole of what the repository states; it is not legal advice, and if your organisation has a policy on third-party licences, the LICENSE file at the repository root is the document to route through it.

The upgrade cost is the thing to plan for. Because each major pins one Angular major, an Angular upgrade is an ng-bootstrap major upgrade, and the README's table tells you which Bootstrap CSS version you land on. Moving from ng-bootstrap 20.x.x to 21.x.x keeps Bootstrap CSS at 5.3.8 while moving Angular from ^21.0.0 to ^22.0.0, so the CSS side is stable across that particular step. Earlier steps in the table are not always so quiet: 19.x.x to 20.x.x moved Bootstrap CSS from 5.3.6 to 5.3.8 as well as Angular from ^20.0.0 to ^21.0.0. Check both columns before scheduling the work.

Editorial conclusion

Adopt ng-bootstrap if you are on a supported Angular release, already ship Bootstrap 5 CSS, and want widgets whose APIs feel native to Angular rather than a jQuery wrapper. Skip it if you are pinned to an older Angular major, if you want a component library with its own visual language, or if you need widgets the project does not ship, such as a data table. Before installing, read the version table in the README and confirm which Bootstrap CSS and Popper versions your Angular major maps to, because that mapping is the one thing the schematic cannot decide for you.

Frequently asked questions

Official sources

1. License: MIT
2. ng-bootstrap/ng-bootstrap on GitHub
3. Project website
4. README
5. Releases