Build A Production Ready AI Headshot Generator | React, TailwindCSS, Cloudinary

Key Concepts

• Cloudinary: A cloud-based image and video management service used for hosting, transforming, and generating AI-based image modifications.
• Generative AI Transformations: Utilizing Cloudinary’s AI capabilities (e.g., generativeReplace, generativeBackgroundReplace) to modify image content based on text prompts.
• React Hooks: Custom hooks (e.g., useHeadshot) to manage complex state logic, such as upload status, progress tracking, and image transformation states.
• Tailwind CSS & cn Utility: A utility-first CSS framework combined with clsx and tailwind-merge to handle dynamic class names and responsive styling.
• XHR (XMLHttpRequest): Used for manual file uploads to track real-time progress percentages, which is necessary for custom UI feedback.
• React Dropzone: A library for implementing drag-and-drop file upload functionality.
• Advanced Image Component: A Cloudinary-provided React component that handles lazy loading, responsive resizing, and accessibility.

---

1. Project Architecture and Setup

The application is a single-page React application built with Vite and TypeScript. The project is structured into:

• Pages: Contains the main Home component.
• Components: Modular UI elements like Hero, UploadCard, TransformationGrid, and ExportActions.
• Hooks: Logic for managing the AI headshot generation lifecycle.
• Lib/Utils: Helper functions for Tailwind class merging and Cloudinary transformation logic.

Setup Steps:

1. Initialize the project using npx create-cloudinary-react.
2. Configure an Unsigned Upload Preset in the Cloudinary dashboard (Settings > Upload) to allow browser-based uploads without server-side secrets.
3. Install dependencies: lucide-react (icons), clsx, tailwind-merge, and react-dropzone.

---

2. Image Upload and Progress Tracking

To provide a professional user experience, the app tracks upload progress manually rather than relying on a black-box widget for the initial upload:

• Methodology: An async function uploadImageToCloudinary uses the XMLHttpRequest object.
• Progress Logic: By adding an event listener to xhr.upload.addEventListener('progress', ...), the app calculates the percentage: (event.loaded / event.total) * 100.
• State Management: The useHeadshot hook tracks uploadStatus (Idle, Uploading, Success, Error) and progress (number).

---

3. AI Image Transformations

The core feature involves transforming a user's selfie into a professional headshot using Cloudinary’s generative AI.

• Transformation Chain: A sequence of operations is applied to the image:
  • Resizing: fill mode with a 4:5 aspect ratio (600x750px).
  • Gravity: autoGravity to ensure the subject remains centered.
  • Generative AI: generativeReplace is used to swap casual clothing for a "professional navy suit," and generativeBackgroundReplace is used to place the subject in a "modern corporate office."
• Implementation: Transformations are defined in transformations.ts and applied via the Cloudinary SDK.

---

4. UI/UX Features

• Drag-and-Drop: Implemented via useDropzone, with visual feedback (e.g., changing border colors) when a file is dragged over the drop zone.
• Transformation Grid: Displays multiple AI-generated variations. Users can select a style, which updates the selectedPresetID state.
• Before/After Preview: A side-by-side comparison using the AdvancedImage component, which includes a "blur" placeholder effect while the high-resolution image loads.
• Export Actions: Users can download the result in different formats (JPEG, PNG, WEBP), open the image in a new tab, or copy the direct URL to the clipboard.

---

5. Key Code Snippets & Logic

• The cn Utility: Used to handle conditional Tailwind classes:

  export function cn(...inputs: ClassValue[]) {
    return twMerge(clsx(inputs));
  }
  

• Handling Export URLs: Because the SDK is used for previews, exporting requires manually building a URL that matches the transformation chain:

  // Logic involves stripping version prefixes and appending the 
  // transformation string to the base Cloudinary URL.
  

---

Synthesis/Conclusion

The project demonstrates that modern AI product development is less about calling a simple API and more about orchestrating the user experience. By combining Cloudinary’s powerful generative AI with a robust React frontend, the application provides a seamless flow: upload, process, preview, and export. The use of custom hooks and modular components ensures the code remains maintainable, while the manual XHR implementation provides the granular control needed for a professional-grade UI.