0
# @ng-bootstrap/ng-bootstrap
1

2
@ng-bootstrap/ng-bootstrap is a comprehensive Angular UI component library that provides native Angular implementations of Bootstrap 5 components. It offers 18 feature-rich modules with 150+ components, directives, and services, specifically designed for Angular applications with full TypeScript support, reactive forms integration, accessibility features, and Angular-specific optimizations.
3

4
## Package Information
5

6
- **Package Name**: @ng-bootstrap/ng-bootstrap
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @ng-bootstrap/ng-bootstrap`
10
- **Dependencies**: Angular 20.0.0+, Bootstrap 5.3.6 CSS (peer dependencies)
11

12
## Core Imports
13

14
```typescript
15
import { NgbModule } from '@ng-bootstrap/ng-bootstrap';
16
```
17

18
For individual modules:
19

20
```typescript
21
import { NgbAccordionModule } from '@ng-bootstrap/ng-bootstrap';
22
import { NgbModalModule, NgbModal } from '@ng-bootstrap/ng-bootstrap';
23
import { NgbDatepickerModule, NgbDate } from '@ng-bootstrap/ng-bootstrap';
24
```
25

26
## Basic Usage
27

28
```typescript
29
import { Component } from '@angular/core';
30
import { NgbModal, NgbModalRef } from '@ng-bootstrap/ng-bootstrap';
31

32
@Component({
33
  selector: 'app-example',
34
  template: `
35
    <button class="btn btn-primary" (click)="openModal()">Open Modal</button>
36
    
37
    <ngb-accordion>
38
      <ngb-accordion-item id="item-1">
39
        <ngb-accordion-header>
40
          <button ngbAccordionButton>First Item</button>
41
        </ngb-accordion-header>
42
        <ngb-accordion-body>
43
          <p>Content for first accordion item</p>
44
        </ngb-accordion-body>
45
      </ngb-accordion-item>
46
    </ngb-accordion>
47
  `
48
})
49
export class ExampleComponent {
50
  constructor(private modalService: NgbModal) {}
51
  
52
  openModal() {
53
    this.modalService.open('Modal content');
54
  }
55
}
56
```
57

58
## Architecture
59

60
@ng-bootstrap/ng-bootstrap is built around several key architectural patterns:
61

62
- **Module System**: Each UI component is organized into its own Angular module (e.g., `NgbAccordionModule`, `NgbModalModule`)
63
- **Configuration Services**: Global configuration through `NgbConfig` and component-specific configs (e.g., `NgbAccordionConfig`)
64
- **Service-Based Components**: Complex components like modals and offcanvas use services for programmatic control
65
- **Template-Driven Components**: Most components use Angular templates with structural directives
66
- **Type Safety**: Full TypeScript support with strongly typed interfaces and generics
67
- **Accessibility First**: Built-in ARIA attributes, keyboard navigation, and screen reader support
68

69
## Global Configuration
70

71
### NgbConfig Service
72

73
Controls global settings across all components.
74

75
```typescript { .api }
76
class NgbConfig {
77
  animation: boolean; // Global animation toggle (default: true)
78
}
79
```
80

81
### NgbModule
82

83
Main module that imports all component modules for convenience.
84

85
```typescript { .api }
86
@NgModule({ imports: NGB_MODULES, exports: NGB_MODULES })
87
class NgbModule {}
88
```
89

90
## Capabilities
91

92
### Accordion Components
93

94
Collapsible content panels with smooth animations and keyboard navigation.
95

96
```typescript { .api }
97
@Directive({
98
  selector: '[ngbAccordion]',
99
  exportAs: 'ngbAccordion'
100
})
101
class NgbAccordionDirective {
102
  @Input() animation: boolean;
103
  @Input() closeOthers: boolean;
104
  @Input() destroyOnHide: boolean;
105
  @Output() show: EventEmitter<string>;
106
  @Output() shown: EventEmitter<string>;
107
  @Output() hide: EventEmitter<string>;
108
  @Output() hidden: EventEmitter<string>;
109
  
110
  toggle(itemId: string): void;
111
  expand(itemId: string): void;
112
  expandAll(): void;
113
  collapse(itemId: string): void;
114
  collapseAll(): void;
115
  isExpanded(itemId: string): boolean;
116
}
117
```
118

119
[Accordion Components](./accordion.md)
120

121
### Alert Components
122

123
Contextual feedback messages for user actions.
124

125
```typescript { .api }
126
@Component({
127
  selector: 'ngb-alert',
128
  exportAs: 'ngbAlert'
129
})
130
class NgbAlert {
131
  @Input() animation: boolean;
132
  @Input() dismissible: boolean;
133
  @Input() type: string;
134
  @Output() close: EventEmitter<void>;
135
}
136
```
137

138
[Alert Components](./alert.md)
139

140
### Carousel Components
141

142
Interactive slideshow component for cycling through content.
143

144
```typescript { .api }
145
@Component({
146
  selector: 'ngb-carousel',
147
  exportAs: 'ngbCarousel'
148
})
149
class NgbCarousel {
150
  @Input() animation: boolean;
151
  @Input() interval: number;
152
  @Input() pauseOnHover: boolean;
153
  @Input() wrap: boolean;
154
  @Output() slide: EventEmitter<NgbSlideEvent>;
155
  
156
  select(slideId: string): void;
157
  prev(): void;
158
  next(): void;
159
  pause(): void;
160
  cycle(): void;
161
}
162

