Components

Ionic apps are made of high-level building blocks called components. Components allow you to quickly construct an interface for your app. Ionic comes with a number of components, including modals, popups, and cards. Although components are primarily HTML and CSS, some components also include JavaScript functionality. Check out the examples below to see what each component looks like and to learn how to use each one. Once you’re familiar with the basics, head over to the API docs for ideas on how to customize each component.

Action Sheets

Improve this Doc

Action Sheets slide up from the bottom edge of the device screen, and display a set of options with the ability to confirm or cancel an action. Action Sheets can sometimes be used as an alternative to menus, however, they should not be used for navigation.

The Action Sheet always appears above any other components on the page, and must be dismissed in order to interact with the underlying content. When it is triggered, the rest of the page darkens to give more focus to the Action Sheet options.

For more information, Check out the API docs.

Basic Usage

Demo Source

import { ActionSheetController } from 'ionic-angular';

export class MyPage {
  constructor(public actionSheetCtrl: ActionSheetController) {
  }

  presentActionSheet() {
    let actionSheet = this.actionSheetCtrl.create({
      title: 'Modify your album',
      buttons: [
        {
          text: 'Destructive',
          role: 'destructive',
          handler: () => {
            console.log('Destructive clicked');
          }
        },{
          text: 'Archive',
          handler: () => {
            console.log('Archive clicked');
          }
        },{
          text: 'Cancel',
          role: 'cancel',
          handler: () => {
            console.log('Cancel clicked');
          }
        }
      ]
    });
    actionSheet.present();
  }
}

Alerts

Improve this Doc

Alerts are a great way to offer the user the ability to choose a specific action or list of actions. They also can provide the user with important information, or require them to make a decision (or multiple decisions).

From a UI perspective, Alerts can be thought of as a type of “floating” modal that covers only a portion of the screen. This means Alerts should only be used for quick actions like password verification, small app notifications, or quick options. More in depth user flows should be reserved for full screen ​Modals​.

Alerts are quite flexible, and can easily be customized.

For more information, Check out the API docs.

Basic Usage:

Demo Source

Basic Alerts are typically used to notify the user about new information (a change in the app, a new feature, etc), an urgent situation that requires acknowledgement, or as a confirmation to the user that an action was successful or not.

import { AlertController } from 'ionic-angular';

export class MyPage {
  constructor(public alertCtrl: AlertController) {
  }

  showAlert() {
    let alert = this.alertCtrl.create({
      title: 'New Friend!',
      subTitle: 'Your friend, Obi wan Kenobi, just accepted your friend request!',
      buttons: ['OK']
    });
    alert.present();
  }
}

Prompt Alerts

Demo Source

Prompts offer a way to input data or information. Often times Prompts will be used to ask the user for a password before moving forward in an application’s flow.

import { AlertController } from 'ionic-angular';

export class MyPage {
  constructor(public alertCtrl: AlertController) {
  }

  showPrompt() {
    let prompt = this.alertCtrl.create({
      title: 'Login',
      message: "Enter a name for this new album you're so keen on adding",
      inputs: [
        {
          name: 'title',
          placeholder: 'Title'
        },
      ],
      buttons: [
        {
          text: 'Cancel',
          handler: data => {
            console.log('Cancel clicked');
          }
        },
        {
          text: 'Save',
          handler: data => {
            console.log('Saved clicked');
          }
        }
      ]
    });
    prompt.present();
  }
}

Confirmation Alerts

Demo Source

Confirmation Alerts are used when it is required that the user explicitly confirms a particular choice before progressing forward in the app. A common example of the Confirmation Alert is checking to make sure a user wants to delete or remove a contact from their address book.

import { AlertController } from 'ionic-angular';

export class MyPage {
  constructor(public alertCtrl: AlertController) {
  }

  showConfirm() {
    let confirm = this.alertCtrl.create({
      title: 'Use this lightsaber?',
      message: 'Do you agree to use this lightsaber to do good across the intergalactic galaxy?',
      buttons: [
        {
          text: 'Disagree',
          handler: () => {
            console.log('Disagree clicked');
          }
        },
        {
          text: 'Agree',
          handler: () => {
            console.log('Agree clicked');
          }
        }
      ]
    });
    confirm.present();
  }
}

Radio

Demo Source

Radio Alerts are a type of Confirmation Alert, but use the Radio component to offer several choices. A set of options is provided to the user, but only one option can be chosen.

import { AlertController } from 'ionic-angular';

export class MyPage {
  constructor(public alertCtrl: AlertController) {
  }

  showRadio() {
    let alert = this.alertCtrl.create();
    alert.setTitle('Lightsaber color');

    alert.addInput({
      type: 'radio',
      label: 'Blue',
      value: 'blue',
      checked: true
    });

    alert.addButton('Cancel');
    alert.addButton({
      text: 'OK',
      handler: data => {
        this.testRadioOpen = false;
        this.testRadioResult = data;
      }
    });
    alert.present();
  }
}

Checkbox

Demo Source

Checkbox Alerts are a type of Confirmation Alert, but use the Checkbox component to offer several choices. They offer the user a set of options to choose from.

import { AlertController } from 'ionic-angular';

export class MyPage {
  constructor(public alertCtrl: AlertController) {
  }

  showCheckbox() {
    let alert = this.alertCtrl.create();
    alert.setTitle('Which planets have you visited?');

    alert.addInput({
      type: 'checkbox',
      label: 'Alderaan',
      value: 'value1',
      checked: true
    });

    alert.addInput({
      type: 'checkbox',
      label: 'Bespin',
      value: 'value2'
    });

    alert.addButton('Cancel');
    alert.addButton({
      text: 'Okay',
      handler: data => {
        console.log('Checkbox data:', data);
        this.testCheckboxOpen = false;
        this.testCheckboxResult = data;
      }
    });
    alert.present();
  }
}

Badges

Improve this Doc

Badges are small components that typically communicate a numerical value to the user. They are typically used within an item.

For more information, Check out the API docs.

Basic Usage

Demo Source

<ion-item>
  <ion-icon name="logo-twitter" item-left></ion-icon>
  Followers
  <ion-badge item-right>260k</ion-badge>
</ion-item>

Badges can also be given any color attribute:

<ion-badge secondary></ion-badge>

Buttons

