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. 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

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.

Alerts

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​.

Basic Usage

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.

Confirmation Alerts

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.

Buttons

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 accessibility reasons, buttons use a standard <button> element, but are enhanced with an ion-button directive.

Full Buttons

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.

Cards

Cards are a great way to display important pieces of content, and are quickly emerging as a core design pattern for apps. They 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.

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>

Images In Cards

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><imgsrc="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

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.

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

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-avataritem-start><imgsrc="img/marty-avatar.png"></ion-avatar><h2>Marty McFly</h2><p>November 5, 1955</p></ion-item><imgsrc="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><buttonion-buttonicon-leftclearsmall><ion-iconname="thumbs-up"></ion-icon><div>12 Likes</div></button></ion-col><ion-col><buttonion-buttonicon-leftclearsmall><ion-iconname="text"></ion-icon><div>4 Comments</div></button></ion-col><ion-colcentertext-center><ion-note>
11h ago
</ion-note></ion-col></ion-row></ion-card>

Checkbox

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.

DateTime

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.

Basic Usage

FABs

FABs (Floating Action Buttons) are standard material design components. They are shaped as a circle that represents a promoted action. When pressed, it may contain more related actions. FABs as its name suggests are floating over the content in a fixed position.

Basic Usage

<ion-content><!-- Real floating action button, fixed. It will not scroll with the content --><ion-fabtoprightedge><buttonion-fabmini><ion-iconname="add"></ion-icon></button><ion-fab-list><buttonion-fab><ion-iconname="logo-facebook"></ion-icon></button><buttonion-fab><ion-iconname="logo-twitter"></ion-icon></button><buttonion-fab><ion-iconname="logo-vimeo"></ion-icon></button><buttonion-fab><ion-iconname="logo-googleplus"></ion-icon></button></ion-fab-list></ion-fab><ion-fabrightbottom><buttonion-fabcolor="light"><ion-iconname="arrow-dropleft"></ion-icon></button><ion-fab-listside="left"><buttonion-fab><ion-iconname="logo-facebook"></ion-icon></button><buttonion-fab><ion-iconname="logo-twitter"></ion-icon></button><buttonion-fab><ion-iconname="logo-vimeo"></ion-icon></button><buttonion-fab><ion-iconname="logo-googleplus"></ion-icon></button></ion-fab-list></ion-fab></ion-content>

<ion-grid><ion-row><ion-colcol-12>This column will take 12 columns</ion-col></ion-row><ion-row><ion-colcol-6>This column will take 6 columns</ion-col></ion-row></ion-grid>

An ion-col can be sized for different breakpoints by setting the col-<breakpoint>-<width>.

<ion-grid><ion-row><ion-colcol-12col-sm-9col-md-6col-lg-4col-xl-3>
This column will be 12 columns wide by default,
9 columns at the small breakpoint,
6 at the medium breakpoint, 4 at large, and 3 at xl.
</ion-col></ion-row></ion-grid>

Icons

Basic Usage

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

<ion-iconname="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.

Variable Icons

Inputs

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.

Fixed Inline Labels

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.

Icon List

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.

Avatar List

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-avataritem-start><imgsrc="img/avatar-cher.png"></ion-avatar><h2>Cher</h2><p>Ugh. As if.</p></ion-item></ion-list>

Multi-line List

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-avataritem-start><imgsrc="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

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.

Thumbnail List

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:

Loading

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.

Navigation

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.

Basic Navigation

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>'})classMyApp{// First page to push onto the stackrootPage=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 .

Navigating from the Root Component

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>'})exportclassMyApp{@ViewChild('myNav')navrootPage=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 #myNavngAfterViewInit(){// Let's navigate from TabsPage to Page1this.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:

Radio

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.

Basic Usage

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',})classSearchPage{searchQuery:string='';items:string[];constructor(){this.initializeItems();}initializeItems(){this.items=['Amsterdam','Bogota',...];}getItems(ev:any){// Reset items back to all of the itemsthis.initializeItems();// set val to the value of the searchbarletval=ev.target.value;// if the value is an empty string don't filter the itemsif(val&&val.trim()!=''){this.items=this.items.filter((item)=>{return(item.toLowerCase().indexOf(val.toLowerCase())>-1);})}}}

Select

Basic Usage

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.

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:

Toggle

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.

Basic Usage

Toolbar

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.

Header

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

<ion-header><ion-toolbarcolor="primary"><ion-buttonsstart><buttonion-buttonicon-only><ion-iconname="more"></ion-icon></button></ion-buttons><ion-title>Header</ion-title><ion-buttonsend><buttonion-buttonicon-only><ion-iconname="search"></ion-icon></button></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.

Buttons in Toolbars

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: