Carousel causes horizontal page overflow in width-constrained containers

[JakeLin]

The Carousel component causes horizontal page-level overflow when used inside width-constrained containers (e.g., max-width: 768px), resulting in an unwanted horizontal scrollbar.

Root Cause

The .emblaContainer class uses negative horizontal margins to implement the gap system:

.emblaContainer {
  display: flex;
  align-items: stretch;
  margin-left: calc(var(--carousel-gap, 0) / -2);   /* ← Negative margin */
  margin-right: calc(var(--carousel-gap, 0) / -2);  /* ← Negative margin */
  padding-left: var(--carousel-start-inset, 0);
}

While .emblaViewport has overflow: hidden, when the Carousel is placed in a width-constrained parent container, these negative margins push content outside the container boundaries, causing page-level horizontal overflow.

Reproduction

<div style={{ maxWidth: '768px', margin: '0 auto' }}>
  <Carousel gap="16px" align="start">
    <Card>Item 1</Card>
    <Card>Item 2</Card>
    <Card>Item 3</Card>
  </Carousel>
</div>

Result: Horizontal scrollbar appears at page level.

Current Workaround

Add overflow-x: hidden to parent containers:

.carousel-wrapper {
  overflow-x: hidden;
}

However, this requires users to know about the internal implementation detail and apply fixes at multiple container levels.

Suggested Fixes

1. Use CSS gap property instead of negative margins:

   .emblaContainer {
     display: flex;
     gap: var(--carousel-gap, 0);
   }

2. Add compensating padding to contain the negative margins:

   .emblaViewport {
     padding-left: calc(var(--carousel-gap, 0) / 2);
     padding-right: calc(var(--carousel-gap, 0) / 2);
   }

3. Document the requirement that parent containers must use overflow-x: hidden

Environment

• @ainativekit/ui version: 0.8.0
• Browser: Chrome/Safari/Firefox (affects all)
• Use case: ChatGPT widgets with constrained iframe widths

Expected Behavior

A self-contained component should handle its own overflow without requiring parent containers to apply overflow fixes.

[JakeLin]

Fixed in v0.9.0

The Carousel horizontal overflow issue has been resolved by replacing the negative margin gap implementation with the CSS gap property.

Changes:

• Carousel now uses standard CSS gap for spacing between slides
• Component is self-contained and doesn't cause page-level horizontal overflow
• No longer requires parent containers to apply overflow-x: hidden workarounds

Testing:
You can test the fix in Storybook under Composed Components → Carousels in the Edge Cases section, where there's a dedicated test showing the Carousel working correctly inside a max-width: 768px container.

Thank you for reporting this issue!