Improve this Doc

Buttons are an essential way to interact with and navigate through an app, and should clearly communicate what action will occur after the user taps them. Buttons can consist of text and/or an icon, and can be enhanced with a wide variety of attributes.

For more information, Check out the API docs.

Basic Usage

Demo Source

<button>Button</button>

The primary property sets the color of the button. Ionic includes a number of default colors which can be easily overridden:

<button light>Light</button>
<button>Default</button>
<button secondary>Secondary</button>
<button danger>Danger</button>
<button dark>Dark</button>

Outline Style

Demo Source

To use the outline style for a button, just add the outline property:

<button light outline>Light Outline</button>
<button outline>Primary Outline</button>
<button secondary outline>Secondary Outline</button>
<button danger outline>Danger Outline</button>
<button dark outline>Dark Outline</button>

Clear Style

Demo Source

To use the clear style for a button, just add the clear property:

<button light clear>Light Clear</button>
<button clear>Primary Clear</button>
<button secondary clear>Secondary Clear</button>
<button danger clear>Danger Clear</button>
<button dark clear>Dark Clear</button>

Round Buttons

Demo Source

To create a button with rounded corners, just add the round property:

<button light round>Light Round</button>
<button round>Primary Round</button>
<button secondary round>Secondary Round</button>
<button danger round>Danger Round</button>
<button dark round>Dark Round</button>

Block Buttons

Demo Source

Adding block to a button will make the button take 100% of its parent’s width. It will also add display: block to the button:

<button block>Block Button</button>

Full Buttons

Demo Source

Adding full to a button will also make the button take 100% of its parent’s width. However, it will also remove the button’s left and right borders. This style is useful when the button should stretch across the entire width of the display.

<button full>Full Button</button>

Button Sizes

Demo Source

Add the large attribute to make a button larger, or small to make it smaller:

<button small>Small</button>
<button>Default</button>
<button large>Large</button>

Icon Buttons

Demo Source

To add icons to a button, add an icon component inside of it:

<!-- Float the icon left -->
<button>
  <ion-icon name="home"></ion-icon>
  Left Icon
</button>

<!-- Float the icon right -->
<button>
  Right Icon
  <ion-icon name="home"></ion-icon>
</button>

<!-- Only icon (no text) -->
<button>
  <ion-icon name="home"></ion-icon>
</button>

Floating Action Buttons

Demo Source

Adding fab to a button will turn it into a floating action button. This is a material design styled button that is meant to draw the user to take a specific action. Fab buttons are positioned absolutely, and their placement can be controlled by adding attributes like fab-top and fab-left. See the Button API spec for a full list of attributes.

<button fab>FAB</button>

Buttons In Components

Demo Source

Although buttons can be used on their own, they can easily be used within other components. For example, buttons can be added to a list item or a navbar.

<ion-header>
  <ion-navbar>
    <ion-buttons start>
      <button>
        <ion-icon name="contact"></ion-icon>
      </button>
    </ion-buttons>

    <ion-buttons end>
      <button>
        <ion-icon name="search"></ion-icon>
      </button>
    </ion-buttons>
  </ion-navbar>
</ion-header>

<ion-list>
  <ion-item>
    Left Icon Button
    <button outline item-right>
      <ion-icon name="star"></ion-icon>
      Left Icon
    </button>
  </ion-item>
</ion-list>

Cards

Improve this Doc

Cards are a great way to display important pieces of content, and are quickly emerging as a core design pattern for apps. They're are a great way to contain and organize information, while also setting up predictable expectations for the user. With so much content to display at once, and often so little screen realestate, cards have fast become the design pattern of choice for many companies, including the likes of Google, Twitter, and Spotify.

For mobile experiences, Cards make it easy to display the same information visually across many different screen sizes. They allow for more control, are flexible, and can even be animated. Cards are usually placed on top of one another, but they can also be used like a "page" and swiped between, left and right.

Basic Usage

Demo Source

Cards are primarily a CSS component. To use a basic card, follow this structure:

<ion-card>

  <ion-card-header>
    Card Header
  </ion-card-header>

  <ion-card-content>
    <!-- Add card content here! -->
  </ion-card-content>

</ion-card>

Card Headers

Just like a normal page, cards can be customized to include headers. To add a header to a card, add the <ion-card-header> component inside of your card:

<ion-card>
  <ion-card-header>
    Header
  </ion-card-header>
  <ion-card-content>
    The British use the term "header", but the American term "head-shot" the English simply refuse to adopt.
  </ion-card-content>
</ion-card>

Lists In Cards

Demo Source

A card can contain a list of items. Add an ion-list component inside of the ion-card-content to display a list:

<ion-card>
  <ion-card-header>
    Explore Nearby
  </ion-card-header>

  <ion-list>
    <button ion-item>
      <ion-icon name="cart" item-left></ion-icon>
      Shopping
    </button>

    <button ion-item>
      <ion-icon name="medical" item-left></ion-icon>
      Hospital
    </button>

    <button ion-item>
      <ion-icon name="cafe" item-left></ion-icon>
      Cafe
    </button>

    <button ion-item>
      <ion-icon name="paw" item-left></ion-icon>
      Dog Park
    </button>

    <button ion-item>
      <ion-icon name="beer" item-left></ion-icon>
      Pub
    </button>

    <button ion-item>
      <ion-icon name="planet" item-left></ion-icon>
      Space
    </button>

  </ion-list>
</ion-card>

Images In Cards

Demo Source

Images often vary in size, so it is important that they adopt a consistent style throughout your app. Images can easily be added to cards. Adding an image to a card will give the image a constant width, and a variable height. Lists, headers, and other card components can easily be combined with image cards. To add an image to a card, use the following markup:

<ion-card>
  <img src="img/nin-live.png"/>
  <ion-card-content>
    <ion-card-title>
      Nine Inch Nails Live
      </ion-card-title>
    <p>
      The most popular industrial group ever, and largely
      responsible for bringing the music to a mass audience.
    </p>
  </ion-card-content>
</ion-card>

Background Images

Demo Source

Cards can be used to achieve a multitude of designs. We provide many of the elements to achieve common designs, but sometimes it will be necessary to add custom styles. Adding background images to cards is a perfect example of how adding custom styles can achieve a completely different look.

The following html can be added to the content of a page:

