# ng2-bs3-modal

> Angular Boostrap 3 Modal Component

Latest version **0.15.0** (published 2018-07-07) · ISC license · 0 weekly downloads

## Install

```sh
npm install ng2-bs3-modal
pnpm add ng2-bs3-modal
yarn add ng2-bs3-modal
bun add ng2-bs3-modal
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.15.0 |
| Published | 2018-07-07 |
| First published | 2016-02-05 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 490.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | dougludlow |
| Keywords | angular, angular2, bootstrap, modal, component |

## Links

- npm: https://www.npmjs.com/package/ng2-bs3-modal
- Repository: https://github.com/dougludlow/ng2-bs3-modal
- Issues: https://github.com/dougludlow/ng2-bs3-modal/issues
- npm.io page: https://npm.io/package/ng2-bs3-modal

## Dependencies (1)

- [tslib](https://npm.io/package/tslib.md) ^1.9.0

## Alternatives

- [@sveltejs/kit](https://npm.io/package/@sveltejs/kit.md) — 2.2M weekly downloads
- [@atlaskit/theme](https://npm.io/package/@atlaskit/theme.md) — 402.0K weekly downloads
- [@tangle-network/brand](https://npm.io/package/@tangle-network/brand.md) — 10.0K weekly downloads
- [seneca](https://npm.io/package/seneca.md) — 7.4K weekly downloads
- [@bsb/base](https://npm.io/package/@bsb/base.md) — 7.2K weekly downloads

## Recent versions

- 0.15.0 (latest) — 2018-07-07
- 0.13.0 — 2017-10-05
- 0.12.1 — 2017-10-02
- 0.12.0 — 2017-10-02
- 0.11.10 — 2017-09-28
- 0.11.9 — 2017-09-28
- 0.11.7 — 2017-09-27
- 0.11.6 — 2017-09-27
- 0.11.5 — 2017-09-27
- 0.11.4 — 2017-09-27
- 0.11.2 — 2017-09-27
- 0.11.1 — 2017-09-27
- 0.11.0 — 2017-09-23
- 0.10.4 — 2016-09-30
- 0.10.3 — 2016-09-30
- … 35 more at https://npm.io/package/ng2-bs3-modal/versions

## README

# ng2-bs3-modal [![npm version](https://badge.fury.io/js/ng2-bs3-modal.svg)](http://badge.fury.io/js/ng2-bs3-modal) [![npm downloads](https://img.shields.io/npm/dm/ng2-bs3-modal.svg)](https://npmjs.org/ng2-bs3-modal) [![Build Status](https://travis-ci.org/dougludlow/ng2-bs3-modal.svg?branch=master)](https://travis-ci.org/dougludlow/ng2-bs3-modal)
Angular (2+) Bootstrap 3 Modal Component

## Demo
http://dougludlow.github.io/ng2-bs3-modal/demo/

## Prerequisites

If you're using Typescript in your project, `ng2-bs3-modal` requires Typescript v2.0.0 or greater. Also make sure that your editor (Visual Studio Code, Atom, Webstorm, etc.) supports Typescript >= v2.0.0 or you'll see errors even though it compiles.

## Dependencies

`ng2-bs3-modal` depends on `bootstrap` which depends on `jquery`, you'll need to include both scripts before `ng2-bs3-modal` or somehow make them available globally, depending on your build system.

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.0/jquery.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.js"></script>
```

## Install

npm
```bash
npm install --save ng2-bs3-modal
```

yarn
```bash
yarn add ng2-bs3-modal
```

Then include the `ng2-bs3-modal` in your project.

