Skip to main content
Version: v7

ion-item

shadow

Items are elements that can contain text, icons, avatars, images, inputs, and any other native or custom elements. Items should only be used as rows in a List with other items. Items can be swiped, deleted, reordered, edited, and more.

Basic Usage​

Items left align text and wrap 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-nowrap in the below example. See the CSS Utilities Documentation for more classes that can be added to an item to transform the text.

Content Types​

While items in a list take many forms, they typically support 5 different content types: supporting visuals, text, metadata, actions, and controls. However, not all of these content types should be used together at the same time. The following guide shows the different content types as well as how to properly utilize them in an application.

Supporting Visuals​

Supporting visuals are decorative icons or other adornments for an item. Common examples of supporting visuals are Avatars, Icons, and Thumbnails. Since this content is not required to understand the intent of the item, it is typically hidden from screen readers using aria-hidden="true".

If a visual is required to interact with the item, such as an icon button, then the visual is an action not a supporting visual.

Supporting visuals should be rendered in a consistent manner. This makes the information in each item easier to parse.

A list with several items. Each item has an icon and visible text describing the item. The icon in each item is rendered at the start of the line.
Do

Align visuals on the same side in a list

A list with several items. Each item has an icon and visible text describing the item. Some icons are rendered at the start of the line, and some icons are rendered at the end of the line
Don't

Don't render visuals with different alignments in the same list

In the example below, we are creating two lists with supporting visuals. The first list uses icons, and the second list uses avatars. The visuals are decorative, so they all have aria-hidden="true". Additionally, they are presented consistently in the start slot.

Text​

The text content type includes form control labels or other visible text. This text serves to indicate the intent of the item. Try to keep the text short and to the point.

If you find that you need a few more sentences to clarify the item's purpose, consider moving the additional sentences to a Note at the bottom of the list. Adding the item to its own list makes it clear which item the text is associated with.

A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed underneath the list.
Do

Move long text outside of the list

A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed as a single paragraph inline with the checkbox, making the text hard to read and increasing the height of the item.
Don't

Don't try to fit long text in an item

In the example below, we are creating a list with different types of text. The "First Name" and "Last Name" labels serve to indicate what to type into the text inputs.

The "Allow Notifications" label on the toggle has additional text underneath it that notes users can disable notifications. Since this text is short, it is placed inside of the item.

Below that list is another list containing a textarea with a Note containing long text underneath. The textarea was placed in its own list to make it apparent that the long text is associated with the textarea and not any other fields.

Metadata​

Metadata provides additional context for an item such as status text or counts. Components like Badge or Note are great ways of showing metadata.

Limit the amount of metadata you include to only the most relevant information.

A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item.
Do

Add only the most important metadata

A list that contains several items, each representing a different to-do list. Two counts are placed at the end of each item: One count that states the total number of tasks, and another count that states the total number of tasks that are due today.
Don't

Don't add too much metadata as it can overwhelm or confuse the user.

Developers should also consider how important the metadata is. Drawing attention to the metadata may be helpful for the user or it may distract them from the more important information depending on the use case.

A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item.
Do

Prioritize the most important content.

A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item. However, the count is highlighted in blue which draws the user's attention away from the name of the to-do list.
Caution

Prioritized metadata may distract from other important content.

In the example below, we are creating two lists with different kinds of metadata. The first list uses Note to show how many tasks are in each to-do list.

The second list mimics the iOS Mail app to show an inbox. This list makes use of custom metadata including an "unread message" indicator in the "start" slot as well as a timestamp and custom detail icon in the "end" slot. The "unread message" indicator is highlighted in blue to draw the user's attention to the unread messages, while the timestamp is more subtle.

Actions​

Actions are interactive elements that do something when you activate them. An item can have multiple actions displayed on a line. However, developers should ensure that each action's tap target is large enough to be usable.

Developers should avoid creating nested interactives which can break the user experience with screen readers. For example, developers should avoid adding a button inside the main content of the Item if the button property is set to true.

Actions can be added by using the Item Sliding component. Actions can also be placed directly inside of the Item without the use of Item Sliding, but this should be limited to no more than 2 actions.

A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. These actions are revealed by swiping on the item.
Do

Use an Item Sliding to reveal multiple actions by swiping on the Item.

A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. The actions are placed directly on the item. Since there are so many actions, some of the text is cut off.
Don't

Don't put more than 2 actions within an Item.

In the example below, we are creating a list of contacts. Each item is a stubbed button intended to bring you to the full contact page for that item. There are additional actions associated with each item that users can reveal by swiping on the item.