<ion-content class="card-background-page">

  <ion-card>
    <img src="img/card-saopaolo.png"/>
    <div class="card-title">São Paulo</div>
    <div class="card-subtitle">41 Listings</div>
  </ion-card>

  <ion-card>
    <img src="img/card-amsterdam.png"/>
    <div class="card-title">Amsterdam</div>
    <div class="card-subtitle">64 Listings</div>
  </ion-card>

  <ion-card>
    <img src="img/card-sf.png"/>
    <div class="card-title">San Francisco</div>
    <div class="card-subtitle">72 Listings</div>
  </ion-card>

  <ion-card>
    <img src="img/card-madison.png"/>
    <div class="card-title">Madison</div>
    <div class="card-subtitle">28 Listings</div>
  </ion-card>

</ion-content>

Then, in the Sass file for the page:

.card-background-page {

  ion-card {
    position: relative;
    text-align: center;
  }

  .card-title {
    position: absolute;
    top: 36%;
    font-size: 2.0em;
    width: 100%;
    font-weight: bold;
    color: #fff;
  }

  .card-subtitle {
    font-size: 1.0em;
    position: absolute;
    top: 52%;
    width: 100%;
    color: #fff;
  }

}

Advanced Cards

The styles from different types of cards can be combined to create advanced cards. Cards can also use custom CSS. Below are a few advanced cards that have been built by combining various card attributes with a small amount of custom CSS.

Social Cards

Demo Source

It’s often necessary to create social cards within an application. Using a combination of different items in a card you can achieve this.

<ion-card>

  <ion-item>
    <ion-avatar item-left>
      <img src="img/marty-avatar.png">
    </ion-avatar>
    <h2>Marty McFly</h2>
    <p>November 5, 1955</p>
  </ion-item>

  <img src="img/advance-card-bttf.png">

  <ion-card-content>
    <p>Wait a minute. Wait a minute, Doc. Uhhh... Are you telling me that you built a time machine... out of a DeLorean?! Whoa. This is heavy.</p>
  </ion-card-content>

  <ion-row>
    <ion-col>
      <button primary clear small>
        <ion-icon name="thumbs-up"></ion-icon>
        <div>12 Likes</div>
      </button>
    </ion-col>
    <ion-col>
      <button primary clear small>
        <ion-icon name="text"></ion-icon>
        <div>4 Comments</div>
      </button>
    </ion-col>
    <ion-col center text-center>
      <ion-note>
        11h ago
      </ion-note>
    </ion-col>
  </ion-row>

</ion-card>

Map Cards

Demo Source

A combination of Ionic components can be used to create a card that appears as a map.

<ion-card>

  <img src="img/advance-card-map-madison.png">
  <button fab fab-right fab-top>
    <ion-icon name="pin"></ion-icon>
  </button>

  <ion-item>
    <ion-icon name="football" item-left large></ion-icon>
    <h2>Museum of Football</h2>
    <p>11 N. Way St, Madison, WI 53703</p>
  </ion-item>

  <ion-item>
    <ion-icon name="wine" item-left large ></ion-icon>
    <h2>Institute of Fine Cocktails</h2>
    <p>14 S. Hop Avenue, Madison, WI 53703</p>
  </ion-item>

  <ion-item>
    <span item-left>18 min</span>
    <span item-left>(2.6 mi)</span>
    <button primary clear item-right>
      <ion-icon name="navigate"></ion-icon>
      Start
    </button>
  </ion-item>

</ion-card>

Checkbox

Improve this Doc

A checkbox is an input component that holds a boolean value. Checkboxes are no different than HTML checkbox inputs. However, like other Ionic components, checkboxes are styled differently on each platform. Use the checked attribute to set the default value, and the disabled attribute to disable the user from changing the value.

For more information, Check out the API docs.

Basic Usage

Demo Source

<ion-item>
  <ion-label>Daenerys Targaryen</ion-label>
  <ion-checkbox dark checked="true"></ion-checkbox>
</ion-item>

<ion-item>
  <ion-label>Arya Stark</ion-label>
  <ion-checkbox disabled="true"></ion-checkbox>
</ion-item>

DateTime

Improve this Doc

The DateTime component is used to present an interface which makes it easy for users to select dates and times. The DateTime component is similar to the native <input type="datetime-local"> element, however, Ionic’s DateTime component makes it easy to display the date and time in a preferred format, and manage the datetime values.

For more information, Check out the API docs.

Basic Usage

Demo Source

<ion-item>
  <ion-label>Start Time</ion-label>
  <ion-datetime displayFormat="h:mm A" pickerFormat="h mm A" [(ngModel)]="event.timeStarts"></ion-datetime>
</ion-item>

Gestures

Improve this Doc

Basic gestures can be accessed from HTML by binding to tap, press, pan, swipe, rotate, and pinch events.

Basic Usage

Demo Source

<ion-card (tap)="tapEvent($event)">
  <ion-item>
    Tapped:  times
  </ion-item>
</ion-card>

Grid

Improve this Doc

Ionic’s grid system is based on flexbox, a CSS feature supported by all devices that Ionic supports. The grid is composed of three units — grid, rows and columns. Columns will expand to fill their row, and will resize to fit additional columns.

Rows have no padding or margin applied to them. If that is needed, ion-grid can be added to provide additional padding.

In order to set width use width attribute on ion-col tag.

Demo Source

<ion-grid>
  <ion-row>
    <ion-col width-10>This column will take 10% of space</ion-col>
  </ion-row>
</ion-grid>
Explicit Column Percentage Attributes
width-10 10%
width-20 20%
width-25 25%
width-33 33.3333%
width-50 50%
width-67 66.6666%
width-75 75%
width-80 80%
width-90 90%

Use the offset attribute on a column to set its percent offset from the left (eg: offset-25). To change how columns in a row align vertically, add the center or baseline attribute to an <ion-row>.

Use the wrap attribute on an <ion-row> element to allow items in that row to wrap. This applies the flex-wrap: wrap; style to the <ion-row> element.

Icons

Improve this Doc

Ionic comes with the same 700+ Ionicons icons we’ve all come to know and love.

For more information, Check out the API docs.

Basic Usage

Demo Source

To use an icon, populate the name attribute on the ion-icon component:

<ion-icon name="heart"></ion-icon>

