0
# NGX-Bootstrap
1

2
NGX-Bootstrap is a comprehensive Angular component library that provides Bootstrap 5 and Bootstrap 4 components for Angular applications. It offers a complete suite of UI components including modals, datepickers, dropdowns, tooltips, and more, all designed to integrate seamlessly with Angular's change detection and data binding systems.
3

4
## Package Information
5

6
- **Package Name**: ngx-bootstrap
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install ngx-bootstrap`
10

11
## Core Imports
12

13
NGX-Bootstrap uses modular imports, allowing you to import only the components you need:
14

15
```typescript
16
import { AccordionModule } from 'ngx-bootstrap/accordion';
17
import { BsModalService, BsModalRef } from 'ngx-bootstrap/modal';
18
import { BsDatepickerModule } from 'ngx-bootstrap/datepicker';
19
import { TooltipModule } from 'ngx-bootstrap/tooltip';
20
```
21

22
For services and utilities:
23

24
```typescript
25
import { BsModalService } from 'ngx-bootstrap/modal';
26
import { positionElements } from 'ngx-bootstrap/positioning';
27
import { parseDate, formatDate } from 'ngx-bootstrap/chronos';
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { Component } from '@angular/core';
34
import { BsModalService, BsModalRef } from 'ngx-bootstrap/modal';
35
import { AccordionModule } from 'ngx-bootstrap/accordion';
36

37
@Component({
38
  selector: 'app-example',
39
  template: `
40
    <!-- Accordion -->
41
    <accordion [closeOthers]="true">
42
      <accordion-panel heading="Panel 1" [isOpen]="true">
43
        Content for panel 1
44
      </accordion-panel>
45
      <accordion-panel heading="Panel 2">
46
        Content for panel 2
47
      </accordion-panel>
48
    </accordion>
49

50
    <!-- Modal trigger -->
51
    <button class="btn btn-primary" (click)="openModal()">
52
      Open Modal
53
    </button>
54
  `,
55
  imports: [AccordionModule]
56
})
57
export class ExampleComponent {
58
  modalRef?: BsModalRef;
59

60
  constructor(private modalService: BsModalService) {}
61

62
  openModal() {
63
    this.modalRef = this.modalService.show(MyModalComponent);
64
  }
65
}
66
```
67

68
## Architecture
69

70
NGX-Bootstrap is built around several key architectural patterns:
71

72
- **Modular Design**: Each Bootstrap component is packaged as a separate Angular module for optimal tree-shaking
73
- **Configuration Services**: Global configuration through injectable services (e.g., `TooltipConfig`, `AccordionConfig`)
74
- **Angular Integration**: Full support for Angular's change detection, data binding, and dependency injection
75
- **Type Safety**: Complete TypeScript definitions for all components, services, and interfaces
76
- **Bootstrap Compatibility**: Supports both Bootstrap 4 and Bootstrap 5 styling
77
- **Positioning Engine**: Advanced positioning calculations for overlays and popups
78
- **i18n Support**: Extensive localization through the chronos date/time library
79

80
## Capabilities
81

82
### Interactive Components
83

84
Core interactive Bootstrap components including accordions, modals, dropdowns, and tabs.
85

86
```typescript { .api }
87
// Accordion API
88
interface AccordionComponent {
89
  isAnimated: boolean;
90
  closeOthers: boolean;
91
}
92

93
interface AccordionPanelComponent {
94
  heading: string;
95
  isOpen: boolean;
96
  isDisabled: boolean;
97
  isOpenChange: EventEmitter<boolean>;
98
}
99

100
// Modal API
101
interface BsModalService {
102
  show<T>(component: ComponentType<T>, config?: Partial<ModalOptions>): BsModalRef<T>;
103
  hide(id?: number): void;
104
  getModalsCount(): number;
105
  onShow: EventEmitter<BsModalRef>;
106
  onShown: EventEmitter<BsModalRef>;
107
  onHide: EventEmitter<BsModalRef>;
108
  onHidden: EventEmitter<BsModalRef>;
109
}
110

111
interface BsModalRef<T = any> {
112
  content?: T;
113
  hide(): void;
114
  setClass(newClass: string): void;
115
}
116
```
117

118
[Interactive Components](./interactive-components.md)
119

120
### Form Controls
121

122
Advanced form controls including datepickers, timepickers, typeahead, and rating components.
123

124
```typescript { .api }
125
// Datepicker API
126
interface BsDatepickerDirective {
127
  bsConfig: Partial<BsDatepickerConfig>;
128
  bsValue: Date | Date[];
129
  minDate: Date;
130
  maxDate: Date;
131
  dateCustomClasses: DatepickerDateCustomClasses[];
132
  daysDisabled: number[];
133
  datesDisabled: Date[];
134
  placement: 'top' | 'bottom' | 'left' | 'right';
135
  triggers: string;
136
  container: string;
137
  isDisabled: boolean;
138
  onShown: EventEmitter<BsDatepickerDirective>;
139
  onHidden: EventEmitter<BsDatepickerDirective>;
140
  bsValueChange: EventEmitter<Date>;
141
}
142

