List

Vertical list group with optional interactivity, icons, meta, and avatars.

Overview

The List component is a core building block of the Byteion design system, providing a robust, accessibility-compliant interface for its specific UI capabilities.

Why this exists

Lists organize items vertically in a scannable format. They are the simplest data display structure for menus, settings, and summaries.

Mental model

A list is a vertical sequence of items, each with optional leading icon, primary text, secondary text, and trailing action.

When to use

• Settings menus • Notification lists • Activity logs • Simple item listings

When not to use

• Do not use for complex data — use a table • Avoid for items needing multiple columns — use a table • Do not use for hierarchical data — use a tree or accordion

Basic example

The following example demonstrates standard usage, fully compliant with Byteion's token-first approach.

Variants

Each variant communicates a different meaning. Choose based on priority, not aesthetics.

Single default variant.

Sizes

Size should match the importance and context of the component.

  • md — md size.

States

This component reacts seamlessly to the following interaction and data states:

  • default — Resting appearance before interaction.
  • hover — Pointer is over the element — visual feedback via color or shadow.
  • active — Currently selected or in use.
  • focus — Keyboard or tab focus — shows ring indicator for accessibility.
  • disabled — Non-interactive — grayed out, cursor not-allowed.

Anatomy

• Container — bordered or plain • Item — row with leading, main, trailing sections • Divider — between items • Header — optional section title

Usage guidelines

  • Keep items to one line when possible.
  • Use dividers between items.
  • Leading icons should be consistent.

Do and Don't

Do

  • Use dividers.
  • Keep items scannable.
  • Use consistent leading icons.

Don't

  • Do not use for multi-column data.
  • Do not omit dividers in bordered lists.
  • Do not mix item layouts randomly.

Accessibility

Interactive items should be links or buttons. List container is a <ul> or <ol>.

Role:list (implicit via

    )

Customization

Border and hover follow list tokens.

Compose with React cva()

Use the exportedcva() +cn() utilities to compose your own variant on top of the Byteion tokens.

import { cva, cn, type VariantProps } from '@byteion/react';

const myList = cva('base classes…', {
 variants: {
  accent: { soft:'border-primary-200', loud:'border-primary-500' },
 },
 defaultVariants: { accent:'soft' },
});

type Props = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof myList>;

Compose with Vue cva()

Use the exportedcva() +cn() utilities inside standard Vue setup blocks.

<script setup lang="ts">
import { computed, useAttrs } from 'vue';
import { cva, type VariantProps } from '@byteion/vue';

interface Props { accent?:'soft' |'loud' }
const props = withDefaults(defineProps<Props>(), { accent:'soft' });
const attrs = useAttrs();

const myList = cva('base classes…', {
  variants: { accent: { soft:'border-primary-200', loud:'border-primary-500' } },
});

const cls = computed(() => myList({ accent: props.accent, class: attrs.class as string | undefined }));
</script>

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

HTML / JS events

No HTML runtime events are declared by this adapter.

React callbacks

No React callback events are declared by this adapter.

Vue emits

No Vue emitted events are declared by this adapter.

Remote / AJAX

This component does not implement Byteion JS remote loading. Use normal HTML form submission, framework state, or your application data layer around it.

API Reference

Static HTML composition.

HTML Data Attributes

No custom data attributes required.

React Props · ListProps

Extracted directly fromreact/src/components/List.tsx.

export interface ListProps extends HTMLAttributes<HTMLUListElement> {
  /** Render items inline as `<a>` for navigation lists. */
  interactive?: boolean;
  /** Dense spacing for compact interfaces. */
  dense?: boolean;
  children?: ReactNode;
}

Developer tips

• Use List for scannable summaries, not dense data comparison. • Keep row height consistent inside the same list. • If items navigate, use anchors or router links. • If items trigger an action, use buttons. • In notification or activity lists, include timestamp or status context. • In user lists, pair Avatar with name and email or role. • For long lists, consider search, filtering, pagination, or virtualization. • Keep active state connected to route or selected state.

Common mistakes

  • Using List for tabular data.
  • Mixing unrelated row layouts.
  • Making only a small text link clickable.
  • Forgetting semantic <li> elements.
  • Using icons without consistent meaning.
  • Hiding important metadata like timestamp or status.
  • Putting too many actions in one row.
  • Forgetting empty or loading states.
  • Using raw colours instead of tokens.

Production usage tips

  • Test empty list, one item, many items, long labels, long secondary text, and missing avatars.
  • Test keyboard focus for interactive rows.
  • Test active state in light mode, dark mode, and branded themes.
  • For Laravel or server-rendered apps, use normal links or forms for interactive rows.
  • For React or Vue SPAs, use router links for navigation rows and buttons for action rows.
  • For notification or activity lists, coordinate List with Badge, Avatar, Dropdown, Empty state, and Skeleton.
  • For large datasets, avoid rendering thousands of list items without pagination or virtualisation.

Premium examples

Advanced patterns available in Byteion Pro:

• Notification list with unread state • Activity feed list • User or member list with avatars • Settings list with icons and descriptions • Inbox or sidebar list with badges • Customer summary list • List with drag-and-drop reorder • List with swipe actions on mobile • Virtualised list for 1000+ items

Related components

Unlock Premium Patterns

Get access to copy-paste ready Pro blocks, SaaS templates, and advanced data-tables built with this component.

Explore Pro Components