Active / Inactive Icons

All icons have both active and inactive states. Active icons are typically full and thick, where as inactive icons are outlined and thin. Set the isActive attribute to true or false to change the state of the icon. Icons will default to active if a value is not specified.

<ion-icon name="heart"></ion-icon>                    <!-- active -->
<ion-icon name="heart" isActive="false"></ion-icon>  <!-- inactive -->

Platform Specific Icons

Many icons have both Material Design and iOS versions. Ionic will automatically use the correct version based on the platform.

To specify the icon to use for each platform, use the md and ios attributes and provide the platform specific icon name.

<ion-icon ios="logo-apple" md="logo-android"></ion-icon>

Variable Icons

To set an icon using a variable:

<ion-icon [name]="myIcon"></ion-icon>
export class MyFirstPage {
  // use the home icon
  myIcon: string = "home";
}

Explore the full icon set

Inputs

Improve this Doc

Inputs are essential for collecting and handling user input in a secure way. They should follow styling and interaction guidelines for each platform, so that they are intuitive for users to interact with. Ionic uses Angular 2’s form library, which can be thought of as two dependent pieces, Controls, and Control Groups.

Each input field in a form has a Control, a function that binds to the value in the field, and performs validation. A Control Group is a collection of Controls. Control Groups handle form submission, and provide a high level API that can be used to determine whether the entire form is valid.

A number of attributes that can be used to style forms and their various input fields are listed below. For more info on form logic, check out the Inputs API docs.

For more information, Check out the API docs.

Fixed Labels

Demo Source

Use fixed to place a label to the left of the input element. The label does not hide when text is entered. The input will align on the same position, regardless of the length of the label. Placeholder text can be used in conjunction with a fixed label.

<ion-list>

  <ion-item>
    <ion-label fixed>Username</ion-label>
    <ion-input type="text" value=""></ion-input>
  </ion-item>

  <ion-item>
    <ion-label fixed>Password</ion-label>
    <ion-input type="password"></ion-input>
  </ion-item>

</ion-list>

Floating Labels

Demo Source

Floating labels are labels that animate or “float” up when the input is selected. Add the floating attribute to an ion-label to use.

Enter text in the example to the right to see the floating labels in action.

<ion-list>

  <ion-item>
    <ion-label floating>Username</ion-label>
    <ion-input type="text"></ion-input>
  </ion-item>

  <ion-item>
    <ion-label floating>Password</ion-label>
    <ion-input type="password"></ion-input>
  </ion-item>

</ion-list>

Inline Labels

Demo Source

An ion-label without any attributes is an inline label. The label does not hide when text is entered. Placeholder text can be used in conjunction with an inline label.

<ion-list>

  <ion-item>
    <ion-label>Username</ion-label>
    <ion-input type="text"></ion-input>
  </ion-item>

  <ion-item>
    <ion-label>Password</ion-label>
    <ion-input type="password"></ion-input>
  </ion-item>

</ion-list>

<div padding>
  <button block>Sign In</button>
</div>

Inset Labels

Demo Source

By default each input item will fill 100% of the width of its parent element. Make the input inset by adding the inset attribute to the ion-list component.

<ion-list inset>

  <ion-item>
    <ion-label>Username</ion-label>
    <ion-input type="text"></ion-input>
  </ion-item>

  <ion-item>
    <ion-label>Password</ion-label>
    <ion-input type="password"></ion-input>
  </ion-item>

</ion-list>

Placeholder Labels

Demo Source

Add the placeholder attribute to an <input> element to simulate the input’s label. When text is entered into the input, the placeholder label is hidden.

<ion-list>

  <ion-item>
    <ion-input type="text" placeholder="Username"></ion-input>
  </ion-item>

  <ion-item>
    <ion-input type="password" placeholder="Password"></ion-input>
  </ion-item>

</ion-list>

Stacked Labels

Demo Source

A stacked label will always appear on top of the input. Add the stacked attribute to an ion-label to use. Placeholder text can be used in conjunction with an stacked label.

<ion-list>

  <ion-item>
    <ion-label stacked>Username</ion-label>
    <ion-input type="text"></ion-input>
  </ion-item>

  <ion-item>
    <ion-label stacked>Password</ion-label>
    <ion-input type="password"></ion-input>
  </ion-item>

</ion-list>

Lists

Improve this Doc

Lists are used to display rows of information, such as a contact list, playlist, or menu. Or maybe something crazy we don’t even know exists yet!

For more information, Check out the List API docs and the Item API docs.

Basic Usage

Demo Source

By default, all lists will be styled with divider lines:

<ion-list>
  <ion-item *ngFor="let item of items" (click)="itemSelected(item)">
    {{item.title}}
  </ion-item>
</ion-list>

No Lines

Demo Source

Adding the no-lines attribute will hide the dividers between list items:

<ion-list no-lines>
  <ion-item *ngFor="let item of items" (click)="itemSelected(item)">
    {{item.title}}
  </ion-item>
</ion-list>

Inset List

Demo Source

Lists don’t have an outside margin by default. To add one, add the inset attribute to ion-list component.

<ion-list inset>
  <ion-item *ngFor="let item of items" (click)="itemSelected(item)">
    {{item.title}}
  </ion-item>
</ion-list>

List Dividers

Demo Source

To divide groups of items, use <ion-item-group> instead of <ion-list>. Use <ion-item-divider> components to divide the group in to multiple sections:

<ion-content>
    <ion-item-group>

      <ion-item-divider light>A</ion-item-divider>
      <ion-item>Angola</ion-item>
      <ion-item>Argentina</ion-item>

    </ion-item-group>
</ion-content>

List Headers

Demo Source

Each list can include a header at the top of the list:

<ion-list>
  <ion-list-header>
    Action
  </ion-list-header>
  <ion-item>Terminator II</ion-item>
  <ion-item>The Empire Strikes Back</ion-item>
  <ion-item>Blade Runner</ion-item>
</ion-list>

Icon List

Demo Source

Adding icons to list items is a great way to hint about the contents of each item. The position of the icon can be set using the item-left and item-right attributes. The size of the icon defaults to small, and can be made larger with the large attribute.

<ion-list>
  <ion-item>
    <ion-icon name="leaf" item-left></ion-icon>
      Herbology
    <ion-icon name="rose" item-right></ion-icon>
  </ion-item>
