ion-item

shadow

Items are elements that can contain text, icons, avatars, images, inputs, and any other native or custom elements. Generally they are placed in a list with other items. Items can be swiped, deleted, reordered, edited, and more.

Basic Usage

Items left align text and add an ellipsis when the text is wider than the item. We can modify this behavior using the CSS Utilities provided by Ionic Framework, such as using .ion-text-wrap in the below example. See the CSS Utilities Documentation for more classes that can be added to an item to transform the text.

<ion-item>
  <ion-label>Basic Item</ion-label>
</ion-item>

<ion-item>
  <ion-label>
    Multi-line text that should ellipsis when it is too long to fit on one line. Lorem ipsum dolor sit amet, consectetur
    adipiscing elit.
  </ion-label>
</ion-item>

<ion-item>
  <ion-label class="ion-text-wrap">
    Multi-line text that should wrap when it is too long to fit on one line. Lorem ipsum dolor sit amet, consectetur
    adipiscing elit.
  </ion-label>
</ion-item>

<ion-item>
  <ion-label>
    <h1>H1 Heading</h1>
    <p>Paragraph</p>
  </ion-label>
</ion-item>

<ion-item>
  <ion-label>
    <h2>H2 Heading</h2>
    <p>Paragraph</p>
  </ion-label>
</ion-item>

<ion-item>
  <ion-label>
    <h3>H3 Heading</h3>
    <p>Paragraph</p>
  </ion-label>
</ion-item>

Clickable Items

An item is considered "clickable" if it has an href or button property set. Clickable items have a few visual differences that indicate they can be interacted with. For example, a clickable item receives the ripple effect upon activation in md mode, has a highlight when activated in ios mode, and has a detail arrow by default in ios mode.

<ion-item href="#">
  <ion-label>Anchor Item</ion-label>
</ion-item>

<ion-item href="#" disabled="true">
  <ion-label>Disabled Anchor Item</ion-label>
</ion-item>

<ion-item button>
  <ion-label>Button Item</ion-label>
</ion-item>

<ion-item button disabled="true">
  <ion-label>Disabled Button Item</ion-label>
</ion-item>

Detail Arrows

By default clickable items will display a right arrow icon on ios mode. To hide the right arrow icon on clickable elements, set the detail property to false. To show the right arrow icon on an item that doesn't display it naturally, set the detail property to true.

<ion-item detail="true">
  <ion-label>
    <h3>Text Item</h3>
    <p>Detail set to true - detail arrow displays on both modes</p>
  </ion-label>
</ion-item>

<ion-item button>
  <ion-label>
    <h3>Button Item</h3>
    <p>Default detail - detail arrow displays on iOS only</p>
  </ion-label>
</ion-item>

<ion-item button detail="true">
  <ion-label>
    <h3>Button Item</h3>
    <p>Detail set to true - detail arrow displays on both modes</p>
  </ion-label>
</ion-item>

<ion-item button detail="false">
  <ion-label>
    <h3>Button Item</h3>
    <p>Detail set to false - detail arrow hidden on both modes</p>
  </ion-label>
</ion-item>

<ion-item button detail="true" detail-icon="caret-forward-outline">
  <ion-label>
    <h3>Button Item</h3>
    <p>Detail set to true - detail arrow displays on both modes</p>
    <p>Detail icon set to caret-forward-outline</p>
  </ion-label>
</ion-item>

Item Lines

Items show an inset bottom border by default. The border has padding on the left and does not appear under any content that is slotted in the "start" slot. The lines property can be modified to "full" or "none" which will show a full width border or no border, respectively.

<ion-item>
  <ion-label> Default Item Lines </ion-label>
</ion-item>

<ion-item lines="inset">
  <ion-label>Item Lines Inset</ion-label>
</ion-item>

<ion-item lines="full">
  <ion-label>Item Lines Full</ion-label>
</ion-item>

<ion-item lines="none">
  <ion-label>Item Lines None</ion-label>
</ion-item>

