@bentoproject/accordion

v1.2302271541.0

Published

2 years ago

Displays content sections that can be collapsed and expanded.

Downloads

228

0High
0Medium
0Low

bentoprojectbot

kristoferbaxter

esth

Bento Accordion

Displays content sections that can be collapsed and expanded. This component provides a way for viewers to glance at the content outline and jump to any section. Effective use reduces scrolling needs on mobile devices.

A Bento Accordion accepts one or more <section> elements as its direct children.
Each <section> must contain exactly two direct children.
The first child in a <section> is the heading for that section of the Bento Accordion. It must be a heading element such as <h1>-<h6> or <header>.
The second child in a <section> is the expandable/collapsible content.
- It can be any tag allowed in AMP HTML.
A click or tap on a <section> heading expands or collapses the section.
A Bento Accordion with a defined id preserves the collapsed or expanded state of each section while the user remains on your domain.

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.

Import via npm

npm install @bentoproject/accordion

import {defineElement as defineBentoAccordion} from '@bentoproject/accordion';
defineBentoAccordion();

Include via `<script>`

<script type="module" src="https://cdn.ampproject.org/bento.mjs" crossorigin="anonymous"></script>
<script nomodule src="https://cdn.ampproject.org/bento.js" crossorigin="anonymous"></script>
<script type="module" src="https://cdn.ampproject.org/v0/bento-accordion-1.0.mjs" crossorigin="anonymous"></script>
<script nomodule src="https://cdn.ampproject.org/v0/bento-accordion-1.0.js" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdn.ampproject.org/v0/bento-accordion-1.0.css" crossorigin="anonymous">

Example

<!DOCTYPE html>
<html>
  <head>
    <script
      type="module"
      async
      src="https://cdn.ampproject.org/bento.mjs"
    ></script>
    <script nomodule src="https://cdn.ampproject.org/bento.js"></script>
    <script
      type="module"
      async
      src="https://cdn.ampproject.org/v0/bento-accordion-1.0.mjs"
    ></script>
    <script
      nomodule
      async
      src="https://cdn.ampproject.org/v0/bento-accordion-1.0.js"
    ></script>
    <link
      rel="stylesheet"
      type="text/css"
      href="https://cdn.ampproject.org/v0/bento-accordion-1.0.css"
    />
  </head>
  <body>
    <bento-accordion id="my-accordion">
      <section>
        <h2>Section 1</h2>
        <div>Content in section 1.</div>
      </section>
      <section>
        <h2>Section 2</h2>
        <div>Content in section 2.</div>
      </section>
       <!-- Expanded on page load due to attribute: -->
      <section expanded>
        <h2>Section 3</h2>
        <div>Content in section 3.</div>
      </section>
    </bento-accordion>
  </body>
</html>

Interactivity and API usage

Bento components are highly interactive through their API. The bento-accordion component API is accessible by including the following script tag in your document:

await customElements.whenDefined('bento-accordion');
const api = await accordion.getApi();

API Example

<!DOCTYPE html>
<html>
  <head>
    <script
      type="module"
      async
      src="https://cdn.ampproject.org/bento.mjs"
    ></script>
    <script nomodule src="https://cdn.ampproject.org/bento.js"></script>
    <script
      type="module"
      async
      src="https://cdn.ampproject.org/v0/bento-accordion-1.0.mjs"
    ></script>
    <script
      nomodule
      async
      src="https://cdn.ampproject.org/v0/bento-accordion-1.0.js"
    ></script>
    <link
      rel="stylesheet"
      type="text/css"
      href="https://cdn.ampproject.org/v0/bento-accordion-1.0.css"
    />
  </head>
  <body>
    <bento-accordion id="my-accordion">
      <section>
        <h2>Section 1</h2>
        <div>Content in section 1.</div>
      </section>
      <section>
        <h2>Section 2</h2>
        <div>Content in section 2.</div>
      </section>
       <!-- Expanded on page load due to attribute: -->
      <section expanded>
        <h2>Section 3</h2>
        <div>Content in section 3.</div>
      </section>
    </bento-accordion>
    <script>
      (async () => {
        const accordion = document.querySelector('#my-accordion');
        await customElements.whenDefined('bento-accordion');
        const api = await accordion.getApi();

        // programatically expand all sections
        api.expand();
        // programatically collapse all sections
        api.collapse();
      })();
    </script>
  </body>
</html>

Actions

toggle()

The toggle action switches the expanded and collapsed states of bento-accordion sections. When called with no arguments, it toggles all sections of the accordion. To specify a specific section, add the section argument and use its corresponding id as the value.