</ion-list>

Avatar List

Demo Source

Item avatars showcase an image larger than an icon, but smaller than a thumbnail. To use an avatar, add an <ion-avatar> component inside of an item. The position of the avatar can be set using the item-left and item-right attributes:

<ion-list>
  <ion-item>
    <ion-avatar item-left>
      <img src="img/avatar-cher.png">
    </ion-avatar>
    <h2>Cher</h2>
    <p>Ugh. As if.</p>
  </ion-item>
</ion-list>

Multi-line List

Demo Source

Multi-line lists are identical to regular lists, except items have multiple lines of text. When an <ion-item> component contains multiple header or paragraph elements, it will automatically expand it’s height to fit the new lines of text. Below is an example with three lines of text:

<ion-list>
  <ion-item>
    <ion-avatar item-left>
      <img src="img/avatar-finn.png">
    </ion-avatar>
    <h2>Finn</h2>
    <h3>Don't Know What To Do!</h3>
    <p>I've had a pretty messed up day. If we just...</p>
  </ion-item>
</ion-list>

Sliding List

Demo Source

Sliding items can be swiped to the left or right to reveal a hidden set of buttons. To use a sliding item, add an ion-item-sliding component inside of an ion-list component. Next, add an <ion-item-options> component inside of the sliding item to contain the buttons.

For more information, Check out the API docs.

<ion-list>
  <ion-item-sliding>
    <ion-item>
      <ion-avatar item-left>
        <img src="img/slimer.png">
      </ion-avatar>
      <h2>Slimer</h2>
    </ion-item>
    <ion-item-options side="left">
      <button primary>
        <ion-icon name="text"></ion-icon>
        Text
      </button>
      <button secondary>
        <ion-icon name="call"></ion-icon>
        Call
      </button>
    </ion-item-options>
    <ion-item-options side="right">
      <button primary>
        <ion-icon name="mail"></ion-icon>
        Email
      </button>
    </ion-item-options>
  </ion-item-sliding>
</ion-list>

Thumbnail List

Demo Source

Item thumbnails showcase an image that takes up the entire height of an item. To use a thumbnail, add an <ion-thumbnail> component inside of an item. The position of the thumbnail can be set using the item-left and item-right attributes:

<ion-list>
  <ion-item>
    <ion-thumbnail item-left>
      <img src="img/thumbnail-totoro.png">
    </ion-thumbnail>
    <h2>My Neighbor Totoro</h2>
    <p>Hayao Miyazaki • 1988</p>
    <button clear item-right>View</button>
  </ion-item>
</ion-list>

Loading

Improve this Doc

The Loading component is an overlay that prevents user interaction while indicating activity. By default, it shows a spinner based on the mode. Dynamic content can be passed and displayed with the spinner. The spinner can be hidden or customized to use several predefined options. The loading indicator is presented on top of other content even during navigation.

For more information, Check out the API docs.

Basic Usage

Demo Source

import { LoadingController } from 'ionic-angular';

export class MyPage {
  constructor(public loadingCtrl: LoadingController) {
  }

  presentLoading() {
    let loader = this.loadingCtrl.create({
      content: "Please wait...",
      duration: 3000
    });
    loader.present();
  }
}

Improve this Doc

Menu is a side-menu navigation that can be dragged out or toggled to show. The content of a menu will be hidden when the menu is closed.

Menu adapts to the appropriate style based on the platform.

For more information, Check out the API docs.

Basic Usage

Demo Source

<ion-menu [content]="content">
  <ion-toolbar>
    <ion-title>Pages</ion-title>
  </ion-toolbar>
  <ion-content>
    <ion-list>
      <button ion-item (click)="openPage(loginPage)">
        Login
      </button>
      <button ion-item (click)="openPage(signupPage)">
        Signup
      </button>
    </ion-list>
  </ion-content>
</ion-menu>

<ion-nav id="nav" #content [root]="rootPage"></ion-nav>

Modals

Improve this Doc

Modals slide in off screen to display a temporary UI, often used for login or signup pages, message composition, and option selection.

For more information, Check out the API docs.

Basic Usage

Demo Source

import { ModalController } from 'ionic-angular';
import { ModalPage } from './modal-page';

export class MyPage {
  constructor(public modalCtrl: ModalController) {
  }

  presentModal() {
    let modal = this.modalCtrl.create(ModalPage);
    modal.present();
  }
}

Improve this Doc

For more in depth information on navigation, see the Nav API reference.

Navigation is how users move between different pages in your app. Ionic’s navigation follows standard native navigation concepts, like those in iOS. In order to enable native-like navigation, we’ve built a few new navigation components that might feel different for developers used to traditional desktop browser navigation.

There are several ways to navigate throughout an Ionic app:

Basic Navigation

Demo Source

Navigation is handled through the <ion-nav> component, which works as a simple stack that new pages are pushed onto and popped off of, corresponding to moving forward and backward in history.

We start with a root page that loads the Nav component:

import {StartPage} from 'start'

@Component({
  template: '<ion-nav [root]="rootPage"></ion-nav>'
})
class MyApp {
  // First page to push onto the stack
  rootPage = StartPage;
}

Next, we can access the Navigation Controller in each page that is navigated to by injecting it into any of our Pages. Note that Page components does not need a selector. Ionic adds these automatically .

@Component({
  template: `
  <ion-header>
    <ion-navbar>
      <ion-title>Login</ion-title>
    </ion-navbar>
  </ion-header>

  <ion-content>Hello World</ion-content>`
})
export class StartPage {
  constructor(public navCtrl: NavController) {
  }
}

To navigate from one page to another simply push or pop a new page onto the stack:

@Component({
  template: `
  <ion-header>
    <ion-navbar>
      <ion-title>Login</ion-title>
    </ion-navbar>
  </ion-header>

  <ion-content>
    <button (click)="goToOtherPage()">
      Go to OtherPage
    </button>
  </ion-content>`
})
export class StartPage {
  constructor(public navCtrl: NavController) {}

  goToOtherPage() {
    //push another page onto the history stack
    //causing the nav controller to animate the new page in
    this.navCtrl.push(OtherPage);
  }
}

