Confused about ion-item usage


Confused with using ​ion-item. Can anyone please kindly answer below questions on ​ion-item

  1. Can it be used outside of ​ion-list
  2. Can we nest ​ion-list​, ion-item or ​ion-grid​ inside ​ion-item
  3. How the elements inside ​ion-item​ will be aligned (all horizontal, vertical etc)
  4. Is it possible to change the alignment of child elements from horizontal to vertical etc.
  5. When to use it and when not to use it

Posted this in slack but no luck, so posting it again here. Really appreciate your response.


If you take a look at the documentation:

You’ll see that ion-item is a child of ion-list. Also you can put anything you want into a ion-item from what we can see in the documentation here:

Hope this helps!


@skoff, thank you for the reply. Those links are pointing to ionic 1.x, tried putting ion-list and ​ion-grid​ inside ion-item and they are not rendering properly. Sometimes nothing appear, sometimes empty list appear etc. No console errors either. Here is an issue linked to this placing ion-grid inside ion-item


sorry for the wrong links…

Here’s the right documentation links maybe it will help you figure this out:

Also @vijquick from what I can see in the doc concerning ion-grid it doesn’t look like it needs to be inside a ion-list. So you could try that also.


@skoff, thanks for the reply. I have extensively gone through ionic 2 docs already, I am really looking forward to here answers for the above questions. Can someone from ionic team please clarify the above questions. Really appreciate your time.


UPDATE: Check the much more informative answer by @brandyshea instead.

Take a look at the following example from the Ionic docs, it shows pretty clear how to use it:


IMHO you’re asking the wrong questions. Instead you should focus on what you’re trying to achieve and ask concretely how to achieve it. I’ll try to answer them though, but have in mind that this is my personal opinion and not a general advice:

  1. No, but even if possible I wouldn’t recommend you, unless you see it in the docs.
  2. No, probably possible with custom hacks, but not recommended, unless it’s in the docs.
  3. I guess that it’s possible to customize it with CSS.
  4. I guess that it’s possible to customize it with CSS.
  5. Use it only inside <ion-list>, unless you see something else in the docs.

In short: if it’s in the docs it’s supported, otherwise it’s most probably not (and even if you manage to hack it somehow it’s most probably a bad idea). From your questions I guess that you’re maybe looking for some kind of a universal container - then consider using <div>. And keep in mind that the Ionic apps are not restricted only to Ionic components - you can use HTML elements as well, and also CSS…


Hello @iignatov

Thank you for the reply. I agree that it might not be a concrete question.

The root cause of all my confusions actually is the documentation itself. Please take a look at the below links to understand, why I say so. In all the example source code found on ionic framework documentation itself is actually using ion-item in many places outside of ion-list. As a beginner I tend to follow what is shown in documentation and extend it with my use cases.

ion-badge sample code
ion-card sample code

The above list goes on, there are actually tons of examples in documentation that use ion-item in different scenarios. By looking at all those usages I started using ion-item to satisfy my use cases. There is no where specified in documentation how it should be using and what it supports and what it doesn’t support. It simply works sometimes and doesn’t work other times. This is not something that I would expect from such an awesome framework. Please kindly update the documentation with clear guidelines on how ion-item should be used. Looking forward to hear from you.



I don’t like ion-item component, it’s very not flexible.

First: ion-item has wrong name, ion-item is like poor md-input-container. You must use it for inputs/select/etc with labels.
Second: You not must use ion-item in ion-list, because you must use it for inputs in forms too, but your forms are not list usually :slight_smile:
Third: You can use ONLY ONE ion-input, ion-label and some another ionic components into ion-item, all another HTML will be ignored.

So this component is very poor and very usability. I hope, Ionic Team will fix it.
PS Sorry about my terrible English, but I think you can understand that I mean.

@mhartington @brandyshea FYI


I’ll try to address these concerns as best as I can…

Both of these are not true. ionItem can accept any html in it. Take a look at the component docs for lists and items.

ionItem also provides enough flexibility with it’s layout to create thumbnails, avatars, and buttons/notes on the left or right side.

It’s a low level component that is used to build more complex component.


I am currently in the process of improving the Item API docs to include more descriptions and examples. I will make sure to include some documentation to clear this up.

  1. An ion-item can be used outside of an ion-list if you do not plan on using gestures with it. Therefore, if you are using sliding items you do need an ion-list.
  2. You cannot currently nest an ion-list inside of an ion-item but you can place an ion-grid in an ion-item.
  3. The elements are aligned horizontal, except in the case of stacked/floating inputs where the label is on top of the input.
  4. You can change the alignment by adding flex-flow: column; to the .item class.
  5. Items use content projection, which basically means the item component is looking for specific elements/attributes and placing them that way. Here is what the component template for item looks like (with some parts removed):
<ng-content select="[item-left],ion-checkbox:not([item-right])"></ng-content>
<div class="item-inner">
  <div class="input-wrapper">
    <ng-content select="ion-label"></ng-content>
    <ng-content select="ion-select,ion-input,ion-textarea,ion-datetime,ion-range,[item-content]"></ng-content>
  <ng-content select="[item-right],ion-radio,ion-toggle"></ng-content>


The first ng-content looks for elements with the item-left attribute and ion-checkbox elements and if it finds either it places it there. The second ng-content only grabs ion-label elements and so on.

The item-content attribute can be added to any element to be placed inside the item.

