Grasco
Profile Picture UI

ProfilePicture (React)

React wrapper for the profile picture component with type-safe props

The ProfilePicture React component is a type-safe wrapper around the <profile-picture> web component. It provides camelCase props, object prop handling, event callbacks, and SSR safety.

For the Web Component (HTML) documentation with kebab-case attributes, see ProfilePicture.

Import

import { ProfilePicture, setCdnBaseUrl } from '@grasco/profile-picture';
// or
import { ProfilePicture, setCdnBaseUrl } from '@grasco/profile-picture/react';

Core Props

PropTypeDefaultDescription
srcstring—Image source URL
altstring''Alt text for accessibility
extCustomerIdstring—External customer ID for CDN image loading
imageMode'transparent' | 'original''original'CDN image mode

When extCustomerId is provided, the component fetches the image from the configured CDN instead of using src directly.

Basic Usage

<ProfilePictureextCustomerId="demo-user-1769431807927-pd9dtmn1"alt="Kerry Nicholson"size="lg"variant="circle"/>

Sizing

PropTypeDefaultDescription
sizeSize | number'md'Predefined size or custom pixel value

Size Map

TokenPixels
2xs20px
xs24px
sm32px
md40px
lg48px
xl64px
2xl80px
3xl120px
<ProfilePicture extCustomerId="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" size="xs" /><ProfilePicture extCustomerId="demo-user-1769429613186-q8x65t0" alt="Sarah Chen" size="md" /><ProfilePicture extCustomerId="demo-user-1769430228786-ompo3g1" alt="Emma Liu" size="xl" /><ProfilePicture extCustomerId="demo-user-1769430441537-fs5i098" alt="Marcus Webb" size={120} />

Visual

PropTypeDefaultDescription
variant'circle' | 'rounded' | 'squircle' | 'square''circle'Shape variant
shadow'none' | 'sm' | 'md' | 'lg' | 'glow''sm'Shadow preset
<ProfilePicture extCustomerId="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" size="xl" variant="circle" /><ProfilePicture extCustomerId="demo-user-1769429613186-q8x65t0" alt="Sarah Chen" size="xl" variant="rounded" /><ProfilePicture extCustomerId="demo-user-1769430228786-ompo3g1" alt="Emma Liu" size="xl" variant="squircle" /><ProfilePicture extCustomerId="demo-user-1769430441537-fs5i098" alt="Marcus Webb" size="xl" variant="square" />

Border

PropTypeDefaultDescription
borderbooleanfalseEnable border
borderWidth1 | 2 | 3 | 4 | 5 | 6 | 82Border width in pixels
borderColorstring'#ffffff'Border color
<ProfilePicture extCustomerId="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" size="xl" border borderWidth={2} borderColor="#ffffff" /><ProfilePicture extCustomerId="demo-user-1769429613186-q8x65t0" alt="Sarah Chen" size="xl" border borderWidth={4} borderColor="#6366f1" /><ProfilePicture extCustomerId="demo-user-1769430228786-ompo3g1" alt="Emma Liu" size="xl" border borderWidth={6} borderColor="#ec4899" />

Transform

PropTypeDefaultDescription
rotationnumber0Rotation angle in degrees
zoomnumber1.2Zoom level (values greater than 1 zoom in)
<ProfilePicture extCustomerId="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" size="xl" rotation={15} /><ProfilePicture extCustomerId="demo-user-1769429613186-q8x65t0" alt="Sarah Chen" size="xl" rotation={-10} zoom={1.5} />

Background

PropTypeDefaultDescription
bgColorstring—Background color (any valid CSS color)
bgGradientstring—Background gradient (any valid CSS gradient)

These props are visible when the image has transparency or has not yet loaded.

<ProfilePicture extCustomerId="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" size="xl" imageMode="transparent" bgColor="#6366f1" /><ProfilePicture extCustomerId="demo-user-1769429613186-q8x65t0" alt="Sarah Chen" size="xl" imageMode="transparent"bgGradient="linear-gradient(135deg, #667eea 0%, #764ba2 100%)"/>

