# Islands Overview

> Pre-built React components that hydrate client-side for interactive functionality in your Lexsis storefront.

Canonical URL: https://fa7e86e3d553:3005/islands

Islands are pre-built React components that handle interactive functionality.
Authors add them to page source with `<lx-island>` elements while surrounding
static HTML renders immediately.

Use islands for anything that needs JavaScript: add-to-cart buttons, carousels, accordions, popups. Use plain HTML + Tailwind for everything else.

## Authoring Syntax

```html
<lx-island name="BuyBox" hydrate="visible">
  <script type="application/json">
    { "productId": "gid://shopify/Product/123", "ctaText": "Add to Cart" }
  </script>
</lx-island>
```

| Part | Purpose |
|-----------|---------|
| `name` | Exact island name (case-sensitive) |
| JSON script child | Props object passed to the island |

Run `lexsis_pages` with action `compile` before saving. It validates
island names, props, structure, CSS, and JavaScript before the page is created.

> **Deprecated islands:** `BackToTop`, `Carousel`, `CartDrawer`, `Countdown`,
> `Marquee`, `StatCards`, and `Tabs` remain available for legacy pages but are
> excluded from new-page recommendations. See
> [Deprecated Islands](/islands/deprecated) for replacements and migration
> rules.

## Props Rules

1. The JSON script must parse to an object.
2. Use the exact props from `vibe://schema/island/{name}`.
3. Natural copy, including apostrophes and line breaks, is safe in source
   format because the compiler handles attribute escaping.
4. Use `hydrate="immediate|visible|idle|interaction"` only when needed.

## Constraints

- **Multiple BuyBoxes require a shared `syncKey`** — use one unique key per
  purchase group
- **Cart profiles have no authored cart section or enable flag** — Cart V2 is
  default; configure the resolved profile separately
- **No nested islands** — never put one `<lx-island>` inside another
- **Surrounding HTML renders immediately** — islands hydrate after page load

## Island Categories

### Page-authored commerce (21 islands)

| Island | Purpose |
|--------|---------|
| [BuyBox](/islands/commerce/buy-box) | Primary add-to-cart (variants, quantity, checkout) |
| [StickyBar](/islands/commerce/sticky-bar) | Fixed bottom bar (persistent CTA on scroll) |
| [QuantityBreaks](/islands/commerce/quantity-breaks) | Volume discount tiers |
| [ProductCarousel](/islands/commerce/product-carousel) | Horizontal scrolling product grid |
| [FeaturedCollectionStage](/islands/commerce/featured-collection-stage) | Editorial shared-stage collection showcase with active product details |
| [ShoppableVideoFeed](/islands/commerce/shoppable-video-feed) | Responsive shoppable reels, rails, and video grids |
| [QuickAdd](/islands/commerce/quick-add) | Lightweight add-to-cart for grids |
| [ProductGallery](/islands/commerce/product-gallery) | Eight-layout mixed-media PDP gallery with thumbnails, collages, grids, masonry, and lightbox |
| [ProductHero](/islands/commerce/product-hero) | Premium full-height hero gallery for PDP split layouts |
| [VariantSwatches](/islands/commerce/variant-swatches) | Visual option selector (color/size/image) |
| [VariantSelector](/islands/commerce/variant-selector) | Visual variant/option selector (swatches, dropdown, buttons) |
| [OptionResolver](/islands/commerce/option-resolver) | Invisible: resolves multi-axis options to variant |
| [BundleBuilder](/islands/commerce/bundle-builder) | Frequently Bought Together bundles |
| [BundleConfigurator](/islands/commerce/bundle-configurator) | Build-your-own boxes with slot limits, repeat quantities, and live bundle pricing |
| [InventoryIndicator](/islands/commerce/inventory-indicator) | Stock level badge (green/amber/red) |
| [DeliveryEstimate](/islands/commerce/delivery-estimate) | Estimated delivery + countdown to cutoff |
| [PaymentOptions](/islands/commerce/payment-options) | BNPL messaging (Klarna, Afterpay, etc.) |
| [PlanSelector](/islands/commerce/plan-selector) | Subscription plan cards and pricing state |
| [ProceedToCart](/islands/commerce/proceed-to-cart) | Full-page CTA that navigates to cart or checkout |
| [SubscriptionToggle](/islands/commerce/subscription-toggle) | Subscribe & Save toggle |
| [WishlistButton](/islands/commerce/wishlist-button) | Heart icon toggle for product wishlist/favorites |

### Cart (9 active + 1 legacy island)

Legacy Cart V1 (simple) and cart profiles (composable) — [see full Cart section](/islands/cart)

