DOCSEARCHbyAlgolia
Submit Docs

ng-bootstrap Documentation

repository·master·Indexed 27 days ago

https://github.com/ng-bootstrap/ng-bootstrap

Angular-powered Bootstrap 5 widgets built from the ground up using only Bootstrap CSS. The library provides a set of APIs specifically designed for the Angular ecosystem, including components like NgbAccordion, NgbModal, and NgbTooltip. It can be installed via Angular CLI using `ng add @ng-bootstrap/ng-bootstrap` and requires Angular, Bootstrap 5 CSS, and Popper.

Tokens
2.2K
Snippets
7
Records
13
Agent score
94%

What's inside ng-bootstrap

  1. Format and check code style

    master

    The project uses Prettier for code formatting. Formatting is enforced during CI and via Husky pre-commit hooks. You can manually check or apply formatting using these commands:

    • yarn check-format: Checks if the code follows the formatting rules (used in CI).
    • yarn format: Forces formatting on the code.
    yarn check-format
yarn format

  2. Debug and run e2e tests with Playwright

    master

    For faster development and debugging of end-to-end tests, use these commands:

    • Run the e2e-app server to speed up test re-runs: yarn e2e-app:serve
    • Launch Playwright UI mode to focus on specific browser/test combinations: yarn playwright test -c e2e-app --ui

    If you use VSCode, the Playwright extension is recommended for setting breakpoints and inspecting variables.

    yarn e2e-app:serve
yarn playwright test -c e2e-app --ui

  3. Follow commit message conventions

    master

    ng-bootstrap uses CommitLint to enforce a specific commit message format. Messages must include a type, a scope (the name of the widget, e.g., alert, accordion, datepicker), and a description.

    Valid Types:

    • feat(<scope>): A new feature
    • fix(<scope>): A bug fix
    • test(<scope>): An update to unit or e2e tests
    • docs(<scope>): Documentation update
    • refactor(<scope>): Internal refactoring without public functionality changes
    • demo(<scope>): An update to a specific widget's demo
    • demo: Any change to the demo site
    • build: Changes to utility scripts, configurations, or dependencies
    • ci: Changes to CI configuration
    • revert: Reverting an older commit

    Example Format:

    fix(tooltip): allow 'null' and 'undefined' as values for tooltip

The documentation says that falsy values are accepted,
but in strict mode, only the empty string could actually be passed.

Fixes #3845

  4. Set up the ng-bootstrap development environment

    master

    To build and test ng-bootstrap locally, ensure you have the following prerequisite software installed:

    • Git
    • Node.js (LTS version >=14.15.0)
    • Yarn (version >=1.15.2)

    To get the sources, fork the repository on GitHub, clone your fork, and add the original repository as an upstream remote:

    # Clone your fork
git clone git@github.com:<github username>/ng-bootstrap.git ng-bootstrap

# Navigate to the directory
cd ng-bootstrap

# Add the upstream remote
git remote add upstream https://github.com/ng-bootstrap/ng-bootstrap.git

    After cloning, install the project dependencies using Yarn:

    yarn
    git clone git@github.com:<github username>/ng-bootstrap.git ng-bootstrap
cd ng-bootstrap
git remote add upstream https://github.com/ng-bootstrap/ng-bootstrap.git
yarn

  5. Run ng-bootstrap development commands

    master

    The following commands are available via Yarn to manage the library and demo site:

    • yarn demo: Serves the demo site locally at http://localhost:4200/. Use --prod for production mode or --aot for AOT compilation.
    • yarn build: Builds both the library (in Angular Package format in dist/) and the demo site (in demo/dist/) in production mode.
    • yarn tdd: Runs unit tests for the library in watch mode.
    • yarn test: Lints the source code and runs all unit tests with coverage.
    • yarn e2e: Runs all end-to-end tests in production mode using Playwright.
    • yarn ssr: Builds, runs, and performs e2e tests on a simple server-side rendered application.
    • yarn ci: Runs the same suite of actions as the CI server.
    yarn demo
