Confused about ion-item usage

Ionic Framework ionic-v3
10

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>
  </div>
  <ng-content select="[item-right],ion-radio,ion-toggle"></ng-content>
</div>

Source: https://github.com/driftyco/ionic/blob/2.0/src/components/item/item.ts#L44-L55

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:

https://github.com/driftyco/ionic/blob/2.0/src/components/checkbox/test/basic/main.html#L67

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

<ion-item>
  Plain text
</ion-item>

image

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="http://pngimg.com/upload/dog_png2402.png">
  </ion-thumbnail>
  <ion-label>Complex item</ion-label>
  <ion-icon name="close-circle" item-right></ion-icon>
  <ion-checkbox item-right></ion-checkbox>
</button>

image

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: https://github.com/driftyco/ionic-site/issues

And if you run into issues with the way the Item works please report them here so we can resolve them: https://github.com/driftyco/ionic/issues

Thanks so much! :slight_smile:

15 Likes