So an item is a complex component that should be used for positioning components: radios, selects, checkboxes, ranges, etc. It is best used in a list or a card because it is styled to look the best in these scenarios, but you can always override the styles to your particular use case. Many of these components do not need to be in an ion-item to work though, we try to include examples of these in our component tests:

It can be as basic as one line of text (note that this isn’t in an ion-list):

  Plain text

and as complex as a button with the ion-item attribute with a label, thumbnail, icon, and checkbox (this is also not in an ion-list):

<button ion-item>
  <ion-thumbnail item-left>
    <img src="">
  <ion-label>Complex item</ion-label>
  <ion-icon name="close-circle" item-right></ion-icon>
  <ion-checkbox item-right></ion-checkbox>

If you have any ideas for ways we can improve the documentation please create an issue on the ionic-site repo and we will work on updating the docs:

And if you run into issues with the way the Item works please report them here so we can resolve them:

Thanks so much! :slight_smile:

[SOLVED] Ion-item question and "weird" android css

I understand and agree with you that there are some missing things in the docs but there’s something much better - the source code. You should also consider that the framework is still in beta and the documentation is a work in progress. Moreover there’s a link Improve this doc on every page, so if you find something missing or incorrect you could suggest a correction or open an issue - that’s the great in open source.

I would like to add something important - an awesome free open source framework. If you used any other open source projects before you probably know that there’s usually a lot of community involvement. And from my own experience with the Ionic framework I could say that it’s the most awesome open source project I’ve ever used.

The the <ion-item> docs are already updated thanks to this amazing commit.


Hello @brandyshea

Thank you for much detailed information on ion-item. You made my day. Really appreciate your time and efforts went into clearing up my questions and ion-item in general. Will go through it thoroughly and test it with my use cases. Here is one quick question though[quote=“brandyshea, post:10, topic:54116”]
You cannot currently nest an ion-list inside of an ion-item but you can place an ion-grid in an ion-item.

Here is a separate post on placing ion-grid inside ion-item. Not sure what I am doing wrong here, but couldn’t get it running. One thing to mention is I am repeating ion-item inside ion-list and ion-grid is inside the repeated ion-item

Once again thank you for all the detailed documentation. You are the star.



I still confused. I tried use the div elements inside the ion-item and there were ignored. And we can see in @brandyshea answer that ng-content selects elements: ion-select,ion-input,ion-textarea,ion-datetime,ion-range,[item-content]. So another elements will be ignored, will not it? I also tried put 2 ion-input elements in ion-item and it didn’t work.

@brandyshea So if we use it outside of a list than it isn’t an item already )

@mhartington, @brandyshea Thank you very much.


This was fixed in beta.8 with the addition of item-content. Now it’s possible to include HTML elements and custom components inside <ion-item>. So the following should work (make sure that you’re using beta.8):

    <div item-content>Test</div>


:slight_smile: So this is actually because of the use of ion-label, not the grid itself. I believe this is an issue with content projection actually, since it wants to grab the nested ion-label but it isn’t able to place it correctly. I found this Angular issue on it:

Could you create an issue on our repository so we can discuss this more internally?

As a work around, you could use div's instead of ion-labels:

<ion-item class="my-item">
         <ion-icon name="pie" item-left></ion-icon>
         <div>Label 1</div>
         <div>Label 2</div>
         <div>Label 3</div>
           <ion-icon name="calendar"></ion-icon>
           Label 4

and then add any styling to the divs:

.my-item div {
  margin: 8px;


The item will look for an <ion-label> element and if it exists it will ignore other elements, but those can be added by using the item-content attribute. So this will work:

  <div>My Div</div>

but this will ignore the div and only show the label:

  <ion-label>My Label</ion-label>
  <div>My Div</div>

However, this will add the div because of the item-content:

  <ion-label>My Label</ion-label>
  <div item-content>My Div</div>

The element going in the item needs to have one of those attributes on it if it is being added in an item that already has an ion-label. I agree that this is confusing though, so I created an issue for us to discuss this more:

For the issue with the input, can you show me the code you used? I tried using the following:

  <ion-input type="text" value="hi"></ion-input>
  <ion-input type="number" value="44"></ion-input>

  <ion-label floating>Floating Label</ion-label>
  <ion-input type="text" value="hi"></ion-input>
  <ion-input type="number" value="44"></ion-input>

  <ion-label fixed>Fixed Label</ion-label>
  <ion-input type="text" value="hi"></ion-input>
  <ion-input type="number" value="44"></ion-input>

And these are all working for me. The ng-content selects these elements to place them there but there can be multiple of the same elements placed there. For example, you can have 3 elements with the item-right attribute and they will all be placed on the right:

  <ion-icon item-right name="sunny"></ion-icon>
  <ion-icon item-right name="cloudy"></ion-icon>
  <ion-icon item-right name="rainy"></ion-icon>

Sorry, but I don’t understand this question. Could you explain more? Thanks! :slight_smile:


Clear answer, thanks.
I don’t remember what I tried do with 2 ion-inputs. However I am happy that ion-item is more flexible now :slight_smile:

Have a nice day.


Thanks for the reply. Replacing ion-label with div worked like a magic. Like you suggested, I have created an issue in GitHub repo of ionic.


I want to put two input in a row as code above, but labels and inputs not showed as expect. Can you help me?:head_bandage:



What is the reason to hide/discard other components after ion-label by default unless for example you add the ion-content attribute?
Would it be more flexible to allow any nesting/composition as desired leaving some responsibility/power to the developer using the framework?
Maybe is it an Angular2 limitation?