NYYU Logo
APIProfile

Update Avatar Set

Customize user avatar appearance with modular component-based updates for personalization

🎨 CUSTOMIZATION

Update Avatar Set

Customize avatar appearance with modular component-based updates for complete personalization control.

User Feature

This mutation is accessible to all authenticated users for personalizing their avatar appearance.

Overview

The updateAvatarSet mutation enables users to customize their avatar by updating individual components grouped by categories. This is typically called when users save changes from the avatar customization interface (dress-up modal).


GraphQL Schema

mutation {
  updateAvatarSet(
    components: [AvatarSetInput]!
  ): [AvatarSet]
}

Input Type

AvatarSetInput

groupId
String - The avatar component group identifier (e.g., "hair", "accessories", "clothing")
compId
String (UUID) - The unique component ID to apply to this group

Parameters

components

Required

[AvatarSetInput]

An array of avatar component selections, each specifying a group and the component to apply to that group.

Example Structure:

[{groupId: "hair", compId: "uuid-123"}, {groupId: "eyes", compId: "uuid-456"}]


Return Value

Success Response

Returns an array of [AvatarSet] objects representing the updated avatar component configuration.

AvatarSet Object:
groupId: String - Component group identifier
compId: String - Applied component UUID

Example Usage

Request

mutation UpdateUserAvatar {
  updateAvatarSet(
    components: [
      {
        groupId: "hair"
        compId: "550e8400-e29b-41d4-a716-446655440001"
      }
      {
        groupId: "accessories"
        compId: "550e8400-e29b-41d4-a716-446655440002"
      }
      {
        groupId: "clothing"
        compId: "550e8400-e29b-41d4-a716-446655440003"
      }
    ]
  ) {
    groupId
    compId
  }
}

Response

{
  "data": {
    "updateAvatarSet": [
      {
        "groupId": "hair",
        "compId": "550e8400-e29b-41d4-a716-446655440001"
      },
      {
        "groupId": "accessories",
        "compId": "550e8400-e29b-41d4-a716-446655440002"
      },
      {
        "groupId": "clothing",
        "compId": "550e8400-e29b-41d4-a716-446655440003"
      }
    ]
  }
}

Avatar Updated

Successfully updated 3 avatar components. Changes are immediately visible across the platform.


Component Group Examples

💇

Hair Group

groupId: hair

Hairstyles, colors, and hair accessories

👁️

Eyes Group

groupId: eyes

Eye shapes, colors, and expressions

👔

Clothing Group

groupId: clothing

Shirts, outfits, and costumes

💍

Accessories Group

groupId: accessories

Jewelry, glasses, and other items

🎭

Face Group

groupId: face

Face shape, skin tone, and features

🎨

Other Group

groupId: other

Background, effects, and special items


Implementation Flow

Avatar Customization Process

🎨

Open Dress-up
User clicks customize

🖱️

Select Components
Browse & choose items

💾

Save Changes
Update avatar set

Implementation Example

Dress-up Modal Integration

// Example: Avatar customization with live preview
function AvatarCustomizer() {
  const [selectedComponents, setSelectedComponents] = useState([]);

  const handleComponentSelect = (groupId, compId) => {
    // Update local state for preview
    setSelectedComponents(prev => {
      const filtered = prev.filter(c => c.groupId !== groupId);
      return [...filtered, { groupId, compId }];
    });
  };

  const saveAvatarChanges = async () => {
    try {
      const result = await graphqlClient.mutate({
        mutation: gql`
          mutation UpdateAvatar($components: [AvatarSetInput]!) {
            updateAvatarSet(components: $components) {
              groupId
              compId
            }
          }
        `,
        variables: {
          components: selectedComponents
        }
      });

      console.log("Avatar updated:", result.data.updateAvatarSet);
      showSuccessMessage("Avatar saved successfully!");
      closeModal();
    } catch (error) {
      console.error("Failed to update avatar:", error);
      showErrorMessage("Failed to save avatar changes");
    }
  };

  return (
    <div className="avatar-customizer">
      <AvatarPreview components={selectedComponents} />
      <ComponentSelector onSelect={handleComponentSelect} />
      <button onClick={saveAvatarChanges}>Save Avatar</button>
    </div>
  );
}

Use Cases

🎨

Personal Expression

Allow users to express individuality through customizable avatar components and unique style combinations

🎁

Unlockable Content

Reward users with exclusive avatar components for achievements, milestones, or special events

🎉

Seasonal Updates

Enable themed avatar components for holidays, events, or limited-time promotions

👥

Social Identity

Create distinctive visual identity for user profiles, chat, leaderboards, and community features


Best Practices

🔍 Component Validation

Validate component IDs exist before submitting to prevent errors from deleted or invalid components

👁️ Live Preview

Implement real-time preview in the UI before saving to improve user experience and reduce mistakes

💾 Batch Updates

Update all changed components in a single mutation rather than multiple calls for better performance

🎯 Group Consistency

Ensure each group appears only once in the components array to avoid conflicts or undefined behavior

🔄 State Management

Maintain local state for the customization UI and only persist changes when user explicitly saves