163
interface NgbSlideEvent {
164
  prev: string;
165
  current: string;
166
  direction: NgbSlideEventDirection;
167
  source: NgbSlideEventSource;
168
}
169
```
170

171
[Carousel Components](./carousel.md)
172

173
### Datepicker Components
174

175
Comprehensive date selection with multiple calendar systems and internationalization.
176

177
```typescript { .api }
178
@Component({
179
  selector: 'ngb-datepicker',
180
  exportAs: 'ngbDatepicker'
181
})
182
class NgbDatepicker {
183
  @Input() dayTemplate: TemplateRef<DayTemplateContext>;
184
  @Input() displayMonths: number;
185
  @Input() firstDayOfWeek: number;
186
  @Input() markDisabled: (date: NgbDate) => boolean;
187
  @Input() maxDate: NgbDate;
188
  @Input() minDate: NgbDate;
189
  @Input() navigation: 'select' | 'arrows' | 'none';
190
  @Input() outsideDays: 'visible' | 'collapsed' | 'hidden';
191
  @Input() showWeekNumbers: boolean;
192
  @Input() startDate: NgbDate;
193
  @Output() navigate: EventEmitter<NgbDatepickerNavigateEvent>;
194
  @Output() select: EventEmitter<NgbDate>;
195
  
196
  navigateTo(date?: NgbDate): void;
197
}
198

199
class NgbDate {
200
  readonly year: number;
201
  readonly month: number;
202
  readonly day: number;
203
  
204
  constructor(year: number, month: number, day: number);
205
  equals(other: NgbDate): boolean;
206
  before(other: NgbDate): boolean;
207
  after(other: NgbDate): boolean;
208
  toString(): string;
209
}
210
```
211

212
[Datepicker Components](./datepicker.md)
213

214
### Modal Components
215

216
Service-based modal dialogs with backdrop and keyboard support.
217

218
```typescript { .api }
219
@Injectable({ providedIn: 'root' })
220
class NgbModal {
221
  open(content: any, options?: NgbModalOptions): NgbModalRef;
222
  dismissAll(reason?: any): void;
223
}
224

225
class NgbModalRef {
226
  componentInstance?: any;
227
  result: Promise<any>;
228
  
229
  close(result?: any): void;
230
  dismiss(reason?: any): void;
231
  update(options: NgbModalUpdatableOptions): void;
232
}
233

234
interface NgbModalOptions {
235
  animation?: boolean;
236
  backdrop?: boolean | 'static';
237
  beforeDismiss?: () => boolean | Promise<boolean>;
238
  centered?: boolean;
239
  container?: string | Element;
240
  keyboard?: boolean;
241
  scrollable?: boolean;
242
  size?: 'sm' | 'lg' | 'xl';
243
  windowClass?: string;
244
}
245
```
246

247
[Modal Components](./modal.md)
248

249
### Navigation Components
250

251
Flexible navigation components supporting tabs, pills, and custom layouts.
252

253
```typescript { .api }
254
@Component({
255
  selector: '[ngbNav]',
256
  exportAs: 'ngbNav'
257
})
258
class NgbNav {
259
  @Input() activeId: any;
260
  @Input() animation: boolean;
261
  @Input() destroyOnHide: boolean;
262
  @Input() orientation: 'horizontal' | 'vertical';
263
  @Input() roles: 'tablist' | false;
264
  @Output() activeIdChange: EventEmitter<any>;
265
  @Output() navChange: EventEmitter<NgbNavChangeEvent>;
266
  
267
  select(id: any): void;
268
}
269
```
270

271
[Navigation Components](./navigation.md)
272

273
### Form Components
274

275
Enhanced form controls including rating, timepicker, and typeahead.
276

277
```typescript { .api }
278
@Component({
279
  selector: 'ngb-rating',
280
  exportAs: 'ngbRating'
281
})
282
class NgbRating implements ControlValueAccessor {
283
  @Input() max: number;
284
  @Input() rate: number;
285
  @Input() readonly: boolean;
286
  @Input() resettable: boolean;
287
  @Input() starTemplate: TemplateRef<any>;
288
  @Output() hover: EventEmitter<number>;
289
  @Output() leave: EventEmitter<number>;
290
  @Output() rateChange: EventEmitter<number>;
291
}
292