Glow Effect

The glow prop accepts a GlowConfig object.

PropertyTypeDefaultDescription
colorstringborder colorGlow color
intensitynumber—Intensity from 0 to 1
animatebooleanfalseAnimate the glow with a pulsing effect
<ProfilePicture extCustomerId="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" size="xl"glow={{ color: '#6366f1', intensity: 0.8 }}/><ProfilePicture extCustomerId="demo-user-1769429613186-q8x65t0" alt="Sarah Chen" size="xl"glow={{ color: '#ec4899', intensity: 0.8, animate: true }}/>

Ring Effect

The ring prop accepts a RingConfig object.

PropertyTypeDefaultDescription
showboolean—Show ring
colorstring—Ring color
gradientstring[]—Gradient colors for a multi-color ring
widthnumber3Ring width in pixels
gapnumber3Gap between the ring and the avatar
animatebooleanfalseAnimate the ring
progressnumber—Progress percentage from 0 to 100
emptyColorstring—Color for the unfilled portion of a progress ring
// Solid ring<ProfilePicture extCustomerId="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" size="xl"ring={{ show: true, color: '#6366f1', width: 3 }}/>// Gradient ring with animation<ProfilePicture extCustomerId="demo-user-1769429613186-q8x65t0" alt="Sarah Chen" size="xl"ring={{ show: true, gradient: ['#ec4899', '#8b5cf6', '#6366f1'], animate: true }}/>// Progress ring<ProfilePicture extCustomerId="demo-user-1769430228786-ompo3g1" alt="Emma Liu" size="xl"ring={{ show: true, progress: 75, color: '#10b981', emptyColor: '#374151' }}/>

Presence Indicator

The presence prop accepts a PresenceConfig object.

PropertyTypeDefaultDescription
status'online' | 'away' | 'busy' | 'offline' | 'dnd'—Current status
animatebooleanfalseShow animated ring around the indicator
thickness1 | 2 | 32Ring thickness

Status Colors

StatusColor
online#30D158
away#FFD60A
busy#FF453A
offline#8E8E93
dnd#FF453A
<ProfilePicture extCustomerId="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" size="xl"presence={{ status: 'online', animate: true }}/><ProfilePicture extCustomerId="demo-user-1769429613186-q8x65t0" alt="Sarah Chen" size="xl"presence={{ status: 'away' }}/><ProfilePicture extCustomerId="demo-user-1769430228786-ompo3g1" alt="Emma Liu" size="xl"presence={{ status: 'busy' }}/><ProfilePicture extCustomerId="demo-user-1769430441537-fs5i098" alt="Marcus Webb" size="xl"presence={{ status: 'dnd' }}/><ProfilePicture extCustomerId="demo-user-1769431068241-t5mkiym" alt="Alice Spark" size="xl"presence={{ status: 'offline' }}/>

Badge

The badge prop accepts a BadgeConfig object.

PropertyTypeDefaultDescription
contentstring | number—Text, number, or leave empty for a dot
positionPosition'bottom-right'Badge position
colorstring—Text or icon color
bgColorstring—Background color
borderRadiusstring'9999px'Border radius
pulsebooleanfalseEnable pulse animation
glowbooleanfalseEnable glow effect
maxnumber—Maximum value (displays 99+ if exceeded)
iconstring—Icon before content (emoji or Unicode character)

Position Options

top-left | top-center | top-right | bottom-left | bottom-center | bottom-right

// Notification count with pulse<ProfilePicture extCustomerId="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" size="xl"badge={{ content: 5, position: 'top-right', bgColor: '#ef4444', pulse: true }}/>// Status dot<ProfilePicture extCustomerId="demo-user-1769429613186-q8x65t0" alt="Sarah Chen" size="xl"badge={{ position: 'bottom-right', bgColor: '#10b981' }}/>// With icon<ProfilePicture extCustomerId="demo-user-1769430228786-ompo3g1" alt="Emma Liu" size="xl"badge={{ icon: '✓', content: 'Verified', bgColor: '#3b82f6' }}/>

