@n8d/htwoo-patterns

--- title: Facepile order: 10 --- # 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 ```json { "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 ```json { "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: ```handlebars <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