Controls​

Controls are form components such as checkboxes, inputs, radios, and more. Each item in a list should have at most two controls due to screen space constraints.

Metadata such as helper text or character counts should not be used on form controls in list views. If such metadata is needed, the form control should be placed outside of a list. Filled Inputs are a great way of visually defining the input container outside of a list.

There is an email input and a password input. Both have helper text associated with them. Since both are placed outside of a list it is clear which input each helper text is associated with.
Do

Place inputs with metadata outside of the list.

There is a list containing an email input and a password input. Both have helper texts associated with them. However, the divider between each item and between the helper text makes it hard to tell which input each helper text is associated with.
Don't

Don't put metadata for inputs in the list.

Alternatively, the metadata can be placed in a Note at the bottom of the list.

There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above.
Do

Place metadata for inputs at the end of a list.

There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with.
Don't

Don't put metadata for inputs in the list.

Items should typically have no more than two controls. If you need more controls, consider adding the additional controls in a Modal that is accessible from the item.

There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with.
Do

Move additional controls to a submenu accessible from the item.

There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above.
Don't

Don't use more than two controls within an item.

In the example below, we are creating a list of to-do tasks. Each item has a checkbox and an input. The checkbox lets the user mark a task as complete, and the input lets the user change the name of the task.

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.

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.

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.

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

Item Inputs​

Theming​

Colors​

CSS Shadow Parts​

CSS Custom Properties​

Guidelines​

The following guidelines will help ensure your list items are easy to understand and use.

  1. Items should only be used inside of Lists.
  2. Items inside of a list should be presented in a consistent format. For example, if your items present decorative icons, the icons should be positioned in the same way between items.
  3. Items should never render nested interactives. Screen readers are unable to select the correct interactive element when nested interactives are used. For example, avoid placing a button inside of an ion-item that has button="true".
  4. Use content types correctly. The Item component is designed to be a row in a List and should not be used as a general purpose container.

Properties​

button​

Descriptiontrueの場合、ボタンタグがレンダリングされ、アイテムはタップ可能になる。
Attributebutton
Typeboolean
Defaultfalse

color​

DescriptionThe 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.
Attributecolor
Type"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
Defaultundefined

counter (deprecated)​

Descriptiontrueの場合、文字カウンタが使用された文字の比率と総文字数制限を表示します。内側の ion-input または ion-textarea に maxlength プロパティが設定されている場合にのみ適用されます。 Deprecated Use the counter property on ion-input or ion-textarea instead.
Attributecounter
Typeboolean
Defaultfalse

counterFormatter (deprecated)​

DescriptionA callback used to format the counter text. By default the counter text is set to "itemLength / maxLength". Deprecated Use the counterFormatter property on ion-input or ion-textarea instead.
Attributeundefined
Type((inputLength: number, maxLength: number) => string) ｜ undefined
Defaultundefined

detail​

DescriptionIf 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.
Attributedetail
Typeboolean ｜ undefined
Defaultundefined

detailIcon​

Descriptiondetail が true に設定されているときに使用するアイコンです。
Attributedetail-icon
Typestring
DefaultchevronForward

disabled​

Descriptiontrueの場合、ユーザはそのアイテムと対話することができません。
Attributedisabled
Typeboolean
Defaultfalse

download​

DescriptionThis 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).
Attributedownload
Typestring ｜ undefined
Defaultundefined

fill (deprecated)​

DescriptionThe 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. Deprecated Use the fill property on ion-input or ion-textarea instead.
Attributefill
Type"outline" ｜ "solid" ｜ undefined
Defaultundefined

href​

DescriptionContains a URL or a URL fragment that the hyperlink points to. If this property is set, an anchor tag will be rendered.
Attributehref
Typestring ｜ undefined
Defaultundefined

lines​

Descriptionアイテムに表示される下枠の表示方法。
Attributelines
Type"full" ｜ "inset" ｜ "none" ｜ undefined
Defaultundefined

mode​

Descriptionmodeは、どのプラットフォームのスタイルを使用するかを決定します。
Attributemode
Type"ios" ｜ "md"
Defaultundefined

rel​

DescriptionSpecifies the relationship of the target object to the link object. The value is a space-separated list of link types.
Attributerel
Typestring ｜ undefined
Defaultundefined

routerAnimation​

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

routerDirection​

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

shape​

DescriptionThe shape of the item. If "round" it will have increased border radius.
Attributeshape
Type"round" ｜ undefined
Defaultundefined