Using [SystemJS](https://github.com/systemjs/systemjs), you can add a mapping to your `System.config`:

```javascript
System.config({
    defaultJSExtensions: true,
    map: {
        'ng2-bs3-modal': 'node_modules/ng2-bs3-modal'
    }
});
```

Or you can include a reference to the bundle in your html:

```html
<script src="node_modules/ng2-bs3-modal/bundles/ng2-bs3-modal.system.js"></script>
```

Then include the module in the `imports` collection of your app's module:

```typescript
import { NgModule } from '@angular/core';
import { BsModalModule } from 'ng2-bs3-modal';

@NgModule({
    imports: [ BsModalModule ]
    ...
})
export class MyAppModule { }
```

## Example Projects

The following is a list of basic demo projects that use the `ng2-bs3-modal`:

- [npm](https://github.com/dougludlow/ng2-bs3-modal-demo-npm)
- [SystemJS](https://github.com/dougludlow/ng2-bs3-modal-demo-systemjs)
- [jspm](https://github.com/dougludlow/ng2-bs3-modal-demo-jspm)
- [angular-cli](https://github.com/dougludlow/ng2-bs3-modal-demo-angular-cli)
- [webpack](https://github.com/dougludlow/ng2-bs3-modal-demo-webpack)

Feel free to request more.

## API

### BsModalComponent

#### Inputs

- `animation: boolean`, default: `true`

   Specify `false` to simply show the modal rather than having it fade in/out of view.
   
- `backdrop: string | boolean`, default: `true`

   Specify `'static'` for a backdrop which doesn't close the modal on click or `false` for no backdrop.
   
- `keyboard: boolean`, default: `true`

   Closes the modal when escape key is pressed. Specify `false` to disable.
   
- `size: string`, default: `undefined`

   Specify `'sm'` for small and `'lg'` for large.

- `cssClass: string`, default: `undefined`

   Applies the given class to the modal. Can be used to styles the modal; for example, giving it a custom size.

#### Outputs

- `onShow: EventEmitter<Event>`

   Emits when the `show.bs.modal` event is triggered, just before the modal is shown. Call `Event.preventDefault()` to cancel the modal from showing.

- `onHide: EventEmitter<BsModalHideEvent>`

   Emits when the `hide.bs.modal` event is triggered, just before the modal is hidden. Call `BsModalHideEvent.event.preventDefault()` to cancel the modal from hiding.

- `onClose: EventEmitter<any>`

   Emits when `ModalComponent.close()` is called. Will emit whatever was passed into `ModalComponent.close()`.

- `onDismiss: EventEmitter<BsModalHideType>`
    
   Emits when `ModalComponent.dismiss()` is called, or when the modal is dismissed with the keyboard or backdrop. Returns a `BsModalHideType` that can be used to determine how the modal was dismissed.

- `onOpen: EventEmitter`
    
   Emits when `ModalComponent.open()` is called.

#### Methods

- `open(size?: string): Promise`

   Opens the modal. Size is optional. Specify `'sm'` for small and `'lg'` for large to override size. Returns a promise that resolves when the modal is completely shown.
   
- `close(value?: any): Promise<any>`

   Closes the modal. Causes `onClose` to be emitted. Returns a promise that resolves the value passed to `close` when the modal is completely hidden.

- `dismiss(): Promise`

   Dismisses the modal. Causes `onDismiss` to be emitted. Returns a promise that resolves when the modal is completely hidden.

### BsModalHeaderComponent

#### Inputs

- `showDismiss: boolean`, default: `false`

   Show or hide the close button in the header. Specify `true` to show.
   
### BsModalFooterComponent

#### Inputs

- `showDefaultButtons: boolean`, default: `false`

   Show or hide the default 'Close' and 'Dismiss' buttons in the footer. Specify `true` to show.

- `closeButtonLabel: string`, default: `'Close'`

   Change the label in the default 'Close' button in the footer. Has no effect if showDefaultButtons aren't set.

- `dismissButtonLabel: string`, default: `'Dismiss'`

   Change the label in the default 'Dismiss' button in the footer. Has no effect if showDefaultButtons aren't set.

### BsModalService

#### Methods

- `dismissAll(): void`
   
   Dismiss all open modals. Inject the `BsModalService` into a componet/service to use.

## Example Usage

### Default modal

```html
<button type="button" class="btn btn-default" (click)="modal.open()">Open me!</button>

<bs-modal #modal>
    <bs-modal-header [showDismiss]="true">
        <h4 class="modal-title">I'm a modal!</h4>
    </bs-modal-header>
    <bs-modal-body>
        Hello World!
    </bs-modal-body>
    <bs-modal-footer [showDefaultButtons]="true"></bs-modal-footer>
</bs-modal>
```
    
![Example](src/demo/assets/modal.png)
    
### Static modal

This will create a modal that cannot be closed with the escape key or by clicking outside of the modal.

```html
<bs-modal #modal [keyboard]="false" [backdrop]="'static'">
    <bs-modal-header [showDismiss]="false">
        <h4 class="modal-title">I'm a modal!</h4>
    </bs-modal-header>
    <bs-modal-body>
        Hello World!
    </bs-modal-body>
    <bs-modal-footer [showDefaultButtons]="true"></bs-modal-footer>
</bs-modal>
```
    
### Use custom buttons in footer

```html    
<bs-modal #modal>
    <bs-modal-header>
        <h4 class="modal-title">I'm a modal!</h4>
    </bs-modal-header>
    <bs-modal-body>
        Hello World!
    </bs-modal-body>
    <bs-modal-footer>
        <button type="button" class="btn btn-default" data-dismiss="modal" (click)="modal.dismiss()">Cancel</button>
        <button type="button" class="btn btn-primary" (click)="modal.close()">Ok</button>
    </bs-modal-footer>
</bs-modal>
```
    
![Example](src/demo/assets/modal-custom-footer.png)
    
### Opening and closing the modal from a parent component

```typescript
import { Component, ViewChild } from '@angular/core';
import { BsModalComponent } from 'ng2-bs3-modal';

@Component({
    selector: 'parent-component',
    template: `
        <bs-modal #myModal>
            ...
        </bs-modal>
    `
})
export class ParentComponent {
    @ViewChild('myModal')
    modal: BsModalComponent;

    close() {
        this.modal.close();
    }
    
    open() {
        this.modal.open();
    }
}
```

### Opening the modal when the parent component loads

```typescript
import { Component, ViewChild, AfterViewInit } from '@angular/core';
import { BsModalComponent } from 'ng2-bs3-modal';

@Component({
    selector: 'parent-component',
    template: `
        <bs-modal #myModal>
            ...
        </bs-modal>
    `
})
export class ParentComponent implements AfterViewInit {
    @ViewChild('myModal')
    modal: BsModalComponent;

    ngAfterViewInit() {
        this.modal.open();
    }
}
```

Note: `ViewChild` doesn't resolve the `modal` property until `AfterViewInit`. `OnInit` is too early and will result in an "undefined" error.

### Multiple modals in a component

```typescript
import { Component, ViewChild } from '@angular/core';
import { BsModalComponent } from 'ng2-bs3-modal';

@Component({
    selector: 'parent-component',
    template: `
        <bs-modal #myFirstModal>
            ...
        </bs-modal>
        <bs-modal #mySecondModal>
            ...
        </bs-modal>
    `
})
export class ParentComponent {
    @ViewChild('myFirstModal')
    modal1: BsModalComponent;
    
    @ViewChild('mySecondModal')
    modal2: BsModalComponent;
    
    ...
}
```

### Modal with a custom size

```typescript
import { Component, ViewChild } from '@angular/core';
import { BsModalComponent } from 'ng2-bs3-modal';

@Component({
    selector: 'parent-component',
    styles: ['>>> .modal-xl { width: 1100px; }'],
    template: `
        <bs-modal cssClass="modal-xl" #modal>
            ...
        </bs-modal>
    `
})
export class ParentComponent {
    ...
}
```

Note: Angular2 emulates the shadow dom by prefixing component styles with a unique identifier. Because the modal is attached to the body tag, it doesn't pick up these styles. You will need to add the `/deep/` or `>>>` selector in order for the style to take effect. See [Component Styles](https://angular.io/docs/ts/latest/guide/component-styles.html#!#-deep-).

### Modal in NgFor

```typescript
import { Component, ViewChildren } from '@angular/core';
import { BsModalComponent } from 'ng2-bs3-modal';

@Component({
    selector: 'parent-component',
    template: `
        <button type="button" class="btn btn-default" (click)="modal.open()">Open me!</button>
        <div *ngFor="let item in items; trackBy: item.id">
            <bs-modal #modal>
                ...
            </bs-modal>
        </div>
    `
})
export class ParentComponent {
    @ViewChildren(BsModalComponent)
    modals: QueryList<BsModalComponent>; // How to access a collection of modals
    ...
}
```

Note: If you are updating items asynchronously, make sure you are using `trackBy` in the `ngFor` directive so that Angular doesn't teardown and redraw the elements each time the collection is changed. See [NgFor Directive](https://angular.io/docs/ts/latest/api/common/index/NgFor-directive.html) for more details.

### Modal with validation

```html
<bs-modal #validationModal>
    <form #modalForm="ngForm">
        <bs-modal-header [showDismiss]="true">
            <h4 class="modal-title">I'm a modal!</h4>
        </bs-modal-header>
        <bs-modal-body>
            <div class="form-group">
                <label for="firstName">First Name</label>
                <input type="text" class="form-control" required [(ngModel)]="firstName" name="firstName" id="firstName">
            </div>
            <div class="form-group">
                <label for="lastName">Last Name</label>
                <input type="text" class="form-control" required [(ngModel)]="lastName" name="lastName" id="lastName">
            </div>
        </bs-modal-body>
        <bs-modal-footer>
            <button type="button" class="btn btn-default" data-dismiss="modal" (click)="validationModal.dismiss()">Cancel</button>
            <button type="button" class="btn btn-primary" [disabled]="!modalForm.valid" (click)="validationModal.close()">Save</button>
        </bs-modal-footer>
    </form>
</bs-modal>
```

### Autofocus on a textbox when modal is opened

```html    
<bs-modal #modal>
    <bs-modal-header>
        <h4 class="modal-title">I'm a modal!</h4>
    </bs-modal-header>
    <bs-modal-body>
        <div class="form-group">
            <label for="textbox">I'm a textbox!</label>
            <input autofocus type="text" class="form-control" id="textbox">
        </div>        
    </bs-modal-body>
    <bs-modal-footer [showDefaultButtons]="true"></bs-modal-footer>
</bs-modal>
```

## Building

```bash
git clone https://github.com/dougludlow/ng2-bs3-modal.git
yarn
yarn build
```

## Running 

```bash
yarn start
```

Navigate to http://localhost:4200/ in your browser.

## Testing

```bash
yarn test
```

To run tests once without watching:
```bash
yarn test:single
```

## Bugs/Contributions

Report all bugs and feature requests on the [issue tracker](https://github.com/dougludlow/ng2-bs3-modal/issues).

Contributions are welcome! Feel free to open a [pull request](https://github.com/dougludlow/ng2-bs3-modal/pulls).

---
_Source: https://npm.io/package/ng2-bs3-modal · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._