Skip to content

docs(): add slot content recommendations #295

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
adrianptrv wants to merge 4 commits into
base: master
Choose a base branch
from
Open

docs(): add slot content recommendations #295

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ae02b05
feat(): add detailed information about slots
adrianptrv Jun 4, 2026
d9f6d0f
chore(): fix lint errors
adrianptrv Jun 4, 2026
f5d4c62
Merge branch 'master' into apetrov/add-recommended-slots
adrianptrv Jun 4, 2026
ac38f26
docs(): small improvements
adrianptrv Jun 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 98 additions & 85 deletions docs/xplat/src/content/en/components/grids/list.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,19 +20,14 @@ The following example represents a list populated with contacts with a name and

<Sample src="/grids/list/overview" height={300} alt="{Platform} List Example" />




<div class="divider--half"></div>

## Usage

At its core the list web component allows you to easily display a vertical list of items.


<PlatformBlock for="WebComponents">


First, you need to install the {ProductName} by running the following command:

```cmd
Expand All @@ -41,12 +36,8 @@ npm install {PackageWebComponents}

</PlatformBlock>



<PlatformBlock for="React">



First, you need to the install the corresponding {ProductName} npm package by running the following command:

```cmd
Expand All @@ -60,10 +51,8 @@ import { IgrList, IgrListHeader, IgrListItem } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';
```


</PlatformBlock>


Before using the <ApiLink pkg="inputs" type="List" />, you need to register it as follows:

<PlatformBlock for="Blazor">
Expand All @@ -76,21 +65,16 @@ builder.Services.AddIgniteUIBlazor(typeof(IgbListModule));

</PlatformBlock>


<PlatformBlock for="Blazor">



You will also need to link an additional CSS file to apply the styling to the <ApiLink pkg="inputs" type="List" /> component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project:

```razor
<link href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />
```


</PlatformBlock>


<PlatformBlock for="WebComponents">

```ts
Expand Down Expand Up @@ -132,13 +116,13 @@ Now, we can add the following code to get a simple list of items:
<IgbList>
<IgbListHeader>Header</IgbListHeader>
<IgbListItem>
<h2 slot="title">Item 1</h2>
<span slot="title">Item 1</span>
</IgbListItem>
<IgbListItem>
<h2 slot="title">Item 2</h2>
<span slot="title">Item 2</span>
</IgbListItem>
<IgbListItem>
<h2 slot="title">Item 3</h2>
<span slot="title">Item 3</span>
</IgbListItem>
</IgbList>
```
Expand All @@ -153,13 +137,13 @@ Now, we can add the following code to get a simple list of items:
<span>Header</span>
</IgrListHeader>
<IgrListItem>
<h2 slot="title">Item 1</h2>
<span slot="title">Item 1</span>
</IgrListItem>
<IgrListItem>
<h2 slot="title">Item 2</h2>
<span slot="title">Item 2</span>
</IgrListItem>
<IgrListItem>
<h2 slot="title">Item 3</h2>
<span slot="title">Item 3</span>
</IgrListItem>
</IgrList>
```
Expand All @@ -170,9 +154,6 @@ If all went well, you should see the following in your browser:

<Sample src="/grids/list/add-list-items" height={300} alt="{Platform} Add list items Example" />




Let's up our game a bit and enhance our list items. Say we want to create a list of contacts with a name and a phone number displayed under the name. To achieve that we can use some of the slots that come with the list items as demonstrated in the next example:

<PlatformBlock for="WebComponents">
Expand All @@ -183,15 +164,15 @@ Let's up our game a bit and enhance our list items. Say we want to create a list
<h1>Contacts</h1>
</igc-list-header>
<igc-list-item>
<h2 slot="title">Terrance Orta</h2>
<span slot="title">Terrance Orta</span>
<span slot="subtitle">770-504-2217</span>
</igc-list-item>
<igc-list-item>
<h2 slot="title">Richard Mahoney</h2>
<span slot="title">Richard Mahoney</span>
<span slot="subtitle">423-676-2869</span>
</igc-list-item>
<igc-list-item>
<h2 slot="title">Donna Price</h2>
<span slot="title">Donna Price</span>
<span slot="subtitle">859-496-2817</span>
</igc-list-item>
</igc-list>
Expand All @@ -207,15 +188,15 @@ Let's up our game a bit and enhance our list items. Say we want to create a list
<h1>Contacts</h1>
</IgbListHeader>
<IgbListItem>
<h2 slot="title">Terrance Orta</h2>
<span slot="title">Terrance Orta</span>
<span slot="subtitle">770-504-2217</span>
</IgbListItem>
<IgbListItem>
<h2 slot="title">Richard Mahoney</h2>
<span slot="title">Richard Mahoney</span>
<span slot="subtitle">423-676-2869</span>
</IgbListItem>
<IgbListItem>
<h2 slot="title">Donna Price</h2>
<span slot="title">Donna Price</span>
<span slot="subtitle">859-496-2817</span>
</IgbListItem>
</IgbList>
Expand All @@ -231,15 +212,15 @@ Let's up our game a bit and enhance our list items. Say we want to create a list
<span>Contacts</span>
</IgrListHeader>
<IgrListItem>
<h2 slot="title">Terrance Orta</h2>
<span slot="title">Terrance Orta</span>
<span slot="subtitle">770-504-2217</span>
</IgrListItem>
<IgrListItem>
<h2 slot="title">Richard Mahoney</h2>
<span slot="title">Richard Mahoney</span>
<span slot="subtitle">423-676-2869</span>
</IgrListItem>
<IgrListItem>
<h2 slot="title">Donna Price</h2>
<span slot="title">Donna Price</span>
<span slot="subtitle">859-496-2817</span>
</IgrListItem>
</IgrList>
Expand All @@ -251,9 +232,6 @@ After implementing the above code, our list component should now look like the f