target​

DescriptionSpecifies where to display the linked URL. Only applies when an href is provided. Special keywords: "_blank", "_self", "_parent", "_top".
Attributetarget
Typestring ｜ undefined
Defaultundefined

type​

Descriptionボタンの種類。onclickまたはbutton`プロパティが存在する場合にのみ使用される。
Attributetype
Type"button" ｜ "reset" ｜ "submit"
Default'button'

Events​

No events available for this component.

Methods​

No public methods available for this component.

CSS Shadow Parts​

NameDescription
detail-iconアイテムのシェブロンアイコンを表示します。detail="true"`のときのみ適用されます。
nativeすべての子要素をラップするネイティブHTMLのボタン、アンカー、またはdiv要素です。

CSS Custom Properties​

NameDescription
--backgroundアイテムの背景
--background-activated押されたときのアイテムの背景。注意：これを設定すると、Material Designの波紋に干渉します。
--background-activated-opacity押されたときのアイテム背景の不透明度
--background-focusedタブキーでフォーカスしたときのアイテムの背景
--background-focused-opacityタブキーでフォーカスしたときのアイテムの背景の不透明度
--background-hoverホバー時のアイテムの背景
--background-hover-opacityホバー時のアイテムの背景の不透明度
--border-colorアイテムの縁取りの色
--border-radiusアイテムの境界線の半径
--border-styleアイテムの枠のスタイル
--border-widthアイテムの枠の幅
--colorアイテムのカラー
--color-activated押したときのアイテムの色
--color-focusedタブキーでフォーカスしたときのアイテムの色
--color-hoverホバー時のアイテムの色
--detail-icon-colorアイテム詳細アイコンの色
--detail-icon-font-sizeアイテム詳細アイコンのFont Size
--detail-icon-opacityアイテム詳細アイコンの不透明度
--highlight-color-focusedフォーカスされたときのアイテムのハイライトの色。レガシーなフォーム構文を使用している input と textareas にのみ適用されます。廃止予定：モダンなフォーム構文を使用している場合、ハイライトは ion-input または ion-textarea にスタイル設定することができる。
--highlight-color-invalid無効な場合の項目のハイライトの色。レガシーなフォーム構文を使用している input と textareas にのみ適用されます。廃止予定：モダンなフォーム構文を使用している場合、ハイライトは ion-input または ion-textarea にスタイル設定することができる。
--highlight-color-valid有効な場合の項目のハイライトの色。レガシーなフォーム構文を使用している input と textareas にのみ適用されます。廃止予定：モダンなフォーム構文を使用している場合、ハイライトは ion-input または ion-textarea でスタイリングできる。
--highlight-heightアイテムのハイライトの高さ。レガシーなフォーム構文を使用している input と textareas にのみ適用されます。廃止予定：モダンなフォーム構文を使用している場合、ハイライトは ion-input または ion-textarea にスタイル設定することができる。
--inner-border-widthアイテム内枠の幅
--inner-box-shadowアイテム内側のボックスシャドウ
--inner-padding-bottomアイテム内側のBottom Padding
--inner-padding-end方向が左から右の場合はRight Padding、方向がアイテムの内側の右から左の場合はLeft Paddingとなります。
--inner-padding-start方向が左から右の場合はLeft Padding、方向が右から左の場合はRight Paddingがアイテム内側に入る
--inner-padding-topアイテム内側のTop Padding
--min-heightアイテムの最小高さ
--padding-bottomアイテムのBottom Padding
--padding-end方向が左から右の場合はRight Padding、方向が右から左の場合はLeft Paddingで項目を囲む
--padding-start方向が左から右の場合はLeft Padding、方向が右から左の場合はRight Paddingで項目を囲む
--padding-topアイテムのTop Padding
--ripple-colorアイテム波及効果の色
--transitionアイテムの変遷

Slots​

NameDescription
``slotがない状態で提供される場合、コンテンツは名前付きslotの間に配置されます。
endコンテンツは、LTRではアイテムテキストの右側に、RTLでは左側に配置されます。
errorコンテンツはアイテムの下に配置され、エラーが検出されたときに表示されます。DEPRECATED 代わりに ion-input または ion-textarea の "errorText" プロパティを使用してください。
helperコンテンツはアイテムの下に配置され、エラーが検出されない場合に表示されます。DEPRECATED 代わりに ion-input または ion-textarea の "helperText" プロパティを使用してください。
startコンテンツは、LTRではアイテムテキストの左側に、RTLでは右側に配置されます。

Contents

Edit this page