BlazeSlider Props Reference

Full prop tables for every sub-component. Types live in app/components/BlazeSlider/lib/types.d.ts. For usage patterns see Simple + Composable Mode.

---

BlazeSlider

The root component. Accepts BlazeSliderConfig + either simple-mode or composable-mode props. All BlazeSliderConfig props apply in both modes.

BlazeSliderConfig — layout & behavior

Prop	Type	Default	Description
slidesToShow	number	1	Slides visible in the viewport at once.
slidesToScroll	number	1	Slides advanced per prev/next press. Setting this > 1 means slider.next(N) / slider.prev(N) advance by states, not slides — affects initialSlide mapping (see hook.md).
slideGap	string	'12px'	Gap between slides — any CSS length unit (px, rem, %).
minSlideWidth	string	—	Optional floor on each slide's width. When set, buildScopedCSS overrides --slide-width to this value and sizes slides to width: max-content; min-width: <floor>. Use for tight strips (e.g. a color bar) where a long label should widen its own slide rather than be clipped. Don't use on product carousels — blaze snaps by --slide-width so dragging drifts when slides are max-content width.
loop	boolean	false	Infinite loop — wraps the track by physically reordering DOM nodes. isAtStart / isAtEnd are always false in loop mode (buttons are never disabled).
draggable	boolean	true	Enable drag/swipe gestures.
initialSlide	number	0	Zero-based index of the slide to show on mount. Navigates instantly (no transition). Set slidesToScroll: 1 if you need 1:1 index mapping — slider.next(N) advances by states, so initialSlide: 3 with slidesToScroll: 5 would jump 15 slides.
onSlideChange	(activeIndex: number) => void	—	Fires after each slide transition with the new active (leftmost-visible) index.
breakpoints	Record<string, MediaConfig>	—	Responsive overrides keyed by media query string. Each value is a MediaConfig that accepts any subset of the layout props above. Applied in CSS cascade order — mobile-first or desktop-first both work. See blaze-slider docs for advanced targets (orientation, reduced-motion, etc.).
enableAutoplay	boolean	false	Auto-advance slides on an interval.
autoplayInterval	number	3000	Milliseconds between auto-advances. Only relevant when enableAutoplay is true.
stopAutoplayOnInteraction	boolean	false	Permanently stop autoplay after the first user interaction.
pauseAutoplayOnHover	boolean	true	Pause autoplay on mouseenter / focusin, resume on mouseleave / focusout.
transitionDuration	number	500	Slide transition duration in milliseconds.
transitionTimingFunction	string	'ease'	CSS easing for the transition. Accepts 'ease', 'linear', or any cubic-bezier(...) string.

Shared layout props

Prop	Type	Default	Description
headingTitle	string	'Carousel'	Screen-reader heading for the carousel region (aria-labelledby). Rendered as a visually-hidden <p>.
headingRole	number	—	When provided, adds role="heading" + aria-level={headingRole} to the heading element. Range 1–6. Match the surrounding heading hierarchy.
containerClassname	string	—	Classes applied to the inner blaze-container div (the direct parent of buttons + track).
className	string	—	Classes on the outermost carousel <div>.
style	CSSProperties	—	Inline styles on the outermost <div>.

Simple-mode-only props

Only valid when slides + slideRenderer are passed (simple mode).

Prop	Type	Default	Description
slides	ReadonlyArray<T>	required	Data items — one BlazeSlide is generated per entry.
slideRenderer	(item: T, index: number) => ReactNode	required	Render function for each item. Does not receive isVisible — drop into composable + BlazeTrack renderer mode if you need it.
hideButtons	boolean	false	Hides prev/next buttons visually but keeps them keyboard-focusable (opacity-0, pointer-events-none, revealed on focus). Use instead of display:none to preserve keyboard accessibility.
buttonProps	SimpleButtonProps	—	Forwarded to both prev + next BlazeButton instances. Accepts any BlazeButtonProps except direction (set internally).
trackProps	SimpleTrackProps	—	Forwarded to BlazeTrack. Accepts any BlazeTrackProps except enableAutoplay and children (set internally).
slideProps	SimpleSlideProps	—	Forwarded to every generated BlazeSlide. Accepts any BlazeSlideProps except index and children (set internally).

---

BlazeTrack

Renders the .blaze-track-container + .blaze-track DOM nodes that blaze-slider requires. Supports two sub-modes selected at runtime by the presence of slideRenderer.