293
@Component({
294
  selector: 'ngb-timepicker',
295
  exportAs: 'ngbTimepicker'
296
})
297
class NgbTimepicker implements ControlValueAccessor {
298
  @Input() meridian: boolean;
299
  @Input() spinners: boolean;
300
  @Input() seconds: boolean;
301
  @Input() hourStep: number;
302
  @Input() minuteStep: number;
303
  @Input() secondStep: number;
304
  @Input() readonlyInputs: boolean;
305
  @Input() size: 'small' | 'medium' | 'large';
306
}
307
```
308

309
[Form Components](./forms.md)
310

311
### Feedback Components
312

313
User feedback components including alerts, toast notifications, tooltips, and popovers.
314

315
```typescript { .api }
316
@Directive({
317
  selector: '[ngbTooltip]',
318
  exportAs: 'ngbTooltip'
319
})
320
class NgbTooltip {
321
  @Input() ngbTooltip: string | TemplateRef<any>;
322
  @Input() tooltipClass: string;
323
  @Input() placement: Placement;
324
  @Input() triggers: string;
325
  @Input() container: string;
326
  @Input() disableTooltip: boolean;
327
  @Output() shown: EventEmitter<void>;
328
  @Output() hidden: EventEmitter<void>;
329
  
330
  open(): void;
331
  close(): void;
332
  toggle(): void;
333
}
334

335
@Component({
336
  selector: 'ngb-toast',
337
  exportAs: 'ngbToast'
338
})
339
class NgbToast {
340
  @Input() animation: boolean;
341
  @Input() autohide: boolean;
342
  @Input() delay: number;
343
  @Input() header: string;
344
  @Output() hide: EventEmitter<void>;
345
  
346
  show(): void;
347
  hide(): void;
348
}
349
```
350

351
[Feedback Components](./feedback.md)
352

353
### Layout Components
354

355
Layout and navigation components including collapse, offcanvas, and pagination.
356

357
```typescript { .api }
358
@Directive({
359
  selector: '[ngbCollapse]',
360
  exportAs: 'ngbCollapse'
361
})
362
class NgbCollapse {
363
  @Input() ngbCollapse: boolean;
364
  @Input() animation: boolean;
365
  @Output() ngbCollapseChange: EventEmitter<boolean>;
366
  
367
  toggle(): void;
368
}
369

370
@Injectable({ providedIn: 'root' })
371
class NgbOffcanvas {
372
  open(content: any, options?: NgbOffcanvasOptions): NgbOffcanvasRef;
373
  dismissAll(reason?: any): void;
374
}
375
```
376

377
[Layout Components](./layout.md)
378

379
## Utility Types
380

381
```typescript { .api }
382
type Placement = 
383
  | 'auto' | 'top' | 'bottom' | 'start' | 'left' | 'end' | 'right'
384
  | 'top-start' | 'top-left' | 'top-end' | 'top-right'
385
  | 'bottom-start' | 'bottom-left' | 'bottom-end' | 'bottom-right'
386
  | 'start-top' | 'left-top' | 'start-bottom' | 'left-bottom'
387
  | 'end-top' | 'right-top' | 'end-bottom' | 'right-bottom';
388

389
type PlacementArray = Placement[];
390

391
interface NgbDateStruct {
392
  year: number;
393
  month: number;
394
  day: number;
395
}
396

397
interface NgbTimeStruct {
398
  hour: number;
399
  minute: number;
400
  second: number;
401
}
402
```