Loading

PropTypeDefaultDescription
loading'lazy' | 'eager''lazy'Image loading strategy
placeholder'shimmer' | 'pulse' | 'blur' | 'skeleton' | 'none''shimmer'Placeholder animation while loading
placeholderColorstring'#f3f4f6'Placeholder background color
<ProfilePicture
  extCustomerId="demo-user-1769431807927-pd9dtmn1"
  alt="Kerry Nicholson"
  loading="eager"
  placeholder="blur"
  placeholderColor="#e5e7eb"
/>

Fallback

PropTypeDefaultDescription
fallbackstring—Custom fallback text
fallbackMode'initials' | 'gradient'—Fallback display mode

When no image is available, the component renders a fallback:

  • initials mode generates initials from the alt text and displays them on a colored background.
  • gradient mode shows a unique gradient derived from the name, providing a visually distinct placeholder for each user.
// Initials fallback<ProfilePicture alt="Jane Smith" size="xl" fallbackMode="initials" />// Gradient fallback<ProfilePicture alt="Bob Wilson" size="xl" fallbackMode="gradient" />// Custom fallback text<ProfilePicture alt="Jane Smith" size="xl" fallback="JS" fallbackMode="initials" />

Interaction

The interactive prop accepts an InteractionConfig object.

PropertyTypeDefaultDescription
hoverablebooleanfalseEnable hover effects (scale and brightness change)
pressablebooleanfalseEnable press/click effects
focusablebooleanfalseShow a focus ring for keyboard navigation
cursor'pointer' | 'default' | 'zoom-in'—Cursor style on hover
<ProfilePicture extCustomerId="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" size="xl"interactive={{ hoverable: true, pressable: true, cursor: 'pointer' }}onClick={(detail) => console.log('clicked', detail)}/>

React-Specific Props

PropTypeDescription
classNamestringCSS class name
styleReact.CSSPropertiesInline styles

Static Methods

MethodSignatureDescription
setCdnBaseUrl(url: string) => voidSet the global CDN base URL for all instances
getCdnBaseUrl() => stringGet the current CDN base URL
import { setCdnBaseUrl } from '@grasco/profile-picture';

// The default CDN base URL is https://api.propicture.app
// Override if needed:
setCdnBaseUrl('https://cdn.example.com');

Examples

Chat User

A typical avatar for a messaging app — online presence, notification badge, and clickable.

<ProfilePictureextCustomerId="demo-user-1769431807927-pd9dtmn1"alt="Kerry Nicholson"size="lg"presence={{ status: 'online', animate: true }}badge={{ content: 3, bgColor: '#ef4444', pulse: true }}interactive={{ hoverable: true, pressable: true, cursor: 'pointer' }}onClick={(detail) => console.log('Clicked:', detail)}/>

Social Profile

A social-media style avatar with a gradient story ring and a bordered frame.

<ProfilePictureextCustomerId="demo-user-1769429613186-q8x65t0"alt="Sarah Chen"size="xl"borderborderWidth={3}borderColor="#ffffff"ring={{ show: true, gradient: ['#ec4899', '#8b5cf6', '#6366f1'], animate: true }}/>

Verified Account

A squared avatar with a verification badge — common in admin panels or marketplace profiles.

<ProfilePictureextCustomerId="demo-user-1769430228786-ompo3g1"alt="Emma Liu"size="xl"variant="rounded"shadow="md"badge={{ icon: '✓', bgColor: '#3b82f6', position: 'bottom-right' }}/>

ProfilePictureGroup

Display a group of profile pictures with overlap, tooltips, and dropdown

ProfilePictureGroup (React)

React wrapper for displaying a group of profile pictures with overlap, tooltips, and dropdown

On this page

ImportCore PropsBasic UsageSizingSize MapVisualBorderTransformBackgroundGlow EffectRing EffectPresence IndicatorStatus ColorsBadgePosition OptionsLoadingFallbackInteractionReact-Specific PropsStatic MethodsExamplesChat UserSocial ProfileVerified Account