To AI Agent: Implement Mobile Horizontal Image Panning Component

1. Context & Objective

We are developing a travel application. We need to implement a mobile-first image viewer component. CRITICAL REQUIREMENT: When a user swipes/drags horizontally on mobile, the UI must NOT switch to the next image. Instead, it must smoothly scroll/pan horizontally to reveal the hidden, unexposed parts of the same wide/panoramic image.

2. Technical Stack & Scope

Target Platform: Mobile Web / Responsive (Touch-friendly).
Preferred Method: CSS-First approach utilizing Viewport Overflow (for optimal GPU performance and native inertia scrolling).
Avoid: Do NOT use global slider libraries (like standard Swiper/Slick) if they force image switching behavior.

3. UI/UX Specifications

A. DOM Structure

A wrapper/container acting as the "window view" (.image-pan-container).
The target wide/panoramic image (.image-pan-element).

B. CSS Rules & Constraints

Container (.image-pan-container):
- Must have a fixed width (e.g., 100vw or 100% of parent).
- Must set overflow-x: auto and overflow-y: hidden to enable horizontal touch scrolling only.
- Must enable smooth scrolling (scroll-behavior: smooth) and native touch momentum (-webkit-overflow-scrolling: touch).
- Crucial: Hide the native scrollbar across all major browsers (Webkit, Firefox, IE/Edge) to make it look like a native mobile app feature.
Image Element (.image-pan-element):
- Must fit the container's height perfectly (height: 100%).
- Width must be calculated automatically based on aspect ratio (width: auto).
- Must override any global framework styles: enforce max-width: none !important.
- Do NOT use object-fit: cover as it will crop the scrolling data.

4. Reference Code Blueprint

Use the following snippet as a baseline for your implementation:

<div class="image-pan-container">
  <img src="YOUR_PANORAMIC_IMAGE_URL" class="image-pan-element" alt="Panoramic View" />
</div>

/* Styling Architecture */
.image-pan-container {
  width: 100%;
  height: 400px; /* Adjust height based on project guidelines */
  overflow-x: auto;
  overflow-y: hidden;
  scroll-behavior: smooth;
  -webkit-overflow-scrolling: touch;
}

/* Hide scrollbars entirely */
.image-pan-container::-webkit-scrollbar {
  display: none;
}
.image-pan-container {
  -ms-overflow-style: none;
  scrollbar-width: none;
}

.image-pan-element {
  height: 100%;
  width: auto;
  max-width: none !important;
  display: block;
}

5. Acceptance Criteria
[ ] The wide photo fills the component height and overflows horizontally without distortion.

[ ] Users can smoothly swipe left/right with their fingers to view all details of the photo.

[ ] No desktop/mobile scrollbars are visible during the interaction.

[ ] Ensure max-width override is active so Tailwind or other CSS frameworks don't crush the image width to 100%.

2.9 KiB Raw Blame History