@Component({
  template: `
  <ion-header>
    <ion-navbar>
      <ion-title>Other Page</ion-title>
    </ion-navbar>
  </ion-header>

  <ion-content>I'm the other page!</ion-content>`
})
class OtherPage {}

If your page has an <ion-navbar>, a back button will automatically be added to it if it is not a root page, and the title of the Nav Bar will be updated.

Alternatively, if you want to go back, but don’t have a NavBar, you can pop the current page off the stack:

@Component({
  template: `
  <ion-content>
    <button (click)="goBack()">
      There's no place like home
    </button>
  </ion-content>`
})
class OtherPage {
  constructor(public navCtrl: NavController) {}

  goBack() {
    this.navCtrl.pop();
  }
}

For more information on basic navigation, check out the Nav API reference.

What if you want to control navigation from your root app component? You can’t inject NavController because any components that are navigation controllers are children of the root component so they aren’t available to be injected.

By adding a reference variable to the ion-nav, you can use @ViewChild to get an instance of the Nav component, which is a navigation controller (it extends NavController):

@Component({
  template: '<ion-nav #myNav [root]="rootPage"></ion-nav>'
})
export class MyApp {
  @ViewChild('myNav') nav
  rootPage = TabsPage;

  // Wait for the components in MyApp's template to be initialized
  // In this case, we are waiting for the Nav identified by
  // the template reference variable #myNav
  ngAfterViewInit() {
    // Let's navigate from TabsPage to Page1
    this.nav.push(LoginPage);
  }
}

Tabbed Navigation

Navigation can be nested and used inside of complex components like Tabs. Unlike traditional routing systems, Ionic’s navigation makes it easy to navigate to a given Page from anywhere in the app without specifying a specific route to it. To use the App Store app on iOS as an example, we can easily navigate to the AppDetailPage that shows info about a specific app from any tab (try it yourself to see!). Take a look at the Tabs docs for more info on how to easily achieve this.

Popover

Improve this Doc The Popover is a view that floats above an app’s content. Popovers provide an easy way to present or gather information from the user and are commonly used in the following situations:

For more information, Check out the API docs.

Basic Usage

Demo Source

import { PopoverController } from 'ionic-angular';
import { MyPopOverPage } from './my-pop-over';

export class MyPage {
  constructor(public popoverCtrl: PopoverController) {
  }

  presentPopover() {
    let popover = this.popoverCtrl.create(MyPopOverPage);
    popover.present();
  }
}

Radio

Improve this Doc

Like the checkbox, a radio is an input component that holds a boolean value. Under the hood, radios are no different than HTML radio inputs. However, like other Ionic components, radios are styled differently on each platform. Unlike checkboxes, radio components form a group, where only one radio can be selected at a time. Use the checked attribute to set the default value, and the disabled attribute to disable the user from changing to that value.

For more information, Check out the Radio Button API docs and the Radio Group API docs.

Basic Usage

Demo Source

<ion-list radio-group>
  <ion-list-header>
    Language
  </ion-list-header>

  <ion-item>
    <ion-label>Go</ion-label>
    <ion-radio checked="true" value="go"></ion-radio>
  </ion-item>

  <ion-item>
    <ion-label>Rust</ion-label>
    <ion-radio value="rust"></ion-radio>
  </ion-item>

  <ion-item>
    <ion-label>Python</ion-label>
    <ion-radio value="python" disabled="true"></ion-radio>
  </ion-item>
</ion-list>

Range

Improve this Doc

A Range is a control that lets users select from a range of values by moving a slider knob along the slider bar or track.

For more information, Check out the API docs.

Basic Usage

Demo Source

<ion-item>
  <ion-range [(ngModel)]="brightness">
    <ion-icon range-left small name="sunny"></ion-icon>
    <ion-icon range-right name="sunny"></ion-icon>
  </ion-range>
</ion-item>

Improve this Doc

A Searchbar binds to a model, and emits an input event when the model is changed.

For more information, Check out the API docs.

Basic Usage

Demo Source

<ion-searchbar (ionInput)="getItems($event)"></ion-searchbar>
<ion-list>
  <ion-item *ngFor="let item of items">
    {{ item }}
  </ion-item>
</ion-list>

Note that in this example, the getItems() function is called when the input changes, which updates the cities that are displayed. Although this example filters the list based on the search input, Searchbar can be used in many different scenarios:

@Component({
  templateUrl: 'search/template.html',
})
class SearchPage {

  searchQuery: string = '';
  items: string[];

  constructor() {
    this.initializeItems();
  }

  initializeItems() {
    this.items = [
      'Amsterdam',
      'Bogota',
      ...
    ];
  }

  getItems(ev: any) {
    // Reset items back to all of the items
    this.initializeItems();

    // set val to the value of the searchbar
    let val = ev.target.value;

    // if the value is an empty string don't filter the items
    if (val && val.trim() != '') {
      this.items = this.items.filter((item) => {
        return (item.toLowerCase().indexOf(val.toLowerCase()) > -1);
      })
    }
  }
}

Segment

Improve this Doc

Segment is a collection of buttons that are displayed in line. They can act as a filter, showing/hiding elements based on the segments value.

For more information, Check out the API docs.

Basic Usage

Demo Source

<div padding>
  <ion-segment [(ngModel)]="pet">
    <ion-segment-button value="kittens">
      Kittens
    </ion-segment-button>
    <ion-segment-button value="puppies">
      Puppies
    </ion-segment-button>
  </ion-segment>
</div>

<div [ngSwitch]="pet">
  <ion-list *ngSwitchCase="'puppies'">
    <ion-item>
      <ion-thumbnail item-left>
        <img src="img/thumbnail-puppy-1.jpg">
      </ion-thumbnail>
      <h2>Ruby</h2>
    </ion-item>
    ...
  </ion-list>

  <ion-list *ngSwitchCase="'kittens'">
    <ion-item>
      <ion-thumbnail item-left>
        <img src="img/thumbnail-kitten-1.jpg">
      </ion-thumbnail>
      <h2>Luna</h2>
    </ion-item>
    ...
  </ion-list>
</div>

Select

Improve this Doc

Basic Usage

Demo Source

The ion-select component is similar to an HTML <select> element, however, Ionic’s select component makes it easier for users to sort through and select the preferred option. When users tap the select component, a dialog will appear with all of the options in a large, easy to select list.

