Social Icons

v1.1.2

Documentation Under Review

Installation

Install the Social Icons component from the Catalyst component library:

npm install '@pmi/catalyst-social-icons'

Overview

The Social Icons package provides official social media platform icons in both default and hover states. Each icon component is built on top of the BaseIcon component from @pmi/catalyst-icons, ensuring consistent sizing, coloring, and rendering across all applications.

Available Social Platforms

The package includes 18 icon components representing 9 major social media platforms:

• Facebook: FacebookDefault, FacebookHover
• Instagram: InstagramDefault, InstagramHover
• Twitter: TwitterDefault, TwitterHover
• LinkedIn: LinkedinDefault, LinkedinHover
• YouTube: YoutubeDefault, YoutubeHover
• TikTok: TiktokDefault, TiktokHover
• WhatsApp: WhatsAppDefault, WhatsAppHover
• Apple: AppleDefault, AppleHover
• Google: GoogleDefault, GoogleHover

Each platform has two states: Default (neutral/idle state) and Hover (highlighted/active state), enabling smooth interactive experiences.

Examples

Basic Usage

Display a social icon with default settings:

All Social Icons Gallery

Display all available social media icons:

API Reference

All social icon components accept the same props as BaseIcon from @pmi/catalyst-icons:

Size Scale Reference

Social icon sizes use CSS variable-based scaling:

• xs: 16px × 16px
• sm: 20px × 20px
• md: 24px × 24px
• lg: 32px × 32px
• xl: 40px × 40px (default, recommended for social icons)
• full: 100% of parent width and height

Available Social Icon Components

Import social icons using their platform name with state suffix:

import {
  // Facebook
  FacebookDefault,
  FacebookHover,

  // Instagram
  InstagramDefault,
  InstagramHover,

  // Twitter
  TwitterDefault,
  TwitterHover,

  // LinkedIn
  LinkedinDefault,
  LinkedinHover,

  // YouTube
  YoutubeDefault,
  YoutubeHover,

  // TikTok
  TiktokDefault,
  TiktokHover,

  // WhatsApp
  WhatsAppDefault,
  WhatsAppHover,

  // Apple
  AppleDefault,
  AppleHover,

  // Google
  GoogleDefault,
  GoogleHover,
} from '@pmi/catalyst-social-icons';

Usage Patterns

Default vs Hover States

• Default: Use for neutral/idle state with color="primary" or theme colors
• Hover: Use for highlighted/active state with color="original" to preserve platform brand colors

Interactive Pattern

For smooth hover transitions, layer both states with opacity transitions:

<a className="group relative size-10">
  {/* Hover state (hidden by default, shown on hover) */}
  <PlatformHover
    size="full"
    color="original"
    className="absolute opacity-0 group-hover:opacity-100 transition-opacity"
  />
  {/* Default state (shown by default, hidden on hover) */}
  <PlatformDefault
    size="full"
    color="primary"
    className="absolute opacity-100 group-hover:opacity-0 transition-opacity"
  />
</a>

Color Recommendations

• Default State: Use color="primary" for brand consistency
• Hover State: Use color="original" to show platform brand colors
• Dark Backgrounds: Use color="white" for default states
• Themed Applications: Use theme-aware colors like color="inherit"

Accessibility

All social icon components are built with accessibility in mind:

WCAG 2.1 AA Compliance

• Semantic Links: Always wrap icons in <a> tags with proper href attributes
• Descriptive Labels: Provide aria-label on links with platform name
• Keyboard Navigation: Icons are focusable when wrapped in interactive elements
• Target Size: Minimum 40px × 40px tap target (use size="xl" or larger)
• Color Contrast: Default states meet contrast requirements, hover states use platform colors

Best Practices

// ✅ Good: Icon in link with descriptive label
<a
  href="https://facebook.com"
  target="_blank"
  rel="noopener noreferrer"
  aria-label="Follow us on Facebook"
>
  <FacebookDefault size="xl" color="primary" />