<Sample src="/grids/list/list-item-content" height={300} alt="{Platform} List Example" />




### Adding Avatar and Buttons

We can use some of our other components in conjunction with the <ApiLink pkg="inputs" type="List" /> component to enrich the experience and add some functionality. We can have a nice picture avatar to the left of the name and phone values. Additionally, we can add some buttons to the right of them to allow the user to text and call contacts, so let's update our contacts list component to show the avatar and the buttons. We can do that by using some of the list item's slots.
Expand All @@ -269,7 +247,7 @@ We can use some of our other components in conjunction with the <ApiLink pkg="in
<igc-avatar slot="start" src="https://randomuser.me/api/portraits/men/27.jpg" shape="circle">
AA
</igc-avatar>
<h2 slot="title">Terrance Orta</h2>
<span slot="title">Terrance Orta</span>
<span slot="subtitle">770-504-2217</span>
<igc-button slot="end" variant="outlined">
Text
Expand All @@ -282,7 +260,7 @@ We can use some of our other components in conjunction with the <ApiLink pkg="in
<igc-avatar slot="start" src="https://randomuser.me/api/portraits/men/1.jpg" shape="circle">
AA
</igc-avatar>
<h2 slot="title">Richard Mahoney</h2>
<span slot="title">Richard Mahoney</span>
<span slot="subtitle">423-676-2869</span>
<igc-button slot="end" variant="outlined">
Text
Expand All @@ -295,7 +273,7 @@ We can use some of our other components in conjunction with the <ApiLink pkg="in
<igc-avatar slot="start" src="https://randomuser.me/api/portraits/women/50.jpg" shape="circle">
AA
</igc-avatar>
<h2 slot="title">Donna Price</h2>
<span slot="title">Donna Price</span>
<span slot="subtitle">859-496-2817</span>
<igc-button slot="end" variant="outlined">
Text
Expand All @@ -318,21 +296,21 @@ We can use some of our other components in conjunction with the <ApiLink pkg="in
</IgbListHeader>
<IgbListItem>
<IgbAvatar slot="start" src="https://static.infragistics.com/xplatform/images/avatars/8.jpg" Shape="@AvatarShape.Circle"/>
<h2 slot="title">Terrance Orta</h2>
<span slot="title">Terrance Orta</span>
<span slot="subtitle">770-504-2217</span>
<IgbButton slot="end" Variant="@ButtonVariant.Outlined">Text</IgbButton>
<IgbButton slot="end" Variant="@ButtonVariant.Outlined">Call</IgbButton>
</IgbListItem>
<IgbListItem>
<IgbAvatar slot="start" src="https://static.infragistics.com/xplatform/images/avatars/17.jpg" Shape="@AvatarShape.Circle"/>
<h2 slot="title">Richard Mahoney</h2>
<span slot="title">Richard Mahoney</span>
<span slot="subtitle">423-676-2869</span>
<IgbButton slot="end" Variant="@ButtonVariant.Outlined">Text</IgbButton>
<IgbButton slot="end" Variant="@ButtonVariant.Outlined">Call</IgbButton>
</IgbListItem>
<IgbListItem>
<IgbAvatar slot="start" src="https://static.infragistics.com/xplatform/images/avatars/9.jpg" Shape="@AvatarShape.Circle"/>
<h2 slot="title">Donna Price</h2>
<span slot="title">Donna Price</span>
<span slot="subtitle">859-496-2817</span>
<IgbButton slot="end" Variant="@ButtonVariant.Outlined">Text</IgbButton>
<IgbButton slot="end" Variant="@ButtonVariant.Outlined">Call</IgbButton>
Expand All @@ -350,55 +328,37 @@ We can use some of our other components in conjunction with the <ApiLink pkg="in
<span>Contacts</span>
</IgrListHeader>
<IgrListItem>
<div slot="start">
<IgrAvatar src="https://static.infragistics.com/xplatform/images/avatars/8.jpg" shape="circle" />
</div>
<h2 slot="title">Terrance Orta</h2>
<IgrAvatar slot="start" src="https://static.infragistics.com/xplatform/images/avatars/8.jpg" shape="circle" />
<span slot="title">Terrance Orta</span>
<span slot="subtitle">770-504-2217</span>
<div slot="end">
<IgrButton variant="outlined">
<span>Text</span>
</IgrButton>
</div>
<div slot="end">
<IgrButton variant="outlined">
<span>Call</span>
</IgrButton>
</div>
<IgrButton slot="end" variant="outlined">
<span>Text</span>
</IgrButton>
<IgrButton slot="end" variant="outlined">
<span>Call</span>
</IgrButton>
</IgrListItem>
<IgrListItem>
<div slot="start">
<IgrAvatar src="https://static.infragistics.com/xplatform/images/avatars/17.jpg" shape="circle" />
</div>
<h2 slot="title">Richard Mahoney</h2>
<IgrAvatar slot="start" src="https://static.infragistics.com/xplatform/images/avatars/17.jpg" shape="circle" />
<span slot="title">Richard Mahoney</span>
<span slot="subtitle">423-676-2869</span>
<div slot="end">
<IgrButton variant="outlined">
<span>Text</span>
</IgrButton>
</div>
<div slot="end">
<IgrButton variant="outlined">
<span>Call</span>
</IgrButton>
</div>
<IgrButton slot="end" variant="outlined">
<span>Text</span>
</IgrButton>
<IgrButton slot="end" variant="outlined">
<span>Call</span>
</IgrButton>
</IgrListItem>
<IgrListItem>
<div slot="start">
<IgrAvatar src="https://static.infragistics.com/xplatform/images/avatars/9.jpg" shape="circle" />
</div>
<h2 slot="title">Donna Price</h2>
<IgrAvatar slot="start" src="https://static.infragistics.com/xplatform/images/avatars/9.jpg" shape="circle" />
<span slot="title">Donna Price</span>
<span slot="subtitle">859-496-2817</span>
<div slot="end">
<IgrButton variant="outlined">
<span>Text</span>
</IgrButton>
</div>
<div slot="end">
<IgrButton variant="outlined">
<span>Call</span>
</IgrButton>
</div>
<IgrButton slot="end" variant="outlined">
<span>Text</span>
</IgrButton>
<IgrButton slot="end" variant="outlined">
<span>Call</span>
</IgrButton>
</IgrListItem>
</IgrList>
```
Expand Down Expand Up @@ -507,6 +467,59 @@ The result of implementing the above code should look like the following:

<Sample src="/grids/list/overview" height={300} alt="{Platform} List Example" />

### Recommended Elements for Slots

When slotting content into the **title** and **subtitle** slots, we recommend using `<span>` elements rather than heading elements (`<h1>`–`<h6>`). Heading elements carry built-in styling (such as font size, line height, and margins) that can interfere with the component's intended typography and layout. Using a `<span>` provides a neutral container that inherits the component's styles cleanly.

To achieve the best results, we recommend using the [`<igc-avatar>`](../layouts/avatar.md) component for the **start** slot, which is intended for media content. For the **end** slot, which is intended to be used for actions, we recommend using components such as [`<igc-button>`](../inputs/button.md), [`<igc-switch>`](../inputs/switch.md), [`<igc-checkbox>`](../inputs/checkbox.md), etc., depending on the type of content you want to display. However, for those two slots, you can also use plain HTML elements, such as `<img>` for the **start** slot and `<button>` or another interactive element for the **end** slot, as long as they are appropriate for the content you want to display.

<PlatformBlock for="WebComponents">

```html
<igc-list>
<igc-list-header>Title</igc-list-header>
<igc-list-item>
<igc-avatar slot="start" src="https://randomuser.me/api/portraits/men/27.jpg"></igc-avatar>
<span slot="title">Terrance Orta</span>
<span slot="subtitle">770-504-2217</span>
<igc-button slot="end" variant="outlined">Call</igc-button>
</igc-list-item>
</igc-list>
```

</PlatformBlock>

<PlatformBlock for="Blazor">

```razor
<IgbList>
<IgbListHeader>Title</IgbListHeader>
<IgbListItem>
<IgbAvatar slot="start" src="https://randomuser.me/api/portraits/men/27.jpg"/>
<span slot="title">Terrance Orta</span>
<span slot="subtitle">770-504-2217</span>
<IgbButton slot="end" Variant="@ButtonVariant.Outlined">Call</IgbButton>
</IgbListItem>
</IgbList>
```

</PlatformBlock>

<PlatformBlock for="React">

```tsx
<IgrList>
<IgrListHeader>Title</IgrListHeader>
<IgrListItem>
<IgrAvatar slot="start" src="https://randomuser.me/api/portraits/men/27.jpg"/>
<span slot="title">Terrance Orta</span>
<span slot="subtitle">770-504-2217</span>
<IgrButton slot="end" variant="outlined">Call</IgrButton>
</IgrListItem>
</IgrList>
```

</PlatformBlock>

## Styling

Expand Down
Loading
Loading