For more information, Check out the API docs.

<ion-list>
  <ion-item>
    <ion-label>Gaming</ion-label>
    <ion-select [(ngModel)]="gaming">
      <ion-option value="nes">NES</ion-option>
      <ion-option value="n64">Nintendo64</ion-option>
      <ion-option value="ps">PlayStation</ion-option>
      <ion-option value="genesis">Sega Genesis</ion-option>
      <ion-option value="saturn">Sega Saturn</ion-option>
      <ion-option value="snes">SNES</ion-option>
    </ion-select>
  </ion-item>
</ion-list>

multiple selections can be made with <ion-select> by adding multiple="true" to the component.

<ion-list>
  <ion-item>
    <ion-label>Toppings</ion-label>
    <ion-select [(ngModel)]="toppings" multiple="true" cancelText="Nah" okText="Okay!">
      <ion-option value="bacon" checked="true">Bacon</ion-option>
      <ion-option value="olives">Black Olives</ion-option>
      <ion-option value="xcheese" checked="true">Extra Cheese</ion-option>
      <ion-option value="peppers">Green Peppers</ion-option>
      <ion-option value="mushrooms">Mushrooms</ion-option>
      <ion-option value="onions">Onions</ion-option>
      <ion-option value="pepperoni">Pepperoni</ion-option>
      <ion-option value="pineapple">Pineapple</ion-option>
      <ion-option value="sausage">Sausage</ion-option>
      <ion-option value="Spinach">Spinach</ion-option>
    </ion-select>
  </ion-item>
</ion-list>

Slides

Improve this Doc

Slides make it easy to create galleries, tutorials, and page-based layouts. Slides take a number of configuration options on the <ion-slides> component.

For more information, Check out the Slides API docs and the Slide API docs.

Basic Usage

Demo Source

<ion-slides pager>

  <ion-slide style="background-color: green">
    <h2>Slide 1</h2>
  </ion-slide>

  <ion-slide style="background-color: blue">
    <h2>Slide 2</h2>
  </ion-slide>

  <ion-slide style="background-color: red">
    <h2>Slide 3</h2>
  </ion-slide>

</ion-slides>

Tabs

Improve this Doc

Tabs powers a multi-tabbed interface with a Tab Bar and a set of views that can be tabbed through.

For more information, Check out the Tabs API docs and the Tab API docs.

Basic Usage

Demo Source

To initialize Tabs, use <ion-tabs>, with a child <ion-tab> for each tab:

import { Component } from [email protected]/core';
import { ionicBootstrap } from 'ionic-angular';
import { Tab1 } from './tab1-page';
import { Tab2 } from './tab2-page';
@Component({
  template: `
    <ion-tabs>
      <ion-tab tabIcon="heart" [root]="tab1"></ion-tab>
      <ion-tab tabIcon="star" [root]="tab2"></ion-tab>
    </ion-tabs>`
})
class MyApp {

  tab1: any;
  tab2: any;

  constructor() {
    this.tab1 = Tab1;
    this.tab2 = Tab2;
  }
}

Individual tabs are just @Components

import { Component } from [email protected]/core';

@Component({
  template: `
  <ion-header>
    <ion-navbar>
      <ion-title>Heart</ion-title>
    </ion-navbar>
  </ion-header>
  <ion-content>Tab 1</ion-content>`
})
export class Tab1 {}

@Component({
  template: `
  <ion-header>
    <ion-navbar>
      <ion-title>Star</ion-title>
    </ion-navbar>
  </ion-header>
  <ion-content>Tab 2</ion-content>`
})
export class Tab2 {}

Notice that each <ion-tab> binds to a [root] property, just like <ion-nav> in the Navigation section above. That is because each <ion-tab> is really just a navigation controller. This means that each tab has its own history stack, and NavController instances injected into children @Components of each tab will be unique to each tab:

import { Component } from [email protected]/core';
import { NavController } from 'ionic-angular';

@Component({
...
})
class Tab1 {
  constructor(public navCtrl: NavController) {
    // Id is 1, nav refers to Tab1
    console.log(this.nav.id)
  }
}

@Component({
...
})
class Tab2 {
  constructor(public navCtrl: NavController) {
    // Id is 2, nav refers to Tab2
    console.log(this.nav.id)
  }
}

Icon Tabs

Demo Source

To add an icon inside of a tab, use the tab-icon attribute. This attribute can be passed the name of any icon:

@Component({
  template: `
  <ion-header>
    <ion-navbar>
      <ion-title>Tabs</ion-title>
    </ion-navbar>
  </ion-header>
  <ion-content></ion-content>
  `
})
class TabContentPage {
  constructor() {}
}

@Component({
  template: `
  <ion-tabs>
    <ion-tab tabIcon="contact" [root]="tab1"></ion-tab>
    <ion-tab tabIcon="compass" [root]="tab2"></ion-tab>
    <ion-tab tabIcon="analytics" [root]="tab3"></ion-tab>
    <ion-tab tabIcon="settings" [root]="tab4"></ion-tab>
  </ion-tabs>`
})
export class TabsIconPage {
  constructor() {
    this.tab1 = TabContentPage;
    this.tab2 = TabContentPage;
    ...
  }
}

Icon and Text

Demo Source

To add text and an icon inside of a tab, use the tab-icon and tab-title attributes:

@Component({
  template: `
  <ion-header>
    <ion-navbar>
      <ion-title>Tabs</ion-title>
    </ion-navbar>
  </ion-header>
  <ion-content></ion-content>
  `
})
class TabsTextContentPage {
  constructor() {}
}

@Component({
  template: `
  <ion-tabs>
    <ion-tab tabIcon="water" tabTitle="Water" [root]="tab1"></ion-tab>
    <ion-tab tabIcon="leaf" tabTitle="Life" [root]="tab2"></ion-tab>
    <ion-tab tabIcon="flame" tabTitle="Fire" [root]="tab3"></ion-tab>
    <ion-tab tabIcon="magnet" tabTitle="Force" [root]="tab4"></ion-tab>
  </ion-tabs>`
})
export class TabsTextPage {
  constructor() {
    this.tab1 = TabsTextContentPage;
    this.tab2 = TabsTextContentPage;
    ...
  }
}

Badges

Demo Source