</a>

// ✅ Good: Interactive hover with proper semantics
<a
  href="https://twitter.com"
  className="group relative size-12"
  aria-label="Follow us on Twitter"
>
  <TwitterHover
    size="full"
    color="original"
    className="absolute opacity-0 group-hover:opacity-100 transition-opacity"
  />
  <TwitterDefault
    size="full"
    color="primary"
    className="absolute opacity-100 group-hover:opacity-0 transition-opacity"
  />
</a>

// ✅ Good: Share button with descriptive label
<button aria-label="Share on WhatsApp">
  <WhatsAppDefault size="xl" color="primary" />
</button>

// ❌ Avoid: Icon without semantic context
<div>
  <FacebookDefault size="xl" />
</div>

Testing Considerations

Social icon components include data-testid support for integration testing:

<FacebookDefault data-testid="facebook-icon" size="xl" color="primary" />

Design Tokens

Social icons use the following design tokens from the Catalyst theme:

Size Tokens

• --scale-16: Extra small (xs)
• --scale-20: Small (sm)
• --scale-24: Medium (md)
• --scale-32: Large (lg)
• --scale-40: Extra large (xl) - recommended for social icons
• Custom sizing via parent container for full size

Color Tokens

• --icon-primary: Primary brand color (recommended for default states)
• --icon-secondary: Secondary color
• --icon-white: White/light (for dark backgrounds)
• --icon-inverted: Inverted theme color
• --icon-neutral-soft: Soft neutral
• Platform brand colors embedded in Hover variants (use color="original")

Technical Details

Component Generation

Social icon components are auto-generated from SVG assets. Do not modify icon component files directly. Any changes should be made in the build script at ~/process-packages-assets.cjs.

Bundle Optimization

Each social icon component is exported individually, enabling tree-shaking. Import only the icons you need to minimize bundle size:

// ✅ Optimal: Tree-shakeable imports
import { FacebookDefault, FacebookHover, TwitterDefault } from '@pmi/catalyst-social-icons';

// ⚠️ Avoid: Wildcard imports prevent tree-shaking
import * as SocialIcons from '@pmi/catalyst-social-icons';

SVG Rendering

Social icons use react-inlinesvg for SVG rendering, which:

• Enables runtime color manipulation for default states
• Preserves platform brand colors in hover states
• Ensures unique IDs for multiple instances
• Supports CSS custom properties for theming
• Maintains crisp rendering at all sizes

Hover State Implementation

Hover states use absolute positioning and opacity transitions for smooth interactions:

// Parent: relative positioning with fixed size
<div className="group relative size-12">
  {/* Hover: absolute, hidden by default */}
  <IconHover className="absolute opacity-0 group-hover:opacity-100 transition-opacity" />
  {/* Default: absolute, visible by default */}
  <IconDefault className="absolute opacity-100 group-hover:opacity-0 transition-opacity" />
</div>

Platform Guidelines

Social Media Platform Colors

When using color="original" on hover states, icons display official platform brand colors:

• Facebook: Blue (#1877F2)
• Instagram: Gradient (Purple to Orange)
• Twitter: Blue (#1DA1F2)
• LinkedIn: Blue (#0A66C2)
• YouTube: Red (#FF0000)
• TikTok: Black/Pink
• WhatsApp: Green (#25D366)
• Apple: Black
• Google: Multi-color

External Links Best Practices

When linking to social media platforms:

<a
  href="https://platform.com"
  target="_blank" // Open in new tab
  rel="noopener noreferrer" // Security best practice
  aria-label="Follow us on Platform"
>
  <PlatformDefault size="xl" color="primary" />
</a>

Related Components

• Icons - Base icon component system that social icons extend
• Flags - Country and territory flag assets
• Logos - Official PMI brand logos
• Link - Link component for navigation
• Button - Button component for interactive elements

See Also

• BaseIcon Component Documentation
• Accessibility Best Practices
• Design Tokens Documentation
• Social Media Best Practices