# ngx-bootstrap

The best way to quickly integrate Bootstrap 3 or Bootstrap 4 Components with Angular

## Links

- Release Notes
- Slack Community

## Table of contents

1. Getting Started
2. Installation instructions
3. Usage & Demo
4. API
5. Compatibility
6. Troubleshooting
7. Contributing
8. Accessibility

## Getting Started

ngx-bootstrap contains all core (and not only) Bootstrap components powered by Angular. So you don't need to include original JS components, but we are using markup and css provided by Bootstrap.

## Installation instructions

#### Method 1

Install `ngx-bootstrap` from `npm`

    npm install ngx-bootstrap --save

You will need bootstrap styles (Bootstrap 3)

    <!-- index.html -->
    <link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" rel="stylesheet">

Or Bootstrap 4

    <!--- index.html -->
    <link href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css" rel="stylesheet">

To enable bootstrap 4 theme templates in ngx-bootstrap, please read here

    <!-- index.html -->
    <link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" rel="stylesheet">

#### Method 2

Angular CLI `ng add` command will update your Angular project with the necessary ngx-bootstrap dependencies, make changes to package.json, angular.json and will execute initialization code.

    ng add ngx-bootstrap

    ng add ngx-bootstrap  --component componentName

ng add will use your package manager to download dependencies for ngx-bootstrap and invoke an installation script (implemented as a schematic) which will update your project and add additional dependencies (e.g. styles)

List of possible commands for adding appropriate component

            ng add ngx-bootstrap  --component accordion
            ng add ngx-bootstrap  --component alerts
            ng add ngx-bootstrap  --component buttons
            ng add ngx-bootstrap  --component carousel
            ng add ngx-bootstrap  --component collapse
            ng add ngx-bootstrap  --component datepicker
            ng add ngx-bootstrap  --component dropdowns
            ng add ngx-bootstrap  --component modals
            ng add ngx-bootstrap  --component pagination
            ng add ngx-bootstrap  --component popover
            ng add ngx-bootstrap  --component progressbar
            ng add ngx-bootstrap  --component rating
            ng add ngx-bootstrap  --component sortable
            ng add ngx-bootstrap  --component tabs
            ng add ngx-bootstrap  --component timepicker
            ng add ngx-bootstrap  --component tooltip
            ng add ngx-bootstrap  --component typeahead

### Setting up the bootstrap version manually

Sometimes, your project might contain some library that could interfere with the bootstrap framework, or you might have a customized version of bootstrap. The consequence is that the process of determining bootstrap version might be failed, which can break the UI. In that case, we can still set the bootstrap version manually in the bootstrapping component (i.e. `AppComponent`):

    import {{'{'}} setTheme {{'}'}} from 'ngx-bootstrap/utils';

    @Component({{'{'}}…{{'}'}})
    export class AppComponent {{'{'}}
      constructor() {{'{'}}
        setTheme('bs3'); // or 'bs4'
        …
      {{'}'}}
    {{'}'}}

### How to use it with:

- `angular-cli` please refer to getting-started-with-ng-cli
- `angular-seed` please refer to getting-started-with-angular-seed
- `system.js` (and angular quickstart) please checkout sample repository
- `plnkr` sample available here
- `AoT using ngc and rollup` please refer to ngx-bootstrap-with-aot
- `Bootstrap 4 and angular-cli` please refer to using-with-bootstrap-4-and-angular-cli

## Usage & Demo

Main source of API documentation and usage examples available here: https://valor-software.com/ngx-bootstrap/

Additionally you can find demos and docs deployed from latest code with angular v4 and angular v5

Server side rendered version of this documentation available here

## API

Check demo page for API reference

## Compatibility

The only two dependencies are Angular and Bootstrap CSS.

Here is the versions compatibility list:

ngx-bootstrap | Angular | Bootstrap CSS
--- | --- | ---
5.x.x | 7.x.x - 8.x.x | 3.x.x or 4.x.x
4.x.x | 6.x.x - 7.x.x | 3.x.x or 4.x.x
3.x.x | 6.x.x - 7.x.x | 3.x.x or 4.x.x
2.x.x | 2.x.x - 4.x.x | 3.x.x or 4.x.x
1.x.x | 2.x.x | 3.x.x or 4.x.x

## Troubleshooting

So you are in trouble, where to get help:

- you can search and ask for help at StackOverflow
- you can join slack and ask a question
- if none of this helped please search and only then open new issue

## Contribution

Are very welcome! And remember, contribution is not only PRs and code, but any help with docs or helping other developers to solve issues are very appreciated! Thanks in advance!

If you also would like to show support or simply give back to Open Source community, please consider becoming a backer sponsor of ngx-bootstrap on OpenCollective.

### If you need more modules check here

Please read central `ngx` modules readme for details, plans and approach

### Credits

Crossbrowser testing sponsored by Saucelabs

End-to-end testing sponsored by Cypress

## Accessibility

### Overview and Limitations

The overall accessibility of any project built with ngx-bootstrap depends in large part on the author’s markup, additional styling, and scripting they’ve included. However, provided that these have been implemented correctly, it should be perfectly possible to create websites and applications that fulfill WCAG 2.0 (A/AA/AAA), Section 508 and similar accessibility standards and requirements.

### Interactive components

Interactive components—such as modal dialogs, dropdown menus and custom tooltips—are designed to work for touch, mouse and keyboard users. Through the use of relevant WAI-ARIA roles and attributes, these components should also be understandable and operable using assistive technologies (such as screen readers).

Authors need to include ARIA roles and attributes to more accurately convey the precise nature of their component.

### Color contrast

Most colors that currently make up Bootstrap’s default palette—used throughout the framework for things such as button variations, alert variations, form validation indicators—lead to insufficient color contrast (below the recommended WCAG 2.0 color contrast ratio of 4.5:1) when used against a light background. Authors will need to manually modify/extend these default colors to ensure adequate color contrast ratios.

### Additional resources

- Web Content Accessibility Guidelines (WCAG) 2.0
- The A11Y Project
- MDN accessibility documentation
- Tenon.io Accessibility Checker
- Colour Contrast Analyser (CCA)
- “HTML Codesniffer” bookmarklet for identifying accessibility issues