<ion-item>
  <ion-icon name="star" slot="start"></ion-icon>
  <ion-label>Default Item Lines</ion-label>
  <ion-icon name="information-circle" slot="end"></ion-icon>
</ion-item>

<ion-item lines="inset">
  <ion-icon name="star" slot="start"></ion-icon>
  <ion-label>Item Lines Inset</ion-label>
  <ion-icon name="information-circle" slot="end"></ion-icon>
</ion-item>

<ion-item lines="full">
  <ion-icon name="star" slot="start"></ion-icon>
  <ion-label>Item Lines Full</ion-label>
  <ion-icon name="information-circle" slot="end"></ion-icon>
</ion-item>

<ion-item lines="none">
  <ion-icon name="star" slot="start"></ion-icon>
  <ion-label>Item Lines None</ion-label>
  <ion-icon name="information-circle" slot="end"></ion-icon>
</ion-item>

Media Items

Avatars and Thumbnails can be slotted inside of an item. This is useful when making lists of images and text.

<ion-item>
  <ion-avatar slot="start">
    <img alt="Silhouette of a person's head" src="https://ionicframework.com/docs/img/demos/avatar.svg" />
  </ion-avatar>
  <ion-label> Avatar Item </ion-label>
</ion-item>

<ion-item>
  <ion-thumbnail slot="start">
    <img alt="Silhouette of mountains" src="https://ionicframework.com/docs/img/demos/thumbnail.svg" />
  </ion-thumbnail>
  <ion-label> Thumbnail Item </ion-label>
</ion-item>

Buttons in Items

Buttons are styled smaller inside of items than when they are outside of them. To make the button size match buttons outside of an item, set the size attribute to "default".

<ion-item>
  <ion-button slot="start"> Start </ion-button>
  <ion-label>Default Buttons</ion-label>
  <ion-button slot="end"> End </ion-button>
</ion-item>

<ion-item>
  <ion-button slot="start">
    Start
    <ion-icon name="home" slot="end"></ion-icon>
  </ion-button>
  <ion-label>Buttons with Icons</ion-label>
  <ion-button slot="end">
    <ion-icon name="star" slot="end"></ion-icon>
    End
  </ion-button>
</ion-item>

<ion-item>
  <ion-button slot="start">
    <ion-icon slot="icon-only" name="navigate"></ion-icon>
  </ion-button>
  <ion-label>Icon only Buttons</ion-label>
  <ion-button slot="end">
    <ion-icon slot="icon-only" name="star"></ion-icon>
  </ion-button>
</ion-item>

<ion-item>
  <ion-label>Button Sizes</ion-label>
  <ion-button slot="end" size="small"> Small </ion-button>
  <ion-button slot="end" size="default"> Default </ion-button>
  <ion-button slot="end" size="large"> Large </ion-button>
</ion-item>

Icons in Items

<ion-item>
  <ion-label> Default Icon </ion-label>
  <ion-icon name="information-circle" slot="end"></ion-icon>
</ion-item>

<ion-item>
  <ion-label> Large Icon </ion-label>
  <ion-icon name="information-circle" size="large" slot="end"></ion-icon>
</ion-item>

<ion-item>
  <ion-label> Small Icon </ion-label>
  <ion-icon name="information-circle" size="small" slot="end"></ion-icon>
</ion-item>

<ion-item>
  <ion-icon name="star" slot="start"></ion-icon>
  <ion-label> Default Icon </ion-label>
</ion-item>

Item Inputs

<ion-item>
  <ion-label>Default Input</ion-label>
  <ion-input placeholder="Enter text"></ion-input>
</ion-item>

<ion-item>
  <ion-label position="fixed">Fixed Input</ion-label>
  <ion-input placeholder="Enter text"></ion-input>
</ion-item>

<ion-item>
  <ion-label position="stacked">Stacked Input</ion-label>
  <ion-input placeholder="Enter text"></ion-input>
</ion-item>

<ion-item>
  <ion-label position="floating">Floating Input</ion-label>
  <ion-input placeholder="Enter text"></ion-input>
</ion-item>