Prop	Type	Default	Description
className	string	—	Classes on the outer .blaze-track-container div. Use for horizontal inset (e.g. mx-2 md:mx-6) so buttons can overlap the track edge.
staticClassname	string	—	Classes applied to .blaze-track only when isStatic is true (i.e. total slides ≤ slidesToShow). Use to center a short list that doesn't fill the track.
enableAutoplay	boolean	false	When true, sets aria-live="off" to suppress noisy screen-reader announcements during auto-advance. Match this to BlazeSlider's enableAutoplay.

Children mode — pass <BlazeSlide> nodes directly as children. Full composition control but you manage keys and slide rendering yourself.

Renderer mode — pass items + slideRenderer. BlazeTrack maps items to <BlazeSlide> and resolves isVisible from context on your behalf, so you don't need a wrapper component just to read the provider.

Renderer-mode prop	Type	Default	Description
items	ReadonlyArray<T>	—	Items to map into slides.
slideRenderer	(item: T, index: number, isVisible: boolean) => ReactNode	—	Render function. isVisible is visibleIndices.has(index) — use it to set tabIndex on interactive slide content.
getSlideKey	(item: T, index: number) => React.Key	index	Stable key getter. Always provide this to avoid [object Object] keys when items are objects.
slideProps	Partial<Omit<BlazeSlideProps, 'index' | 'children'>>	—	Props forwarded to every generated BlazeSlide (e.g. className, tag).

---

BlazeSlide

Wraps each slide's content. Intentionally never re-renders on context changes — visibility, aria-hidden, and tabIndex are managed via direct DOM writes in syncSlideDOM. Do not make this component read BlazeSlideContext.

Prop	Type	Default	Description
index	number	required	Position in the track. Used as data-slide-index so blaze-slider and syncSlideDOM can locate this slide. Must be stable and match the item's array position.
tag	keyof JSX.IntrinsicElements	'div'	HTML element to render as the slide root. Use tag="li" when the track is a <ul>, tag="article" for content cards, etc.
className	string	—	Additional classes on the slide root. [content-visibility:auto] is always applied — don't remove it.
children	ReactNode	—	Slide content.

---

BlazeButton

prev / next navigation button. Reads slider state from BlazeSlideContext — must be placed inside a <BlazeSlider> but outside <BlazeTrack>. Returns null when isStatic (no navigation needed).

Prop	Type	Default	Description
direction	'prev' | 'next'	required	Which direction this button navigates. Controls aria-label and rotation (next button rotates 180°).
chevronSize	number	16	Width and height of the icon in px.
type	'default' | 'arrow'	'default'	Icon variant. 'default' uses ChevronIcon; 'arrow' uses CarouselArrow (a longer directional arrow).
iconColor	string	—	Color passed to the icon SVG. Defaults to currentColor.
disablePositioning	boolean	false	When false (default), applies absolute top-1/2 -translate-y-1/2 left-0/right-0 so buttons float over the track. Set true when you want to position buttons manually (e.g. inside a flex row above the track).
hideButtons	boolean	false	Visually hides the button (opacity-0, pointer-events-none) while keeping it keyboard-focusable. Mirrors the simple-mode hideButtons prop for composable usage.
onClick	() => void	—	Fires before the slide transition. Use for side effects (e.g. pausing a video).
analyticsEvent	CustomAnalyticsEvent	—	Analytics event key to publish on click via Hydrogen's useAnalytics().publish().
getAnalyticsData	(direction: 'prev' | 'next') => Record<string, unknown>	—	Returns the customData payload published with analyticsEvent. Receives the button's direction so one handler can serve both buttons.

---

CarouselCounter

Optional 1 / N slide indicator. Reads currentIndex and total from context — must be inside a <BlazeSlider>. No required props beyond totalSlides.

Prop	Type	Default	Description
totalSlides	number	required	Total slide count. Used to render the denominator.
className	string	—	Classes on the counter wrapper.

---

Breakpoint shape (MediaConfig)

Each value in the breakpoints record accepts any layout prop that can differ per viewport:

type MediaConfig = {
  slidesToShow?: number;
  slidesToScroll?: number;
  slideGap?: string;
  loop?: boolean;
  enableAutoplay?: boolean;
  autoplayInterval?: number;
  transitionDuration?: number;
  transitionTimingFunction?: string;
};

Keys are standard media query strings — '(min-width: 768px)', '(orientation: landscape)', '(prefers-reduced-motion: reduce)', etc. Applied in cascade order: later matches override earlier ones.

breakpoints={{
  '(min-width: 768px)': { slidesToShow: 4, slidesToScroll: 3 },
  '(min-width: 1280px)': { slidesToShow: 6, slidesToScroll: 5 },
}}