list/introduction

Quick Demo

1️⃣ Mindset Shift

First things first: Forget everything you *think* a list component should be or do.

Seriously, this is step #1 for grokking our list component. Those old expectations probably came from wonky implementations in other libs/plugins/whatever. Holding onto that old way of thinking will just trip you up here.

2️⃣ What is a List Component?

# The Big Picture

Think of native <ul> and <ol> as "a set of items managed somehow." Our list component shares that core idea but narrows "somehow" to "vertical stacking only". So, while you could use native tags for horizontal lists, our list items strictly stack vertically.

# Inside the List Item

Let's break down the "list item": It's basically just a generic card (component, if you prefer). But, the layout patterns for its inner elements usually stick to a tighter range than the infinite possibilities of a general card.

Often, the elements inside a list item stack horizontally. BUT, that doesn't mean we should bake that assumption in and create a bunch of related components (like <ListItemAvatar>, <ListItemAction>, etc.).

"Why not?" you ask. Because in the real world, horizontal stacking isn't always the case. You can't just say "other stacking methods aren't common" (because they totally are). Plus, the elements inside can vary wildly. And honestly, creating those specific components is dead simple with Tailwind anyway.

"So...?" Still confused? This means the right design should NEVER assume anything about what goes inside a list item. Instead, you should put whatever content you need in there and handle the layout manually with Tailwind for maximum flexibility.

"Then what's the point of using components at all?" you wonder. Ah, that's why I said this component is sophisticated! It might seem confusing now, but stick with me!

3️⃣ The Component Family

Following our general theming approach, all components mentioned below use flexbox. They're flex containers with super minimal default styles (you'll thank us later!). Think of it like we're giving you near-headless components.

# <List>

The only thing that goes directly inside a <List> is a <ListItem>. Period. Just like people don't typically toss random elements besides <li>into native <ul> or <ol>, we're sticking to that common sense.

# <ListItem>

Since only <ListItem>s go in a <List>, anything else you need to integrate (icons, buttons, text, custom components) goes inside the <ListItem>.

4️⃣ Nested Lists

Nested lists are super common, especially in sidebars. We built support for this right in, so you can nest lists as deep as you need. You can achieve UIs like this:

Most of the time, nested lists have an indent style. You get that automatically just by putting a <List> inside a <ListItem>:

  {/* Nest as deep as you want! */}
  <List>
    <ListItem>
      Level 1 Item Title
      <List>
        <ListItem>Level 2 Item Title</ListItem>
        {/* more <ListItem/>... */}
      </List>
    </ListItem>
    <ListItem>Another Level 1 Item</ListItem>
    {/* more <ListItem/>... */}
  </List>
      

Keep in mind, a nested list structure is quite specific. A ListItem containing a list typically includes:

• A title (doesn't have to be plain text; it represents what the nested list is about).
• A list representation (doesn't have to be our List component, but usually is).

If these instructions seem a bit high-level, that's intentional. The best way to really get it is to play around with the "Collapsible nested list" demos below. Check out the code snippets and compare them to what we've explained here:

5️⃣ Real-World Examples Galore

Compared to other component libs, the examples in our docs serve some extra IMPORTANT purposes:

• Shift Your Thinking: Through these examples, we show you from different angles why list components should be designed this way. This helps avoid confusion like "Why don't you provide feature X?". Get familiar with our approach, and you'll be super productive (fingers crossed!).
• Code Templates: Since our design encourages manual styling and feature implementation (using Tailwind), providing lots of real-world examples is key. Think of them as common templates you can copy-paste. The big win? You won't get bogged down trying to customize complex, black-box components by digging through endless API docs. With our approach, it's mostly just Tailwind + our minimal list components!

Alright! To explore the family components and see more demos showcasing this component's versatility, head over to the API reference page.

Q&A