❤
npm
Sign UpSign In

This package has been deprecated

Author message:

See @bentoproject/stream-gallery

@ampproject/amp-stream-gallery

1.2110011758.0 • Public • Published

Bento Stream Gallery

Usage

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>).

Web Component

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: Import via npm

[example preview="top-frame" playground="false"]

Install via npm:

npm install @ampproject/bento-stream-gallery
import '@ampproject/bento-stream-gallery';

[/example]

Example: Include via <script>

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 src="https://cdn.ampproject.org/custom-elements-polyfill.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]

Interactivity and API usage

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();
Actions

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.
Events

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))

Layout and style

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>

Attributes

Behavior
controls

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.
extra-space

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.

loop

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.

outset-arrows

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.

peek

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.

Gallery slide visibility
min-visible-count

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.

max-visible-count

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.

min-item-width

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.

max-item-width

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.

Slide snapping
slide-align

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.

snap

Either true or false, defaults to true. Determines whether or not the carousel should snap on slides when scrolling.

Styling

You may use the bento-stream-gallery element selector to style the streamGallery freely.

Preact/React Component

The examples below demonstrates use of the <BentoStreamGallery> as a functional component usable with the Preact or React libraries.

Example: Import via npm

[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]

Interactivity and API usage

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>
  );
}
Actions

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.
Events

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>

Layout and style

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;
}

Props

Common props

This component supports the common props for React and Preact components.

Behavior
controls

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.
extraSpace

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.

loop

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.

outsetArrows

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.

peek

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.

Gallery slide visibility
minVisibleCount

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.

maxVisibleCount

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.

minItemWidth

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.

maxItemWidth

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.

Slide snapping
slideAlign

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.

snap

Either true or false, defaults to true. Determines whether or not the carousel should snap on slides when scrolling.

Readme

Keywords

none

Package Sidebar

Install

npm i @ampproject/amp-stream-gallery

Repository

github.com/ampproject/amphtml

Homepage

github.com/ampproject/amphtml/tree/main/extensions/amp-stream-gallery/1.0

Weekly Downloads

9

Version

1.2110011758.0

License

Apache-2.0

Unpacked Size

1.18 MB

Total Files

20

Last publish

Collaborators

  • alanorozco
  • amp-toolbox
  • ampproject-admin
  • ampprojectbot
  • caroqliu
  • choumx
  • dvoytenko
  • erwinmombay
  • esth
  • fstanis
  • jridgewell
  • kdwan
  • kristoferbaxter
  • patrickkettner
  • rsimha
  • samouri
Try on RunKit
Report malware