To add a badge to a tab, use the tabBadge and tabBadgeStyle attributes. The tabBadgeStyle attribute can be passed the name of any color:

@Component({
  template: `
  <ion-header>
    <ion-navbar>
      <ion-title>Tabs</ion-title>
    </ion-navbar>
  </ion-header>
  <ion-content></ion-content>
  `
})
class TabBadgePage {
  constructor() {}
}

@Component({
  template: `
    <ion-tabs>
      <ion-tab tabIcon="call" [root]="tabOne" tabBadge="3" tabBadgeStyle="danger"></ion-tab>
      <ion-tab tabIcon="chatbubbles" [root]="tabTwo" tabBadge="14" tabBadgeStyle="danger"></ion-tab>
      <ion-tab tabIcon="musical-notes" [root]="tabThree"></ion-tab>
    </ion-tabs>
    `
})
export class BadgesPage {
  constructor() {
    this.tabOne = TabBadgePage;
    this.tabTwo = TabBadgePage;
  }
}

For more information on tabs, check out the Tabs API reference.

Toast

Improve this Doc

Toast is a subtle notification that appears on top of an app’s content. Typically, Toasts are displayed for a short duration of time than automatically dismiss.

For more information, Check out the API docs.

Basic Usage

Demo Source

import { ToastController } from 'ionic-angular';

export class MyPage {
  constructor(public toastCtrl: ToastController) {
  }

  presentToast() {
    let toast = this.toastCtrl.create({
      message: 'User was added successfully',
      duration: 3000
    });
    toast.present();
  }
}

Toggle

Improve this Doc

A toggle is an input component that holds a boolean value. Like the checkbox, toggles are often used to allow the user to switch a setting on or off. Attributes like value, disabled, and checked can be applied to the toggle to control its behavior.

For more information, Check out the API docs.

Basic Usage

Demo Source

<ion-item>
  <ion-label> Sam</ion-label>
  <ion-toggle disabled checked="false"></ion-toggle>
</ion-item>

Toolbar

Improve this Doc

A toolbar is a generic bar that can be used in an app as a header, sub-header, footer, or even sub-footer. Since ion-toolbar is based on flexbox, no matter how many toolbars you have in your page, they will be displayed correctly and ion-content will adjust accordingly.

Note: Typically a NavBar is used inside the ion-header when used in conjunction with navigation.

For more information, Check out the API docs.

Basic Usage

Demo Source

To use a toolbar as a footer you can use ion-footer instead of ion-toolbar.

<ion-header>
  <ion-toolbar>
    <ion-title>Toolbar</ion-title>
  </ion-toolbar>
</ion-header>

<ion-content></ion-content>

<ion-footer>
  <ion-footer>
    <ion-title>Footer</ion-title>
  </ion-footer>
</ion-footer>

Header

One of the best uses of the toolbar is as a header.

<ion-header>
  <ion-toolbar primary>
    <ion-buttons start>
      <ion-icon name="content"></ion-icon>
    </ion-buttons>

    <ion-title>Header</ion-title>

    <ion-buttons end>
      <ion-icon name="search"></ion-icon>
    </ion-buttons>

  </ion-toolbar>
</ion-header>

<ion-content>
  <p>There is a header above me!</p>
</ion-content>

Changing the Color

You can change the toolbars color by changing the property on the element.


@Component({
  template: `
    <ion-toolbar primary>
      <ion-title>Toolbar</ion-title>
    </ion-toolbar>


    <ion-toolbar secondary>
      <ion-title>Toolbar</ion-title>
    </ion-toolbar>

    <ion-toolbar danger>
      <ion-title>Toolbar</ion-title>
    </ion-toolbar>


    <ion-toolbar dark>
      <ion-title>Toolbar</ion-title>
    </ion-toolbar>
  `
  })

You can also change the navbar’s color the same way. This will allow you to have a different color navbar per page in your app.

<ion-header>
  <ion-navbar dark>
    <ion-title>Dark</ion-title>
  </ion-navbar>
</ion-header>


<ion-header>
  <ion-navbar danger>
    <ion-title>Danger</ion-title>
  </ion-navbar>
</ion-header>

<ion-header>
  <ion-navbar secondary>
    <ion-title>Secondary</ion-title>
  </ion-navbar>
</ion-header>

Buttons in Toolbars

Improve this Doc

Buttons can be added to both header and footer toolbars. To add a button to a toolbar, we need to first add an ion-buttons component. This component wraps one or more buttons, and can be given the start or end attributes to control the placement of the buttons it contains:

<ion-header>
  <ion-toolbar>
    <ion-buttons start>
      <button royal>
        <ion-icon name="search"></ion-icon>
      </button>
    </ion-buttons>
    <ion-title>Send To...</ion-title>
    <ion-buttons end>
      <button royal>
        <ion-icon name="person-add"></ion-icon>
      </button>
    </ion-buttons>
  </ion-toolbar>
</ion-header>

<ion-content></ion-content>

<ion-footer>
  <ion-toolbar>
    <p>Ash, Misty, Brock</p>
    <ion-buttons end>
      <button royal>
        Send
        <ion-icon name="send"></ion-icon>
      </button>
    </ion-buttons>
  </ion-toolbar>
</ion-footer>

Segment in Toolbars

Improve this Doc

Segments are a great way to allow users to switch between different sets of data. Use the following markup to add a segment to a toolbar:

<ion-header>
  <ion-toolbar>
    <ion-buttons start>
      <button>
        <ion-icon name="create"></ion-icon>
      </button>
    </ion-buttons>
    <ion-segment>
      <ion-segment-button value="new">
        New
      </ion-segment-button>
      <ion-segment-button value="hot">
        Hot
      </ion-segment-button>
    </ion-segment>
    <ion-buttons end>
      <button>
        <ion-icon name="more"></ion-icon>
      </button>
    </ion-buttons>
  </ion-toolbar>
</ion-header>

Another common design paradigm is to include a searchbar inside your toolbar.

<ion-header>
  <ion-toolbar primary>
    <ion-searchbar (input)="getItems($event)"></ion-searchbar>
  </ion-toolbar>
</ion-header>

<ion-content>
  <ion-list>
    <ion-item *ngFor="let item of items">
      {{ item }}
    </ion-item>
  </ion-list>
</ion-content>

API

Native

General