143
// Timepicker API
144
interface TimepickerComponent {
145
  hourStep: number;
146
  minuteStep: number;
147
  secondsStep: number;
148
  readonlyInput: boolean;
149
  disabled: boolean;
150
  mousewheel: boolean;
151
  arrowkeys: boolean;
152
  showSpinners: boolean;
153
  showSeconds: boolean;
154
  showMinutes: boolean;
155
  min: Date;
156
  max: Date;
157
}
158
```
159

160
[Form Controls](./form-controls.md)
161

162
### Navigation & Layout
163

164
Navigation components including pagination, tabs, and carousel for content organization.
165

166
```typescript { .api }
167
// Pagination API
168
interface PaginationComponent {
169
  align: boolean;
170
  boundaryLinks: boolean;
171
  directionLinks: boolean;
172
  disabled: boolean;
173
  firstText: string;
174
  lastText: string;
175
  maxSize: number;
176
  nextText: string;
177
  previousText: string;
178
  rotate: boolean;
179
  totalItems: number;
180
  itemsPerPage: number;
181
  numPages: EventEmitter<number>;
182
  pageChanged: EventEmitter<PageChangedEvent>;
183
}
184

185
// Carousel API
186
interface CarouselComponent {
187
  noWrap: boolean;
188
  noPause: boolean;
189
  showIndicators: boolean;
190
  interval: number;
191
  pauseOnFocus: boolean;
192
  indicatorsByChunk: boolean;
193
  itemsPerSlide: number;
194
  singleSlideOffset: boolean;
195
  activeSlideChange: EventEmitter<number>;
196
  slideRangeChange: EventEmitter<number[]>;
197
}
198
```
199

200
[Navigation & Layout](./navigation-layout.md)
201

202
### Overlays & Popovers
203

204
Overlay components including tooltips, popovers, and dropdowns for contextual information.
205

206
```typescript { .api }
207
// Tooltip API
208
interface TooltipDirective {
209
  tooltip: string | TemplateRef<any>;
210
  tooltipHtml: string | TemplateRef<any>;
211
  placement: string;
212
  triggers: string;
213
  container: string;
214
  isDisabled: boolean;
215
  delay: number;
216
  customClass: string;
217
  tooltipContext: any;
218
  tooltipPopupDelay: number;
219
  adaptivePosition: boolean;
220
  onShown: EventEmitter<TooltipDirective>;
221
  onHidden: EventEmitter<TooltipDirective>;
222
}
223

224
// Dropdown API
225
interface BsDropdownDirective {
226
  placement: 'top' | 'bottom' | 'left' | 'right';
227
  triggers: string;
228
  container: string;
229
  dropup: boolean;
230
  autoClose: boolean | 'outside' | 'inside';
231
  insideClick: boolean;
232
  isDisabled: boolean;
233
  onShown: EventEmitter<BsDropdownDirective>;
234
  onHidden: EventEmitter<BsDropdownDirective>;
235
  isOpenChange: EventEmitter<boolean>;
236
}
237
```
238

239
[Overlays & Popovers](./overlays-popovers.md)
240

241
### Utilities & Infrastructure
242

243
Core utilities for positioning, theming, date manipulation, and component loading.
244

245
```typescript { .api }
246
// Positioning utilities
247
function positionElements(
248
  hostElement: HTMLElement,
249
  targetElement: HTMLElement,
250
  placement: string,
251
  appendToBody?: boolean
252
): { top: number; left: number };
253

254
// Date utilities (Chronos)
255
function parseDate(input: string, format?: string, locale?: string): Date;
256
function formatDate(date: Date, format: string, locale?: string): string;
257
function add(date: Date, amount: number, unit: TimeUnit): Date;
258
function subtract(date: Date, amount: number, unit: TimeUnit): Date;
259

260
// Theme utilities
261
function setTheme(theme: AvailableBsVersions): void;
262
function getBsVer(): IBsVersion;
263

264
// Component loading
265
interface ComponentLoader<T> {
266
  provide(component: ComponentType<T>): ComponentLoader<T>;
267
  to(container?: string): ComponentLoader<T>;
268
  position(opts?: PositioningOptions): ComponentLoader<T>;
269
  show(opts?: any): ComponentRef<T>;
270
  hide(): ComponentLoader<T>;
271
  dispose(): void;
272
}
273
```
274

275
[Utilities & Infrastructure](./utilities-infrastructure.md)
276

277
## Common Types
278

279
```typescript { .api }
280
// Configuration interfaces
281
interface BsComponentConfig {
282
  placement?: string;
283
  triggers?: string;
284
  container?: string;
285
}
286

287
// Event types
288
interface PageChangedEvent {
289
  page: number;
290
  itemsPerPage: number;
291
}
292

293
// Date types
294
type TimeUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond';
295

296
interface DatepickerDateCustomClasses {
297
  date: Date;
298
  classes: string[];
299
}
300

301
// Modal types
302
interface ModalOptions {
303
  backdrop?: boolean | 'static';
304
  keyboard?: boolean;
305
  focus?: boolean;
306
  show?: boolean;
307
  ignoreBackdropClick?: boolean;
308
  class?: string;
309
  containerClass?: string;
310
  animated?: boolean;
311
  data?: any;
312
  initialState?: any;
313
  providers?: StaticProvider[];
314
  ariaDescribedby?: string;
315
  ariaLabelledBy?: string;
316
  ariaLabel?: string;
317
}
318

319
// Bootstrap version types
320
interface IBsVersion {
321
  isBs3: boolean;
322
  isBs4: boolean;
323
  isBs5: boolean;
324
}
325

326
type AvailableBsVersions = 'bs3' | 'bs4' | 'bs5';
327
```