yarn build
yarn tdd
yarn test
yarn e2e
yarn ssr
yarn ci

  6. Install ng-bootstrap using Angular CLI

    master

    The recommended way to add ng-bootstrap to an existing Angular CLI project is by using the provided schematics. This will automatically install the library and configure your project.

    To install for the default application specified in your angular.json, run:

    ng add @ng-bootstrap/ng-bootstrap

    If your workspace contains multiple projects and you want to target a specific application, use the --project option:

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

    If you prefer not to use schematics, you can follow the manual installation instructions on the official website.

  7. Add ng-bootstrap to an Angular project using ng add

    master

    You can automatically install and configure ng-bootstrap in your Angular project by using the ng add command. This schematic performs the following actions:

    1. Installs bootstrap and @popperjs/core dependencies.
    2. Installs @angular/localize if it is not already present in your project.
    3. Runs the ng-add-setup-project schematic to complete the configuration.
    4. Triggers a package manager installation (e.g., npm install).
    ng add @ng-bootstrap/ng-bootstrap

  8. Report a bug in ng-bootstrap

    master

    To ensure bugs are fixed quickly, please follow these requirements when opening a GitHub issue:

    1. Fill out the GitHub issue template: Provide a clear description and include the specific versions of Angular, ng-bootstrap, and TypeScript you are using.
    2. Provide a minimal reproduction scenario: Use StackBlitz to create a minimal, failing use-case. You can fork a reproduction from the ng-bootstrap demo page.

    Note: Issues without a minimal reproduction scenario may be marked as non-actionable and closed.

  9. Check ng-bootstrap version compatibility

    master

    ng-bootstrap requires Angular, Bootstrap 5 CSS, and Popper. Ensure your versions are compatible according to the following compatibility matrix.

    Note that for versions 12.x.x and above, Popper is a required peer dependency.

    | ng-bootstrap | Angular | Bootstrap CSS | Popper  |
| ------------ | ------- | ------------- | ------- |
| 1.x.x        | ^5.0.2  | 4.0.0         |         |
| 2.x.x        | ^6.0.0  | 4.0.0         |         |
| 3.x.x        | ^6.1.0  | 4.0.0         |         |
| 4.x.x        | ^7.0.0  | 4.0.0         |         |
| 5.x.x        | ^8.0.0  | 4.3.1         |         |
| 6.x.x        | ^9.0.0  | 4.4.1         |         |
| 7.x.x, 8.x.x | ^10.0.0 | 4.5.0         |         |
| 9.x.x        | ^11.0.0 | 4.5.0         |         |
| 10.x.x       | ^12.0.0 | 4.5.0         |         |
| 11.x.x       | ^13.0.0 | 4.6.0         |         |
| 12.x.x       | ^13.0.0 | 5.0.0         | ^2.10.2 |
| 13.x.x       | ^14.1.0 | 5.2.0         | ^2.10.2 |
| 14.x.x       | ^15.0.0 | 5.2.3         | ^2.11.6 |
| 15.x.x       | ^16.0.0 | 5.2.3         | ^2.11.6 |
| 16.x.x       | ^17.0.0 | 5.3.2         | ^2.11.8 |
| 17.x.x       | ^18.0.0 | 5.3.2         | ^2.11.8 |
| 18.x.x       | ^19.0.0 | 5.3.3         | ^2.11.8 |
| 19.x.x       | ^20.0.0 | 5.3.6         | ^2.11.8 |
| 20.x.x       | ^21.0.0 | 5.3.8         | ^2.11.8 |
| 21.x.x       | ^22.0.0 | 5.3.8         | ^2.11.8 |

  10. Import individual ng-bootstrap modules

    master

    To keep your application bundle size small, it is recommended to import only the specific ng-bootstrap modules you need rather than the entire NgbModule. Available modules include:

    • NgbAccordionModule
    • NgbAlertModule
    • NgbCarouselModule
    • NgbCollapseModule
    • NgbDatepickerModule
    • NgbDropdownModule
    • NgbModalModule
    • NgbNavModule
    • NgbOffcanvasModule
    • NgbPaginationModule
    • NgbPopoverModule
    • NgbProgressbarModule
    • NgbRatingModule
    • NgbScrollSpyModule
    • NgbTimepickerModule
    • NgbToastModule
    • NgbTooltipModule
    • NgbTypeaheadModule

  11. Import all ng-bootstrap modules using NgbModule

    master
    If you want to use all available ng-bootstrap components and directives in your Angular application, you can import the NgbModule. This module acts as a single entry point that imports and exports all individual ng-bootstrap modules.