Skip to main content

​
List

The List component displays a continuous group of text and images in a vertical format. It’s commonly used for navigation menus, settings panels, and data display.

​
Installation

npm install @naturacosmeticos/natds-web

​
Usage

import { List, ListItem, ListItemText } from '@naturacosmeticos/natds-web';

function BasicList() {
  return (
    <List>
      <ListItem>
        <ListItemText primary="Item 1" />
      </ListItem>
      <ListItem>
        <ListItemText primary="Item 2" />
      </ListItem>
      <ListItem>
        <ListItemText primary="Item 3" />
      </ListItem>
    </List>
  );
}

​
List Variants

​
Simple List

Basic list with primary text only: 
<List>
  <ListItem>
    <ListItemText primary="Inbox" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Drafts" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Sent" />
  </ListItem>
</List>

​
List with Icons

Add icons to list items: 
import { List, ListItem, ListItemIcon, ListItemText, Icon } from '@naturacosmeticos/natds-web';

<List>
  <ListItem>
    <ListItemIcon>
      <Icon name="outlined-default-mockup" />
    </ListItemIcon>
    <ListItemText primary="Inbox" />
  </ListItem>
  <ListItem>
    <ListItemIcon>
      <Icon name="outlined-default-mockup" />
    </ListItemIcon>
    <ListItemText primary="Drafts" />
  </ListItem>
</List>

​
List with Avatars

Display avatars in list items: 
import { List, ListItem, ListItemAvatar, ListItemText, Avatar } from '@naturacosmeticos/natds-web';

<List>
  <ListItem>
    <ListItemAvatar>
      <Avatar>JD</Avatar>
    </ListItemAvatar>
    <ListItemText 
      primary="John Doe" 
      secondary="Software Engineer"
    />
  </ListItem>
  <ListItem>
    <ListItemAvatar>
      <Avatar>JS</Avatar>
    </ListItemAvatar>
    <ListItemText 
      primary="Jane Smith" 
      secondary="Product Designer"
    />
  </ListItem>
</List>

​
List with Secondary Text

Show both primary and secondary text: 
<List>
  <ListItem>
    <ListItemText 
      primary="Brunch this weekend?"
      secondary="I'll be in your neighborhood doing errands this weekend."
    />
  </ListItem>
  <ListItem>
    <ListItemText 
      primary="Summer BBQ"
      secondary="Wish I could come, but I'm out of town this weekend."
    />
  </ListItem>
</List>

​
List with Secondary Actions

Add action buttons to list items: 
import { 
  List, 
  ListItem, 
  ListItemText, 
  ListItemSecondaryAction,
  IconButton,
  Icon
} from '@naturacosmeticos/natds-web';

<List>
  <ListItem>
    <ListItemText primary="Notifications" />
    <ListItemSecondaryAction>
      <IconButton>
        <Icon name="outlined-action-settings" />
      </IconButton>
    </ListItemSecondaryAction>
  </ListItem>
  <ListItem>
    <ListItemText primary="Sound" />
    <ListItemSecondaryAction>
      <IconButton>
        <Icon name="outlined-action-settings" />
      </IconButton>
    </ListItemSecondaryAction>
  </ListItem>
</List>

​
Interactive List

function InteractiveList() {
  const [selectedIndex, setSelectedIndex] = React.useState(0);

  const handleClick = (index) => {
    setSelectedIndex(index);
  };

  return (
    <List>
      {['Inbox', 'Starred', 'Drafts', 'Sent'].map((text, index) => (
        <ListItem
          button
          key={text}
          selected={selectedIndex === index}
          onClick={() => handleClick(index)}
        >
          <ListItemText primary={text} />
        </ListItem>
      ))}
    </List>
  );
}

​
Nested Lists

import { List, ListItem, ListItemText, Collapse } from '@naturacosmeticos/natds-web';

function NestedList() {
  const [open, setOpen] = React.useState(true);

  return (
    <List>
      <ListItem button onClick={() => setOpen(!open)}>
        <ListItemText primary="Inbox" />
      </ListItem>
      <Collapse in={open} timeout="auto" unmountOnExit>
        <List disablePadding>
          <ListItem>
            <ListItemText primary="Starred" />
          </ListItem>
          <ListItem>
            <ListItemText primary="Drafts" />
          </ListItem>
        </List>
      </Collapse>
    </List>
  );
}

​
Dense List

Use dense spacing for compact layouts: 
<List dense>
  <ListItem>
    <ListItemText primary="Item 1" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Item 2" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Item 3" />
  </ListItem>
</List>

​
Props

​
List

​
children
node
The content of the component, typically ListItem components.
​
dense
boolean
default:"false"
If true, compact vertical padding will be used for the list and list items.
​
disablePadding
boolean
default:"false"
If true, vertical padding will be removed from the list.
​
subheader
node
The content of the subheader, normally a ListSubheader component.

​
ListItem

​
button
boolean
default:"false"
If true, the list item will be a button using ButtonBase.
​
selected
boolean
default:"false"
Use to apply selected styling.
​
disabled
boolean
default:"false"
If true, the list item will be disabled.
​
divider
boolean
default:"false"
If true, a 1px light border is added to the bottom of the list item.
​
dense
boolean
default:"false"
If true, compact vertical padding will be used.
​
onClick
function
Callback fired when the list item is clicked.

​
ListItemText

​
primary
node
The main content element.
​
secondary
node
The secondary content element.
​
disableTypography
boolean
default:"false"
If true, the children won’t be wrapped by a Typography component.
​
inset
boolean
default:"false"
If true, the children will be indented. Use this when there is no left avatar or icon.

​
Subcomponents

  • ListItem: Individual list item component
  • ListItemText: Text content for list items
  • ListItemIcon: Icon wrapper for list items
  • ListItemAvatar: Avatar wrapper for list items
  • ListItemSecondaryAction: Container for secondary actions
  • ListSubheader: Subheader component for grouping items

​
Best Practices

  • Use button prop on ListItem for clickable items
  • Limit secondary text to 2-3 lines for readability
  • Use ListItemSecondaryAction for actions that don’t affect the entire item
  • Consider using dividers between items in long lists
  • Use dense lists in compact layouts or when displaying many items

​
Accessibility

  • Set button prop when ListItem is interactive
  • Provide appropriate ARIA labels for icon-only actions
  • Use proper heading hierarchy with ListSubheader
  • Ensure sufficient color contrast for text

​
Related Components

Build docs developers (and LLMs) love

Get started for freeTalk to us