<bento-accordion id="myAccordion">
  <section id="section1">
    <h2>Section 1</h2>
    <div>Bunch of awesome content</div>
  </section>
  <section>
    <h2>Section 2</h2>
    <div>Bunch of awesome content</div>
  </section>
  <section>
    <h2>Section 3</h2>
    <div>Bunch of awesome content</div>
  </section>
</bento-accordion>
<button id="button1">Toggle All Sections</button>
<button id="button2">Toggle Section 1</button>
<script>
  (async () => {
    const accordion = document.querySelector('#myAccordion');
    await customElements.whenDefined('bento-accordion');
    const api = await accordion.getApi();

    // set up button actions
    document.querySelector('#button1').onclick = () => {
      api.toggle();
    };
    document.querySelector('#button2').onclick = () => {
      api.toggle('section1');
    };
  })();
</script>

expand()

The expand action expands the sections of the bento-accordion. If a section is already expanded, it stays expanded. When called with no arguments, it expands all sections of the accordion. To specify a section, add the section argument, and use its corresponding id as the value.

<bento-accordion id="myAccordion">
  <section id="section1">
    <h2>Section 1</h2>
    <div>Bunch of awesome content</div>
  </section>
  <section>
    <h2>Section 2</h2>
    <div>Bunch of awesome content</div>
  </section>
  <section>
    <h2>Section 3</h2>
    <div>Bunch of awesome content</div>
  </section>
</bento-accordion>
<button id="button1">Expand All Sections</button>
<button id="button2">Expand Section 1</button>
<script>
  (async () => {
    const accordion = document.querySelector('#myAccordion');
    await customElements.whenDefined('bento-accordion');
    const api = await accordion.getApi();

    // set up button actions
    document.querySelector('#button1').onclick = () => {
      api.expand();
    };
    document.querySelector('#button2').onclick = () => {
      api.expand('section1');
    };
  })();
</script>

collapse()

The collapse action collapses the sections of the bento-accordion. If a section is already collapsed, it stays collapsed. When called with no arguments, it collapses all sections of the accordion. To specify a section, add the section argument, and use its corresponding id as the value.

<bento-accordion id="myAccordion">
  <section id="section1">
    <h2>Section 1</h2>
    <div>Bunch of awesome content</div>
  </section>
  <section>
    <h2>Section 2</h2>
    <div>Bunch of awesome content</div>
  </section>
  <section>
    <h2>Section 3</h2>
    <div>Bunch of awesome content</div>
  </section>
</bento-accordion>
<button id="button1">Collapse All Sections</button>
<button id="button2">Collapse Section 1</button>
<script>
  (async () => {
    const accordion = document.querySelector('#myAccordion');
    await customElements.whenDefined('bento-accordion');
    const api = await accordion.getApi();

    // set up button actions
    document.querySelector('#button1').onclick = () => {
      api.collapse();
    };
    document.querySelector('#button2').onclick = () => {
      api.collapse('section1');
    };
  })();
</script>

Events

The bento-accordion API allows you to register and respond to the following events:

expand

This event is triggered when an accordion section is expanded and is dispatched from the expanded section.

See below for example.

collapse

This event is triggered when an accordion section is collapsed and is dispatched from the collapsed section.

In the example below, section 1 listens for the expand event and expands section 2 when it is expanded. section 2 listens for the collapse event and collapses section 1 when it is collapsed.

See below for example.

Events Example

<bento-accordion id="eventsAccordion" animate>
  <section id="section1">
    <h2>Section 1</h2>
    <div>Puppies are cute.</div>
  </section>
  <section id="section2">
    <h2>Section 2</h2>
    <div>Kittens are furry.</div>
  </section>
</bento-accordion>

<script>
  (async () => {
    const accordion = document.querySelector('#eventsAccordion');
    await customElements.whenDefined('bento-accordion');
    const api = await accordion.getApi();

    // when section 1 expands, section 2 also expands
    // when section 2 collapses, section 1 also collapses
    const section1 = document.querySelector('#section1');
    const section2 = document.querySelector('#section2');
    section1.addEventListener('expand', () => {
      api.expand('section2');
    });
    section2.addEventListener('collapse', () => {
      api.collapse('section1');
    });
  })();
</script>

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/bento-accordion-1.0.css"
/>

Alternatively, you may also make the light-weight pre-upgrade styles available inline:

