StatsRail

Purpose

StatsRail displays a row of selectable statistics with:

• Animated selection indicator
• Hover background effect
• Responsive layout (horizontal on mobile, configurable on desktop)
• Custom render support

When to use

Use StatsRail for:

• Dashboard KPI selectors
• Tab-like stat navigation
• Metric category filters
• Summary stat displays

Basic usage

import { StatsRail, type StatsItem } from '@/shared/ui/components/StatsRail'
import { Users, DollarSign, ShoppingCart } from 'lucide-react'

const stats: StatsItem[] = [
  { id: 'users', label: 'Total Users', value: '12,345', delta: '+12%' },
  { id: 'revenue', label: 'Revenue', value: '$45,678', delta: '+8%' },
  { id: 'orders', label: 'Orders', value: '1,234', hint: 'This month' },
]

export function DashboardStats() {
  const [activeId, setActiveId] = useState('users')

  return (
    <StatsRail
      items={stats}
      activeId={activeId}
      onChange={setActiveId}
      ariaLabel="Dashboard statistics"
    />
  )
}

Props

StatsRailProps

Prop	Type	Default	Description
items	StatsItem[]	Required	Array of stat items
activeId	string	-	Controlled active item
defaultActiveId	string	First item	Initial active item
onChange	(id: string) => void	-	Selection change handler
renderItem	(item, state) => ReactNode	-	Custom item renderer
breakpoint	'md' | 'lg' | 'xl' | '2xl'	'md'	Responsive breakpoint
ariaLabel	string	-	Navigation aria-label
className	string	-	Container class

StatsItem

Property	Type	Required	Description
id	string	Yes	Unique identifier
label	string	Yes	Stat label
value	string | number	Yes	Stat value
hint	string	No	Additional context
delta	string	No	Change indicator
icon	ReactNode	No	Optional icon
to	string	No	Navigation link

Custom rendering

<StatsRail
  items={stats}
  renderItem={(item, { active, onClick }) => (
    <div
      onClick={onClick}
      className={active ? 'font-bold' : ''}
    >
      <span>{item.label}</span>
      <span className="text-2xl">{item.value}</span>
    </div>
  )}
/>

Notes

• Uses Framer Motion for smooth indicator animation
• Respects prefers-reduced-motion for accessibility
• Auto-scrolls active item into view on mobile
• Built with FloatingHover for hover background effect