<ion-item fill="outline">
  <ion-label position="floating">Floating Input: Outline (MD only)</ion-label>
  <ion-input placeholder="Enter text"></ion-input>
</ion-item>

<ion-item fill="solid">
  <ion-label position="floating">Floating Input: Solid (MD only)</ion-label>
  <ion-input placeholder="Enter text"></ion-input>
</ion-item>

<ion-item>
  <ion-label>Select</ion-label>
  <ion-select placeholder="Make a Selection">
    <ion-select-option value="">No Game Console</ion-select-option>
    <ion-select-option value="nes">NES</ion-select-option>
    <ion-select-option value="n64">Nintendo64</ion-select-option>
    <ion-select-option value="ps">PlayStation</ion-select-option>
    <ion-select-option value="genesis">Sega Genesis</ion-select-option>
    <ion-select-option value="saturn">Sega Saturn</ion-select-option>
    <ion-select-option value="snes">SNES</ion-select-option>
  </ion-select>
</ion-item>

<ion-item>
  <ion-label>Toggle</ion-label>
  <ion-toggle slot="end"></ion-toggle>
</ion-item>

<ion-item>
  <ion-label>Checkbox</ion-label>
  <ion-checkbox slot="end"></ion-checkbox>
</ion-item>

<ion-item>
  <ion-label position="stacked">Range</ion-label>
  <ion-range></ion-range>
</ion-item>

Helper & Error Text

Helper & error text can be used inside of an item with an input by slotting a note in the "helper" and "error" slots. The error slot will not be displayed unless the ion-invalid class is added to the ion-item. In Angular, this is done automatically through form validation. In JavaScript, React and Vue, the class needs to be manually added based on your own validation.

<ion-item fill="solid">
  <ion-label position="floating">Email</ion-label>
  <ion-input type="email" ngModel email></ion-input>
  <ion-note slot="helper">Enter a valid email</ion-note>
  <ion-note slot="error">Invalid email</ion-note>
</ion-item>

Item Counter

The item counter is helper text that displays under an input to notify the user of how many characters have been entered out of the total that the input will accept. When adding counter, the default behavior is to format the value that gets displayed as inputLength / maxLength. This behavior can be customized by passing in a formatter function to the counterFormatter property.

src/app/example.component.html

<ion-item counter="true">
  <ion-label position="floating">Default Counter</ion-label>
  <ion-input maxlength="20"></ion-input>
</ion-item>

<ion-item id="custom-item" counter="true" [counterFormatter]="customCounterFormatter">
  <ion-label position="floating">Custom Counter Format</ion-label>
  <ion-input maxlength="20"></ion-input>
</ion-item>

src/app/example.component.ts

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
})
export class ExampleComponent {
  customCounterFormatter(inputLength: number, maxLength: number) {
    return `${maxLength - inputLength} characters remaining`;
  }
}

Theming

Colors

<ion-item>
  <ion-label>Default Item</ion-label>
</ion-item>
<ion-item color="primary">
  <ion-label>Primary Item</ion-label>
</ion-item>
<ion-item color="secondary">
  <ion-label>Secondary Item</ion-label>
</ion-item>
<ion-item color="tertiary">
  <ion-label>Tertiary Item</ion-label>
</ion-item>
<ion-item color="success">
  <ion-label>Success Item</ion-label>
</ion-item>
<ion-item color="warning">
  <ion-label>Warning Item</ion-label>
</ion-item>
<ion-item color="danger">
  <ion-label>Danger Item</ion-label>
</ion-item>
<ion-item color="light">
  <ion-label>Light Item</ion-label>
</ion-item>
<ion-item color="medium">
  <ion-label>Medium Item</ion-label>
</ion-item>
<ion-item color="dark">
  <ion-label>Dark Item</ion-label>
</ion-item>

CSS Shadow Parts

src/app/example.component.css

ion-item::part(native) {
  background: #19422d;
  color: #fff;

  border-color: #fff;
  border-style: dashed;
  border-width: 2px;

  border-radius: 20px;
}

ion-item::part(detail-icon) {
  color: white;
  opacity: 1;
  font-size: 20px;
}

