Overview

The Data List component is designed to display arrays of objects in a visually appealing manner. It supports toggling between grid and list views, expanding items for full descriptions, and dynamically adding or removing items.

Key Features:

  • Grid and List view toggle
  • Expandable item descriptions
  • Image support with fallback placeholders
  • Tag/category display
  • Smooth animations and transitions
  • Event-driven architecture for real-time updates

Basic Usage

HTML Structure

<div data-component="data-list"
				data-source='[...]'
				data-view="grid"
				data-expand="true">
				</div>

Data Format

Pass an array of objects with the following properties:

{
				id: "unique-id",              // Optional, uses array index if not provided
				title: "Item Title",          // Required
				subtitle: "Subtitle",         // Optional
				description: "Full text...",  // Optional, shown on expand
				image: "url-to-image",        // Optional
				tags: ["tag1", "tag2"]        // Optional array of strings
				}

Attributes

Attribute Type Default Description
data-source JSON String [] Array of item objects to display
data-view String "grid" Initial view mode: "grid" or "list"
data-expand Boolean true Enable expandable items for full descriptions

JavaScript API

Access the component instance for programmatic control:

// Get component reference
				const dataListEl = document.querySelector('[data-component="data-list"]');

				// Add item
				window.componentInstances.get(dataListEl).addItem({
				id: 4,
				title: "New Item",
				description: "Item description",
				tags: ["new"]
				});

				// Remove item
				window.componentInstances.get(dataListEl).removeItem(1);

				// Update all items
				window.componentInstances.get(dataListEl).updateItems(newItemsArray);

				// Get items
				const items = window.componentInstances.get(dataListEl).getItems();

				// Set view
				window.componentInstances.get(dataListEl).setView('list');

Events

Event Detail Description
view-changed { view: "grid" | "list" } Fired when user toggles view
item-added { item: {...} } Fired when item is added
item-removed { id: "item-id" } Fired when item is removed
items-updated { items: [...] } Fired when items array is updated

Advanced Example

// Listen for events
				const dataList = document.querySelector('[data-component="data-list"]');

				dataList.addEventListener('item-added', (e) => {
				console.log('Item added:', e.detail.item);
				});

				dataList.addEventListener('view-changed', (e) => {
				console.log('View changed to:', e.detail.view);
				});

Responsive Behavior

This component automatically adapts to different screen sizes:

Mobile (< 768px)

On mobile devices:

  • Optimized for small screens
  • Touch-friendly spacing maintained (44px minimum)
  • Text wraps naturally without overflow
  • Content density optimized for readability

Desktop (1024px+)

On desktop displays:

  • Enhanced visual features
  • Hover states and transitions
  • Full keyboard navigation support
  • Optimal spacing and sizing

Framework Integration

Responsive behavior is automatic:

  • Framework handles media queries
  • No custom CSS required
  • Mobile-first approach applied
  • Accessibility maintained at all sizes

Best Practices

  • Images: Use optimized images around 400x300px for best performance
  • Descriptions: Keep descriptions concise; use expand functionality for details
  • Tags: Limit to 3-4 tags per item for better visual balance
  • Performance: For large datasets (1000+), consider pagination or virtual scrolling
  • Accessibility: All interactive elements are keyboard accessible and screen reader compatible

Browser Support

The Data List component works in all modern browsers:

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+

Features

  • Semantic Structure - Built with native HTML5 elements for maximum reliability.
  • Theme Aware - Automatically adapts to all 22 Axiom01 themes via OKLCH tokens.
  • Fully Responsive - Scales perfectly from mobile to desktop screens.
  • No JS Dependency - Core functionality relies on pure CSS for maximum performance.
  • Customizable - Easily extendable via Axiom01's design tokens and modifiers.

Use Cases

The Data List component is designed for versatile implementation across modern web applications. Ideal scenarios include:

  • Dashboards & Admin Panels - Structured data presentation and interface control.
  • Content Management Systems - Organizing complex information hierarchies and media.
  • E-Commerce Platforms - Enhancing product discovery and user workflows.
  • Marketing Sites - Highlighting key product offerings cleanly and effectively.
  • SaaS Applications - Delivering native-feeling, responsive app experiences.

Accessibility

Axiom01 ensures that the Data List component meets strict WCAG standards out of the box:

  • Keyboard Navigation - Fully navigable using standard Tab and Arrow key workflows.
  • Screen Reader Support - Requires minimal manual ARIA labeling due to semantic HTML roots.
  • Focus Management - Visible, high-contrast focus indicators without layout shifting.
  • Color Contrast - OKLCH math guarantees perfect WCAG AAA contrast ratios in both light and dark modes.
  • Reduced Motion - Respects system-level prefers-reduced-motion settings for any internal animations.