The Bento Stream Gallery is for displaying multiple similar pieces of content at a time along a horizontal axis. To implement a more customized UX, see
bento-base-carousel
.
Use Bento Stream Gallery as a web component (<bento-stream-gallery>
), or a Preact/React functional component (<BentoStreamGallery>
).
You must include each Bento component's required CSS library to guarantee proper loading and before adding custom styles. Or use the light-weight pre-upgrade styles available inline. See Layout and style.
The examples below demonstrate use of the <bento-stream-gallery>
web component.
[example preview="top-frame" playground="false"]
Install via npm:
npm install @ampproject/bento-stream-gallery
import '@ampproject/bento-stream-gallery';
[/example]
The example below contains an bento-stream-gallery
with three sections. The
expanded
attribute on the third section expands it on page load.
[example preview="top-frame" playground="false"]
<head>
<script async src="https://cdn.ampproject.org/bento.js"></script>
<script async src="https://cdn.ampproject.org/v0/bento-stream-gallery-1.0.js"></script>
<link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/amp-streamGallery-1.0.css">
</head>
<body>
<bento-stream-gallery>
<img src="img1.png">
<img src="img2.png">
<img src="img3.png">
<img src="img4.png">
<img src="img5.png">
<img src="img6.png">
<img src="img7.png">
</bento-stream-gallery>
<script>
(async () => {
const streamGallery = document.querySelector('#my-stream-gallery');
await customElements.whenDefined('bento-stream-gallery');
const api = await streamGallery.getApi();
// programatically expand all sections
api.next();
// programatically collapse all sections
api.prev();
// programatically go to slide
api.goToSlide(4);
})();
</script>
</body>
[/example]
Bento enabled components in standalone use are highly interactive through their API. The bento-stream-gallery
component API is accessible by including the following script tag in your document:
await customElements.whenDefined('bento-stream-gallery');
const api = await streamGallery.getApi();
next()
Moves the carousel forwards by number of slides visible.
api.next();
prev()
Moves the carousel backwards by number of slides visible.
api.prev();
goToSlide(index: number)
Moves the carousel to the slide specified by the index
argument.
Note: index
will be normalized to a number greater than or equal to 0
and less than the number of slides given.
api.goToSlide(0); // Advance to first slide.
api.goToSlide(length - 1); // Advance to last slide.
The Bento Stream Gallery component allows you to register and respond to the following events:
slideChange
This event is triggered when the index displayed by the carousel has changed.
The new index is available via event.data.index
.
streamGallery.addEventListener('slideChange', (e) => console.log(e.data.index))
Each Bento component has a small CSS library you must include to guarantee proper loading without content shifts. Because of order-based specificity, you must manually ensure that stylesheets are included before any custom styles.
<link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/amp-streamGallery-1.0.css">
Alternatively, you may also make the light-weight pre-upgrade styles available inline:
<style data-bento-boilerplate>
bento-stream-gallery {
display: block;
overflow: hidden;
position: relative;
}
</style>
Either "always"
, "auto"
, or "never"
, defaults to "auto"
. This determines if and when prev/next navigational arrows are displayed. Note: When outset-arrows
is true
, the arrows are shown "always"
.
always
: Arrows are always displayed.auto
: Arrows are displayed when the carousel has most recently received interaction via mouse, and not displayed when the carousel has most recently received interaction via touch. On first load for touch devices, arrows are displayed until first interaction.never
: Arrows are never displayed.
Either "around"
or undefined. This determines how extra space is allocated after displaying the calculated number of visible slides in the carousel. If "around"
, white space is evenly distributed around the carousel with justify-content: center
; otherwise, space is allocated to the right of the carousel for LTR documents and to the left for RTL documents.
Either true
or false
, defaults to true
. When true, the carousel will allow
the user to move from the first item back to the last item and visa versa. There
must be at least three slides present for looping to occur.
Either true
or false
, defaults to false
. When true, the carousel will display its arrows outset and on either side of the slides. Note that with outset arrows, the slide container will have an effective length of 100px less than the allotted space for its given container - 50px per arrow on either side. When false, the carousel will display its arrows inset and overlayed on top of the left and right edges of the slides.
A number, defaults to 0
. This determines how much of an additional slide to show (on one or both sides of the current slide) as an affordance to the user indicating the carousel is swipeable.
A number, defaults to 1
. Determines the minimum number of slides that should be shown at a given time. Fractional values can be used to make part of a(n) additional slide(s)
visible.
A number, defaults to Number.MAX_VALUE
. Determines the maximum number of slides that should be shown at a given time. Fractional values can be used to make part of a(n) additional slide(s) visible.
A number, defaults to 1
. Determines the minimum width of each item, used to resolve how many whole items can be shown at once within the overall width of the gallery.
A number, defaults to Number.MAX_VALUE
. Determines the maximum width of each item, used to resolve how many whole items can be shown at once within the overall width of the gallery.
Either start
or center
. When start aligning, the start of a slide (e.g. the
left edge, when horizontal aligning) is aligned with the start of a carousel.
When center aligning, the center of a slide is aligned with the center of a
carousel.
Either true
or false
, defaults to true
. Determines whether or not the
carousel should snap on slides when scrolling.
You may use the bento-stream-gallery
element selector to style the streamGallery
freely.
The examples below demonstrates use of the <BentoStreamGallery>
as a functional component usable with the Preact or React libraries.
[example preview="top-frame" playground="false"]
Install via npm:
npm install @ampproject/bento-stream-gallery
import React from 'react';
import { BentoStreamGallery } from '@ampproject/bento-stream-gallery/react';
import '@ampproject/bento-stream-gallery/styles.css';
function App() {
return (
<BentoStreamGallery>
<img src="img1.png">
<img src="img2.png">
<img src="img3.png">
<img src="img4.png">
<img src="img5.png">
<img src="img6.png">
<img src="img7.png">
</BentoStreamGallery>
);
}
[/example]
Bento components are highly interactive through their API. The BentoStreamGallery
component API is accessible by passing a ref
:
import React, {createRef} from 'react';
const ref = createRef();
function App() {
return (
<BentoStreamGallery ref={ref}>
<img src="img1.png">
<img src="img2.png">
<img src="img3.png">
<img src="img4.png">
<img src="img5.png">
<img src="img6.png">
<img src="img7.png">
</BentoStreamGallery>
);
}
The BentoStreamGallery
API allows you to perform the following actions:
next()
Moves the carousel forwards by advanceCount
slides.
ref.current.next();
prev()
Moves the carousel backwards by advanceCount
slides.
ref.current.prev();
goToSlide(index: number)
Moves the carousel to the slide specified by the index
argument.
Note: index
will be normalized to a number greater than or equal to 0
and less than the number of slides given.
ref.current.goToSlide(0); // Advance to first slide.
ref.current.goToSlide(length - 1); // Advance to last slide.
onSlideChange
This event is triggered when the index displayed by the carousel has changed.
<BentoStreamGallery onSlideChange={(index) => console.log(index)}>
<img src="puppies.jpg" />
<img src="kittens.jpg" />
<img src="hamsters.jpg" />
</BentoStreamGallery>
Container type
The BentoStreamGallery
component has a defined layout size type. To ensure the component renders correctly, be sure to apply a size to the component and its immediate children via a desired CSS layout (such as one defined with width
). These can be applied inline:
<BentoStreamGallery style={{width: '300px'}}>
...
</BentoStreamGallery>
Or via className
:
<BentoStreamGallery className='custom-styles'>
...
</BentoStreamGallery>
.custom-styles {
background-color: red;
}
This component supports the common props for React and Preact components.
Either "always"
, "auto"
, or "never"
, defaults to "auto"
. This determines if and when prev/next navigational arrows are displayed. Note: When outset-arrows
is true
, the arrows are shown "always"
.
always
: Arrows are always displayed.auto
: Arrows are displayed when the carousel has most recently received interaction via mouse, and not displayed when the carousel has most recently received interaction via touch. On first load for touch devices, arrows are displayed until first interaction.never
: Arrows are never displayed.
Either "around"
or undefined. This determines how extra space is allocated after displaying the calculated number of visible slides in the carousel. If "around"
, white space is evenly distributed around the carousel with justify-content: center
; otherwise, space is allocated to the right of the carousel for LTR documents and to the left for RTL documents.
Either true
or false
, defaults to true
. When true, the carousel will allow
the user to move from the first item back to the last item and visa versa. There
must be at least three slides present for looping to occur.
Either true
or false
, defaults to false
. When true, the carousel will display its arrows outset and on either side of the slides. Note that with outset arrows, the slide container will have an effective length of 100px less than the allotted space for its given container - 50px per arrow on either side. When false, the carousel will display its arrows inset and overlayed on top of the left and right edges of the slides.
A number, defaults to 0
. This determines how much of an additional slide to show (on one or both sides of the current slide) as an affordance to the user indicating the carousel is swipeable.
A number, defaults to 1
. Determines the minimum number of slides that should be shown at a given time. Fractional values can be used to make part of a(n) additional slide(s)
visible.
A number, defaults to Number.MAX_VALUE
. Determines the maximum number of slides that should be shown at a given time. Fractional values can be used to make part of a(n) additional slide(s) visible.
A number, defaults to 1
. Determines the minimum width of each item, used to resolve how many whole items can be shown at once within the overall width of the gallery.
A number, defaults to Number.MAX_VALUE
. Determines the maximum width of each item, used to resolve how many whole items can be shown at once within the overall width of the gallery.
Either start
or center
. When start aligning, the start of a slide (e.g. the
left edge, when horizontal aligning) is aligned with the start of a carousel.
When center aligning, the center of a slide is aligned with the center of a
carousel.
Either true
or false
, defaults to true
. Determines whether or not the
carousel should snap on slides when scrolling.