src/app/example.component.html

<ion-item button detail lines="full">
  <ion-label>Custom Item</ion-label>
</ion-item>

<ion-item button detail lines="full">
  <ion-label>Custom Item</ion-label>
</ion-item>

<ion-item button detail lines="full">
  <ion-label>Custom Item</ion-label>
</ion-item>

CSS Custom Properties

src/app/example.component.css

ion-item {
  --background: #19422d;
  --color: #fff;

  --border-color: #fff;
  --border-style: dashed;
  --border-width: 2px;

  --border-radius: 20px;

  --ripple-color: purple;

  --detail-icon-color: white;
  --detail-icon-opacity: 1;
  --detail-icon-font-size: 20px;
}

src/app/example.component.html

<ion-item button detail lines="full">
  <ion-label>Custom Item</ion-label>
</ion-item>

<ion-item button detail lines="full">
  <ion-label>Custom Item</ion-label>
</ion-item>

<ion-item button detail lines="full">
  <ion-label>Custom Item</ion-label>
</ion-item>

Input Highlight

Items containing an input will highlight the bottom border of the input with a different color when focused, valid, or invalid. By default, md items have a highlight with a height set to 2px and ios has no highlight (technically the height is set to 0). The height can be changed using the --highlight-height CSS property. To turn off the highlight, set this variable to 0.

The highlight color changes based on the item state, but all of the states use Ionic colors by default. When focused, the input highlight will use the primary color. If the input is valid it will use the success color, and invalid inputs will use the danger color. This can be customized using the provided CSS properties.

src/app/example.component.css

ion-item {
  --highlight-height: 2px;
  --highlight-color-focused: #43e7f3;
  --highlight-color-valid: #6f58d8;
  --highlight-color-invalid: #ff46be;
}

src/app/example.component.html

<ion-item lines="full" class="item-has-focus ion-touched">
  <ion-label position="stacked">Custom Input Highlight: Focused</ion-label>
  <ion-input></ion-input>
</ion-item>

<ion-item lines="full" class="item-has-focus ion-touched ion-valid">
  <ion-label position="stacked">Custom Input Highlight: Focused & Valid</ion-label>
  <ion-input></ion-input>
</ion-item>

<ion-item lines="full" class="item-has-focus ion-touched ion-invalid">
  <ion-label position="stacked">Custom Input Highlight: Focused & Invalid</ion-label>
  <ion-input></ion-input>
</ion-item>

Properties

button

Description	If true, a button tag will be rendered and the item will be tappable.
Attribute	button
Type	boolean
Default	false

color

Description	The color to use from your application's color palette. Default options are: "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", and "dark". For more information on colors, see theming.
Attribute	color
Type	"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
Default	undefined

counter

Description	If true, a character counter will display the ratio of characters used and the total character limit. Only applies when the maxlength property is set on the inner ion-input or ion-textarea.
Attribute	counter
Type	boolean
Default	false

counterFormatter

Description	A callback used to format the counter text. By default the counter text is set to "itemLength / maxLength".
Attribute	undefined
Type	((inputLength: number, maxLength: number) => string) ｜ undefined
Default	undefined

detail

Description	If true, a detail arrow will appear on the item. Defaults to false unless the mode is ios and an href or button property is present.
Attribute	detail
Type	boolean ｜ undefined
Default	undefined

detailIcon

Description	The icon to use when detail is set to true.
Attribute	detail-icon
Type	string
Default	chevronForward

disabled

Description	If true, the user cannot interact with the item.
Attribute	disabled
Type	boolean
Default	false

download

Description	This attribute instructs browsers to download a URL instead of navigating to it, so the user will be prompted to save it as a local file. If the attribute has a value, it is used as the pre-filled file name in the Save prompt (the user can still change the file name if they want).
Attribute	download
Type	string ｜ undefined
Default	undefined

fill

Description	The fill for the item. If 'solid' the item will have a background. If 'outline' the item will be transparent with a border. Only available in md mode.
Attribute	fill
Type	"outline" ｜ "solid" ｜ undefined
Default	undefined