<style>
  bento-accordion {
    display: block;
    contain: layout;
  }

  bento-accordion,
  bento-accordion > section,
  bento-accordion > section > :first-child {
    margin: 0;
  }

  bento-accordion > section > * {
    display: block;
    float: none;
    overflow: hidden; /* clearfix */
    position: relative;
  }

  @media (min-width: 1px) {
    :where(bento-accordion > section) > :first-child {
      cursor: pointer;
      background-color: #efefef;
      padding-right: 20px;
      border: 1px solid #dfdfdf;
    }
  }

  .i-amphtml-accordion-header {
    cursor: pointer;
    background-color: #efefef;
    padding-right: 20px;
    border: 1px solid #dfdfdf;
  }

  bento-accordion
    > section:not([expanded])
    > :last-child:not(.i-amphtml-animating),
  bento-accordion
    > section:not([expanded])
    > :last-child:not(.i-amphtml-animating)
    * {
    display: none !important;
  }
</style>

Attributes

animate

Include the animate attribute in <bento-accordion> to add a "roll down" animation when the content is expanded and "roll up" animation when collapsed.

This attribute can be configured to based on a media query.

<bento-accordion animate>
  <section>
    <h2>Section 1</h2>
    <div>Content in section 1.</div>
  </section>
  <section>
    <h2>Section 2</h2>
    <div>Content in section 2.</div>
  </section>
  <section>
    <h2>Section 3</h2>
    <div>Content in section 2.</div>
  </section>
</bento-accordion>

expanded

Apply the expanded attribute to a nested <section> to expand that section when the page loads.

<bento-accordion>
  <section id="section1">
    <h2>Section 1</h2>
    <div>Bunch of awesome content</div>
  </section>
  <section id="section2">
    <h2>Section 2</h2>
    <div>Bunch of awesome content</div>
  </section>
  <section id="section3" expanded>
    <h2>Section 3</h2>
    <div>Bunch of awesome expanded content</div>
  </section>
</bento-accordion>

expand-single-section

Allow only one section to expand at a time by applying the expand-single-section attribute to the <bento-accordion> element. This means if a user taps on a collapsed <section>, it will expand and collapse other expanded <section>'s.

<bento-accordion expand-single-section>
  <section>
    <h2>Section 1</h2>
    <div>Content in section 1.</div>
  </section>
  <section>
    <h2>Section 2</h2>
    <div>Content in section 2.</div>
  </section>
  <section>
    <h2>Section 3</h2>
    <img
      src="https://source.unsplash.com/random/320x256"
      width="320"
      height="256"
    />
  </section>
</bento-accordion>

Styling

You may use the bento-accordion element selector to style the accordion freely.

Keep the following points in mind when you style an accordion:

bento-accordion elements are always display: block.
float cannot style a <section>, heading, nor content elements.
An expanded section applies the expanded attribute to the <section> element.
The content element is clear-fixed with overflow: hidden and hence cannot have scrollbars.
Margins of the <bento-accordion>, <section>, heading, and content elements are set to 0, but can be overridden in custom styles.
Both the header and content elements are position: relative.

Preact/React Component

Import via npm

npm install @bentoproject/accordion

Example

import React from 'react';
import {
  BentoAccordion,
  BentoAccordionSection,
  BentoAccordionHeader,
  BentoAccordionContent
} from '@bentoproject/accordion/react';
import '@bentoproject/accordion/styles.css';

function App() {
  return (
    <BentoAccordion>
      <BentoAccordionSection key={1}>
        <BentoAccordionHeader>
          <h1>Section 1</h1>
        </BentoAccordionHeader>
        <BentoAccordionContent>Content 1</BentoAccordionContent>
      </BentoAccordionSection>

      <BentoAccordionSection key={2}>
        <BentoAccordionHeader>
          <h1>Section 2</h1>
        </BentoAccordionHeader>
        <BentoAccordionContent>Content 2</BentoAccordionContent>
      </BentoAccordionSection>

      <BentoAccordionSection key={3}>
        <BentoAccordionHeader>
          <h1>Section 3</h1>
        </BentoAccordionHeader>
        <BentoAccordionContent>Content 3</BentoAccordionContent>
      </BentoAccordionSection>
    </BentoAccordion>
  );
}

Interactivity and API usage

Bento components are highly interactive through their API. The BentoAccordion component API is accessible by passing a ref:

import React, {createRef} from 'react';
const ref = createRef();

