Facepile

The facepile component is an organism-level layout that displays multiple user avatars with presence indicators in a horizontal arrangement. It’s commonly used to show team members, collaborators, or participants in a compact, visually appealing format.

Overview

Facepile provides a space-efficient way to display multiple users by showing their avatars in a row with flexible wrapping. It leverages the avatar-with-presence molecular component to maintain consistency with other persona representations throughout the application while supporting various layout contexts and user interaction patterns.

Features

Layout and Display

• Horizontal Arrangement: Displays avatars in left-to-right flow with intelligent wrapping
• Flexible Spacing: Maintains consistent 1.118rem margins between avatars
• Responsive Design: Adapts to container width with automatic line wrapping
• Smooth Transitions: 1-second ease-in-out transitions for dynamic updates

User Representation

• Avatar Integration: Each user represented by avatar with optional image or initials
• Presence Status: Real-time presence indicators (online, away, busy, offline)
• User Information: Support for display names, roles, and additional metadata
• Interactive Elements: Optional click handlers for user selection or profile viewing

Size Variants

The component supports multiple avatar sizes for different contexts:

• 24px: Ultra-compact for dense layouts and minimal space
• 32px: Compact for navigation elements and sidebar displays
• 40px: Standard size for most application contexts
• 48px: Prominent display for featured content areas
• 64px: Large display for hero sections and main content

Structure

The facepile consists of:

1. Container: .hoo-facepile - Main flexbox container
2. Avatar-Presence Items: Individual avatar-with-presence components
3. Optional Overflow: Overflow indicator for large user sets

Data Structure

Standard Data Format

{
    "items": [
        {
            "avatar": {
                "mugshot": "../../images/mug-shots/user1.jpg",
                "status": "online",
                "size": 32,
                "initials": "JD",
                "displayName": "John Doe",
                "title": "Software Engineer"
            },
            "size": 32
        },
        {
            "avatar": {
                "mugshot": "../../images/mug-shots/user2.jpg",
                "status": "away",
                "size": 32,
                "initials": "JS",
                "displayName": "Jane Smith",
                "title": "Product Manager"
            },
            "size": 32
        }
    ]
}

With Metadata

{
    "items": [
        {
            "avatar": {
                "mugshot": "user1.jpg",
                "status": "online",
                "size": 40,
                "initials": "AB",
                "displayName": "Alice Brown",
                "title": "Team Lead",
                "department": "Engineering",
                "email": "alice.brown@company.com"
            },
            "size": 40,
            "role": "owner",
            "lastActive": "2024-01-15T10:30:00Z"
        }
    ]
}

CSS Classes

Container Classes

• .hoo-facepile: Main flexbox container with wrapping and spacing

Avatar-Presence Classes

• .hoo-avatar-pres-{size}: Individual avatar-presence containers
• .hoo-avatar-{size}: Avatar image containers
• .hoo-presence-{size}: Presence indicator elements

Size-Specific Classes

• .hoo-avatar-pres-24: 24px avatar-presence container
• .hoo-avatar-pres-32: 32px avatar-presence container
• .hoo-avatar-pres-40: 40px avatar-presence container
• .hoo-avatar-pres-48: 48px avatar-presence container
• .hoo-avatar-pres-64: 64px avatar-presence container

Styling

Layout Properties

Visual Design

• Background: Transparent, relies on individual avatar styling
• Spacing: 1.118rem margins between avatars (accounts for presence indicator positioning)
• Alignment: Flex-start alignment for consistent left-to-right flow
• Transitions: Smooth 1-second transitions for dynamic content changes

Responsive Behavior

• Flexible Width: Adapts to container width constraints
• Intelligent Wrapping: Automatically wraps to new lines when needed
• Consistent Spacing: Maintains uniform gaps regardless of line breaks
• Smooth Updates: Animated transitions for adding/removing users

Use Cases

Team and Collaboration

• Project Teams: Display team members in project management interfaces
• Document Collaboration: Show active editors and reviewers
• Meeting Participants: Display attendees in video conference interfaces
• Workspace Members: Show team members in shared workspaces

Social and Community

• Group Membership: Display members of groups or communities
• Event Attendance: Show event attendees or RSVP lists
• Social Connections: Display mutual friends or followers
• Discussion Participants: Show contributors to conversations

Content and Media

• Content Contributors: Display authors, editors, and reviewers
• Media Collaborators: Show people with access to shared media
• Version History: Display contributors to document versions
• Approval Workflows: Show approvers and reviewers in workflows

System and Administration

• User Management: Display system users and administrators
• Permission Groups: Show members of permission or security groups
• Department Views: Display organizational structure and reporting
• Activity Logs: Show users involved in recent activities

Accessibility

Screen Reader Support

• Individual Focus: Each avatar is individually focusable and navigable
• Descriptive Labels: Clear names and status descriptions for each user
• Group Context: Container provides context for the collection of users
• Live Updates: Presence changes announced appropriately via ARIA live regions

Keyboard Navigation

• Tab Order: Logical tab sequence through interactive avatars
• Focus Management: Clear focus indicators and consistent focus states
• Interactive Elements: Keyboard access to clickable avatars and actions
• Skip Navigation: Ability to skip large facepiles for efficient navigation

Visual Accessibility

• High Contrast: Strong color contrast for all text and status indicators
• Color Independence: Status communicated through multiple visual methods
• Size Flexibility: Scales appropriately with user font size preferences
• Focus Indicators: Clear visual focus states for keyboard users

Performance Considerations

Image Loading

• Lazy Loading: Implement lazy loading for avatar images in large collections
• Progressive Loading: Load visible avatars first, then off-screen ones
• Image Optimization: Use appropriate formats (WebP, AVIF) and sizes
• Fallback Handling: Graceful fallback to initials when images fail to load

Large Collections

• Virtualization: Use virtual scrolling for very large user sets (100+ users)
• Pagination: Implement pagination or “load more” for extensive lists
• Overflow Indicators: Show limited avatars with overflow count for space efficiency
• Search and Filter: Provide search capabilities for large user collections

Dynamic Updates

• Efficient Re-renders: Minimize DOM manipulation for presence updates
• Batch Updates: Group multiple changes to reduce layout thrashing
• Memory Management: Properly clean up event listeners and image references
• Caching: Implement effective caching for user data and avatar images

Integration with Overflow

For large user collections, combine with overflow indicators:

<div class="user-collection">
    <div class="hoo-facepile">
        {{#each visibleUsers}}
        {{> molecules-avatar-presence }}
        {{/each}}
    </div>
    {{#if hasOverflow}}
    {{> molecules-persona-overflow number="+{{overflowCount}}" }}
    {{/if}}
</div>

JavaScript Overflow Management

React Integration

For React applications, use the @n8d/htwoo-react package which provides facepile components with the same design system styling. Facepile components are available in Storybook for interactive examples and documentation.

Integration Examples

SharePoint Framework (SPFx)

Best Practices

Design Guidelines

• Consistent Sizing: Use the same avatar size throughout a single facepile
• Logical Ordering: Order users by relevance, status, activity, or alphabetically
• Visual Hierarchy: Use size and positioning to indicate importance or roles
• Overflow Management: Implement clear overflow indicators for large user sets

User Experience

• Performance: Optimize for quick loading and smooth interactions
• Responsiveness: Ensure facepiles work well across all device sizes
• Context: Provide clear context for who the users are and their relationship
• Interactivity: Consider tooltips or click actions for additional user information