href

Description	Contains a URL or a URL fragment that the hyperlink points to. If this property is set, an anchor tag will be rendered.
Attribute	href
Type	string ｜ undefined
Default	undefined

lines

Description	How the bottom border should be displayed on the item.
Attribute	lines
Type	"full" ｜ "inset" ｜ "none" ｜ undefined
Default	undefined

mode

Description	The mode determines which platform styles to use.
Attribute	mode
Type	"ios" ｜ "md"
Default	undefined

rel

Description	Specifies the relationship of the target object to the link object. The value is a space-separated list of link types.
Attribute	rel
Type	string ｜ undefined
Default	undefined

routerAnimation

Description	When using a router, it specifies the transition animation when navigating to another page using href.
Attribute	undefined
Type	((baseEl: any, opts?: any) => Animation) ｜ undefined
Default	undefined

routerDirection

Description	When using a router, it specifies the transition direction when navigating to another page using href.
Attribute	router-direction
Type	"back" ｜ "forward" ｜ "root"
Default	'forward'

shape

Description	The shape of the item. If "round" it will have increased border radius.
Attribute	shape
Type	"round" ｜ undefined
Default	undefined

target

Description	Specifies where to display the linked URL. Only applies when an href is provided. Special keywords: "_blank", "_self", "_parent", "_top".
Attribute	target
Type	string ｜ undefined
Default	undefined

type

Description	The type of the button. Only used when an onclick or button property is present.
Attribute	type
Type	"button" ｜ "reset" ｜ "submit"
Default	'button'

Events

No events available for this component.

Methods

No public methods available for this component.

CSS Shadow Parts

Name	Description
detail-icon	The chevron icon for the item. Only applies when detail="true".
native	The native HTML button, anchor or div element that wraps all child elements.

CSS Custom Properties

Name	Description
--background	Background of the item
--background-activated	Background of the item when pressed. Note: setting this will interfere with the Material Design ripple.
--background-activated-opacity	Opacity of the item background when pressed
--background-focused	Background of the item when focused with the tab key
--background-focused-opacity	Opacity of the item background when focused with the tab key
--background-hover	Background of the item on hover
--background-hover-opacity	Opacity of the background of the item on hover
--border-color	Color of the item border
--border-radius	Radius of the item border
--border-style	Style of the item border
--border-width	Width of the item border
--color	Color of the item
--color-activated	Color of the item when pressed
--color-focused	Color of the item when focused with the tab key
--color-hover	Color of the item on hover
--detail-icon-color	Color of the item detail icon
--detail-icon-font-size	Font size of the item detail icon
--detail-icon-opacity	Opacity of the item detail icon
--highlight-color-focused	The color of the highlight on the item when focused
--highlight-color-invalid	The color of the highlight on the item when invalid
--highlight-color-valid	The color of the highlight on the item when valid
--highlight-height	The height of the highlight on the item
--inner-border-width	Width of the item inner border
--inner-box-shadow	Box shadow of the item inner
--inner-padding-bottom	Bottom padding of the item inner
--inner-padding-end	Right padding if direction is left-to-right, and left padding if direction is right-to-left of the item inner
--inner-padding-start	Left padding if direction is left-to-right, and right padding if direction is right-to-left of the item inner
--inner-padding-top	Top padding of the item inner
--min-height	Minimum height of the item
--padding-bottom	Bottom padding of the item
--padding-end	Right padding if direction is left-to-right, and left padding if direction is right-to-left of the item
--padding-start	Left padding if direction is left-to-right, and right padding if direction is right-to-left of the item
--padding-top	Top padding of the item
--ripple-color	Color of the item ripple effect
--transition	Transition of the item

Slots

Name	Description
``	Content is placed between the named slots if provided without a slot.
end	Content is placed to the right of the item text in LTR, and to the left in RTL.
error	Content is placed under the item and displayed when an error is detected.
helper	Content is placed under the item and displayed when no error is detected.
start	Content is placed to the left of the item text in LTR, and to the right in RTL.