function App() {
  return (
    <BentoAccordion ref={ref}>
      <BentoAccordionSection id="section1" key={1}>
        <BentoAccordionHeader>
          <h1>Section 1</h1>
        </BentoAccordionHeader>
        <BentoAccordionContent>Content 1</BentoAccordionContent>
      </BentoAccordionSection>

      <BentoAccordionSection id="section2" key={2}>
        <BentoAccordionHeader>
          <h1>Section 2</h1>
        </BentoAccordionHeader>
        <BentoAccordionContent>Content 2</BentoAccordionContent>
      </BentoAccordionSection>

      <BentoAccordionSection id="section3" key={3}>
        <BentoAccordionHeader>
          <h1>Section 3</h1>
        </BentoAccordionHeader>
        <BentoAccordionContent>Content 3</BentoAccordionContent>
      </BentoAccordionSection>
    </BentoAccordion>
  );
}

Actions

The BentoAccordion API allows you to perform the following actions:

toggle()

ref.current.toggle();
ref.current.toggle('section1');

expand()

ref.current.expand();
ref.current.expand('section1');

collapse()

ref.current.collapse();
ref.current.collapse('section1');

Events

The Bento Accordion API allows you to respond to the following events:

onExpandStateChange

This event is triggered on a section when an accordion section is expanded or collpased and is dispatched from the expanded section.

See example below for example.

onCollapse

This event is triggered on a section when an accordion section is collapsed and is dispatched from the collapsed section.

See example below for example.

Events Example

import React, {createRef} from 'react';
import {
  BentoAccordion,
  BentoAccordionSection,
  BentoAccordionHeader,
  BentoAccordionContent
} from '@bentoproject/accordion/react';
import '@bentoproject/accordion/styles.css';


function App() {
  const ref = createRef();
  return (
    <BentoAccordion ref={ref}>
      <BentoAccordionSection
        id="section1"
        key={1}
        onExpandStateChange={(expanded) => {
          alert(expanded ?  'section1 expanded' : 'section1 collapsed');
        }}
      >
        <BentoAccordionHeader>
          <h1>Section 1</h1>
        </BentoAccordionHeader>
        <BentoAccordionContent>Content 1</BentoAccordionContent>
      </BentoAccordionSection>

      <BentoAccordionSection
        id="section2"
        key={2}
        onExpandStateChange={(expanded) => {
          alert(expanded ?  'section2 expanded' : 'section2 collapsed');
        }}
      >
        <BentoAccordionHeader>
          <h1>Section 2</h1>
        </BentoAccordionHeader>
        <BentoAccordionContent>Content 2</BentoAccordionContent>
      </BentoAccordionSection>

      <BentoAccordionSection
        id="section3"
        key={3}
        onExpandStateChange={(expanded) => {
          alert(expanded ?  'section3 expanded' : 'section3 collapsed');
        }}
      >
        <BentoAccordionHeader>
          <h1>Section 3</h1>
        </BentoAccordionHeader>
        <BentoAccordionContent>Content 3</BentoAccordionContent>
      </BentoAccordionSection>
    </BentoAccordion>
  )
}

Layout and style

Container type

The BentoAccordion 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 height, width, aspect-ratio, or other such properties). These can be applied inline:

<BentoAccordion style={{width: 300, height: 100}}>...</BentoAccordion>

Or via className:

<BentoAccordion className="custom-styles">...</BentoAccordion>

.custom-styles {
  background-color: red;
}

Props

BentoAccordion

animate

If true, then uses "roll-down" / "roll-up" animation during the expansion and collapse of each section.

Default: false

expandSingleSection

If true, then expanding 1 section will automatically collapse all other sections.

Default: false

BentoAccordionSection

animate

If true, then uses "roll-down" / "roll-up" animation during the expansion and collapse the section.

Default: false

expanded

If true, expands the section.

Default: false

onExpandStateChange

(expanded: boolean): void

Callback to listen for expand state changes. Takes a boolean flag as parameter indicating whether the section was just expanded (false indicates it was collapsed)

BentoAccordionHeader

Common props

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

BentoAccordionHeader does not yet support any custom props

BentoAccordionContent

Common props

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

BentoAccordionContent does not yet support any custom props

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Bento Accordion

Web Component

Import via npm

Include via <script>

Example

Interactivity and API usage

API Example

Actions

toggle()

expand()

collapse()

Events

expand

collapse

Events Example

Layout and style

Attributes

animate

expanded

expand-single-section

Styling

Preact/React Component

Import via npm

Example

Interactivity and API usage

Actions

toggle()

expand()

collapse()

Events

onExpandStateChange

onCollapse

Events Example

Layout and style

Container type

Props

BentoAccordion

animate

expandSingleSection

BentoAccordionSection

animate

expanded

onExpandStateChange

BentoAccordionHeader

Common props

BentoAccordionContent

Common props

Include via `<script>`