| Island | Version | Purpose |
|--------|---------|---------|
| [CartDrawer](/islands/cart/cart-drawer) | **Deprecated / Legacy** | Monolithic slide-out cart |
| [DrawerShell](/islands/cart/drawer-shell) | Cart profile | Multi-mode container (drawer, bottom-sheet, modal, fullscreen) |
| [CartLines](/islands/cart/cart-lines) | Cart profile | Line items with qty/remove |
| [CartSummary](/islands/cart/cart-summary) | Cart profile | Subtotal, taxes, total |
| [CartCheckoutButton](/islands/cart/cart-checkout-button) | Cart profile | Checkout CTA |
| [CartProgressBar](/islands/cart/cart-progress-bar) | Cart profile | Free shipping progress |
| [CartDiscountInput](/islands/cart/cart-discount-input) | Cart profile | Promo code input |
| [CartCrossSell](/islands/cart/cart-cross-sell) | Cart profile | In-cart cross-sell/upsell recommendations |
| [CartRewardProgress](/islands/cart/cart-reward-progress) | Cart profile | Reward milestones with automatic gift and discount reconciliation |
| [CartCoupons](/islands/cart/cart-coupons) | Cart profile | Curated coupons, applied savings, and manual code entry |

### Social Proof (3 active islands)

| Island | Purpose |
|--------|---------|
| [ReviewCarousel](/islands/social-proof/review-carousel) | Scrolling review cards |
| [SocialProofPopup](/islands/social-proof/social-proof-popup) | Recent activity toast notifications |
| [ReviewList](/islands/social-proof/review-list) | Filterable or paginated review list |

### Content and media (8 active islands)

| Island | Purpose |
|--------|---------|
| [VideoPlayer](/islands/content/video-player) | Optimized video with lazy loading |
| [BeforeAfter](/islands/content/before-after) | Interactive comparison slider |
| [ImageZoom](/islands/content/image-zoom) | Hover/click-to-zoom viewer |
| [GalleryLightbox](/islands/content/gallery-lightbox) | Fullscreen lightbox overlay with scroll-snap viewer |
| [CountdownTimer](/islands/content/countdown-timer) | Countdown (sale end, launch, restock) |
| [FAQ](/islands/content/faq) | Accessible single-open or multiple-open accordion |
| [HeroMedia](/islands/commerce/hero-media) | Full-bleed background media (image, carousel, video with parallax/ken-burns) |
| [MediaCarousel](/islands/content/media-carousel) | Unified image/adaptive-video carousel using the shared media array contract |

### Engagement (5 islands)

| Island | Purpose |
|--------|---------|
| [EmailCapture](/islands/engagement/email-capture) | Email signup (inline/floating/banner) |
| [FunnelRuntime](/islands/engagement/funnel-runtime) | Server-resolved quizzes, offers, and multi-step capture |
| [Modal](/islands/engagement/modal) | Generic modal/popup (delay, scroll, exit-intent, click triggers) |
| [SizeGuide](/islands/engagement/size-guide) | Size chart modal/drawer |
| [IngredientExplorer](/islands/engagement/ingredient-explorer) | Interactive ingredient breakdown |

### Navigation (5 active islands)

| Island | Purpose |
|--------|---------|
| [SiteHeader](/islands/navigation/site-header) | Combined announcement + navbar (preferred for sticky headers) |
| [Navbar](/islands/navigation/navbar) | Top navigation with mobile hamburger |
| [AnnouncementBar](/islands/navigation/announcement-bar) | Top promotional banner |
| [Footer](/islands/navigation/footer) | Site footer with links, social icons, newsletter |
| [MobileMenu](/islands/navigation/mobile-menu) | Full-screen mobile drawer |

## Event System

Islands communicate via custom DOM events. Key flows:

| Event | Emitted by | Listened by |
|-------|-----------|-------------|
| `variant:changed` | VariantSwatches, VariantSelector, OptionResolver | BuyBox, ProductGallery, ProductHero, InventoryIndicator, PaymentOptions |
| `subscription:changed` | SubscriptionToggle | BuyBox |
| `bundle:add` | BundleBuilder, BundleConfigurator | Bundle analytics and custom listeners |
| `inventory:updated` | Inventory runtime | VariantSwatches, VariantSelector, StickyBar, BuyBox |

To enable listening, set `listenForEvents: true` in the listener island's props.

## Page Type Recommendations

| Page Type | Key Islands |
|-----------|-------------|
| **PDP** | BuyBox + ProductGallery + ReviewCarousel + StickyBar + cart profile |
| **Landing** | EmailCapture + ReviewCarousel + FAQ + SocialProofPopup |
| **Homepage** | ProductCarousel + AnnouncementBar + Navbar |
| **Collection** | ProductCarousel + QuickAdd + ReviewCarousel |

## Common Combinations

### Minimal PDP

```
ProductGallery + BuyBox (side-by-side on desktop)
ReviewCarousel
FAQ
StickyBar
```

### Conversion Landing Page

```
Hero (plain HTML)
Benefits (plain HTML grid)
BeforeAfter or IngredientExplorer
ReviewCarousel
BuyBox or EmailCapture
FAQ
Modal (when the brief requires a popup)
```