React Faqs

Questions? Ask in Slack #vcc-ui

@volvo-cars/react-faqs

This package provides a set of helpful React components and methods that help with creating FAQs, which are used to provide a compact display of longer information. A FAQ renders an accordion to show and hide questions and answers as needed.

Installation

💡 This package includes Typescript definitions

SimpleFaqs

The SimpleFaqs component renders a list of FAQs as accordions with a question in the summary and an answer in the details section. It takes a faqs(questions/answers) array of objects with question and answer as properties. question and answer should be of type string. To use a React Node refer to the Composition example.

<View maxWidth={400}>
  <SimpleFaqs
    faqs={[
      { question: 'Question 1', answer: 'Answer 1' },
      { question: 'Question 2', answer: 'Answer 2' },
      { question: 'Question 3', answer: 'Answer 3' },
      { question: 'Question 4', answer: 'Answer 4' },
    ]}
  />
</View>

Composition

() => {
  const faqs = [
    { question: 'Question 1', answer: 'Answer 1' },
    { question: 'Question 2', answer: 'Answer 2' },
    { question: 'Question 3', answer: 'Answer 3' },
    { question: 'Question 4', answer: 'Answer 4' },
  ];
  return (
    <View maxWidth={400}>
      <Faqs showMoreText="Show more" showLessText="Show less">
        {faqs.map(({ question, answer }, index) => (
          <Faq key={index}>
            <Question>
              <Text subStyle="emphasis">{question}</Text>
            </Question>
            <Answer>
              <Text>{answer}</Text>
            </Answer>
          </Faq>
        ))}
      </Faqs>
    </View>
  );
};

Advanced

Sometimes you might want to avoid rendering a large list of FAQs on a page, therefore it's possible to select a certain number of FAQs to show initially, and hide the rest until expanded with a Show more button. This can be done by passing initialLength prop to SimpleFaqs. The text of the Show more button can be controlled by the showMoreText and showLessText props.

Using strings

<View maxWidth={400}>
  <SimpleFaqs
    showMoreText="Show more"
    showLessText="Show less"
    initialLength={4}
    faqs={[
      { question: 'Question 1', answer: 'Answer 1' },
      { question: 'Question 2', answer: 'Answer 2' },
      { question: 'Question 3', answer: 'Answer 3' },
      { question: 'Question 4', answer: 'Answer 4' },
      { question: 'Question 5', answer: 'Answer 5' },
      { question: 'Question 6', answer: 'Answer 6' },
    ]}
  />
</View>

Using React nodes

Rendering custom React nodes can be done with composition as follows

() => {
  const faqs = [
    { question: 'Question 1', answer: 'Answer 1' },
    { question: 'Question 2', answer: 'Answer 2' },
    { question: 'Question 3', answer: 'Answer 3' },
    { question: 'Question 4', answer: 'Answer 4' },
    { question: 'Question 5', answer: 'Answer 5' },
    { question: 'Question 6', answer: 'Answer 6' },
  ];
  return (
    <View maxWidth={400}>
      <Faqs showMoreText="Show more" showLessText="Show less" initialLength={4}>
        {faqs.map(({ question, answer }, index) => (
          <Faq key={index}>
            <Question>
              <Text>{question}</Text>
            </Question>
            <Answer>
              <Block>
                <Text subStyle="inline-link">{answer}</Text>
              </Block>
            </Answer>
          </Faq>
        ))}
      </Faqs>
    </View>
  );
};

Default Expanded

You can also control which FAQs will be open by default using the defaultExpanded prop, it takes an array of FAQ indices that should be expanded by default.

SimpleFaqs

<View maxWidth={400}>
  <SimpleFaqs
    defaultExpanded={[1, 4]}
    faqs={[
      { question: 'Question 1', answer: 'Answer 1' },
      { question: 'Question 2', answer: 'Answer 2' },
      { question: 'Question 3', answer: 'Answer 3' },
      { question: 'Question 4', answer: 'Answer 4' },
      { question: 'Question 5', answer: 'Answer 5' },
    ]}
  />
</View>

Composition

() => {
  const faqs = [
    { question: 'Question 1', answer: 'Answer 1' },
    { question: 'Question 2', answer: 'Answer 2' },
    { question: 'Question 3', answer: 'Answer 3' },
    { question: 'Question 4', answer: 'Answer 4' },
    { question: 'Question 5', answer: 'Answer 5' },
    { question: 'Question 6', answer: 'Answer 6' },
  ];
  return (
    <View maxWidth={400}>
      <Faqs showMoreText="Show more" showLessText="Show less" initialLength={4}>
        {faqs.map(({ question, answer }, index) => (
          <Faq key={index} defaultExpanded={index === 2}>
            <Question>
              <Text>{question}</Text>
            </Question>
            <Answer>
              <Block>
                <Text subStyle="inline-link">{answer}</Text>
              </Block>
            </Answer>
          </Faq>
        ))}
      </Faqs>
    </View>
  );
};

Accessibility

The FAQ components are accessible by default, they add necessary roles, aria labels, keyboard interaction with Enter and Space as well as tab focus following WAI:ARIA guidelines. It also sends focus back to the first element in the hidden FAQs when the Show more button is toggled with the keyboard, for a better user experience.

Structured data

Properly marked up FAQ pages may be eligible to have a rich result on Search and an Action on the Google Assistant, which can help pages reach the right users on Google search. Structured data is a standardized format for providing information about a page and classifying the page content.

The FaqStructuredData component renders a script tag with structured data in JSON-ld format. It takes a faqs array of objects with question and answer as properties. question and answer have to be of type string.

FaqStructuredData

<FaqStructuredData
  faqs={[
    { question: 'Question 1', answer: 'Answer 1' },
    { question: 'Question 2', answer: 'Answer 2' },
    { question: 'Question 3', answer: 'Answer 3' },
  ]}
/>

Which renders the following HTML:

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "Question 1",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Answer 1"
        }
      },
      {
        "@type": "Question",
        "name": "Question 2",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Answer 2"
        }
      },
      {
        "@type": "Question",
        "name": "Question 3",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Answer 3"
        }
      }
    ]
  }
</script>

If you need to render multiple FaqStructuredData components on a single page, it is required to provide the same faqPageId prop on all usages of this component in a single page, this is to convey that the FAQPage items are related or the structured data will be invalid since each page can only have one FAQPage definition. The faqPageId is usually the path of the page that is being rendered (ex: intl/v/cars/xc90-hybrid) as the id mostly static in the lifetime of the page.

<>
  <FaqStructuredData
    faqPageId="intl/v/cars/xc90-hybrid"
    faqs={[
      { question: 'Question 1', answer: 'Answer 1' },
      { question: 'Question 2', answer: 'Answer 2' },
      { question: 'Question 3', answer: 'Answer 3' },
    ]}
  />
  <FaqStructuredData
    faqPageId="intl/v/cars/xc90-hybrid"
    faqs={[
      { question: 'Question 5', answer: 'Answer 5' },
      { question: 'Question 6', answer: 'Answer 6' },
      { question: 'Question 7', answer: 'Answer 7' },
    ]}
  />
</>

Which renders the following HTML:

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "@id": "intl/v/cars/xc90-hybrid",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "Question 1",
        "acceptedAnswer": { "@type": "Answer", "text": "Answer 1" }
      },
      {
        "@type": "Question",
        "name": "Question 2",
        "acceptedAnswer": { "@type": "Answer", "text": "Answer 2" }
      },
      {
        "@type": "Question",
        "name": "Question 3",
        "acceptedAnswer": { "@type": "Answer", "text": "Answer 3" }
      }
    ]
  }
</script>
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "@id": "intl/v/cars/xc90-hybrid",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "Question 5",
        "acceptedAnswer": { "@type": "Answer", "text": "Answer 5" }
      },
      {
        "@type": "Question",
        "name": "Question 6",
        "acceptedAnswer": { "@type": "Answer", "text": "Answer 6" }
      },
      {
        "@type": "Question",
        "name": "Question 7",
        "acceptedAnswer": { "@type": "Answer", "text": "Answer 7" }
      }
    ]
  }
</script>

The above two JSON-ld objects are considered as one since they share the same @id.

generateStructuredData

If you need to generate a JSON-ld object you can use the generateStructuredData function:

generateStructuredData(
  [
    { question: 'Question 5', answer: 'Answer 5' },
    { question: 'Question 6', answer: 'Answer 6' },
    { question: 'Question 7', answer: 'Answer 7' },
  ],
  '/intl/pdp'
);

Which renders the following JS object:

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "@id": "/intl/pdp",
  mainEntity: [
    {
      "@type": "Question",
      name: "Question 5",
      acceptedAnswer: { "@type": "Answer", text: "Answer 5" },
    },
    {
      "@type": "Question",
      name: "Question 6",
      acceptedAnswer: { "@type": "Answer", text: "Answer 6" },
    },
    {
      "@type": "Question",
      name: "Question 7",
      acceptedAnswer: { "@type": "Answer", text: "Answer 7" },
    },
  ],
}

API

Props - SimpleFaqs

| Name | Description | Type | Default Value | | ----------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------ | ------------- | | defaultExpanded | An array of indices to be expanded by default | number[] | undefined | | faqs | An array of questions and answers to be rendered | {question:ReactNode,answer:ReactNode, trackEventLabel?:string}[] | undefined | | initialLength | How many FAQs to show initially, the rest are toggled by a button | number | undefined | | showMoreText | Button text to be rendered when the hidden FAQs are collapsed | string | undefined | | showLessText | Button text to be rendered when the hidden FAQs are expanded | string | undefined | | multiple | Allow opening multiple FAQs at the same time | boolean | false |

Props - Faqs

| Name | Description | Type | Default Value | | --------------- | ----------------------------------------------------------------- | --------- | ------------- | | initialLength | How many FAQs to show initially, the rest are toggled by a button | number | undefined | | showMoreText | Button text to be rendered when the hidden FAQs are collapsed | string | undefined | | showLessText | Button text to be rendered when the hidden FAQs are expanded | string | undefined | | multiple | Allow opening multiple FAQs at the same time | boolean | false |

Props - Faq

| Name | Description | Type | Default Value | | ----------------- | --------------------------------- | --------- | ------------- | | defaultExpanded | Faq should be expanded by default | boolean | undefined |

Props - Question

| Name | Description | Type | Default Value | | ----------------- | ----------------------------------------------------- | -------- | ------------- | | trackEventLabel | A custom event label to be sent with analytics events | string | undefined |

Props - FaqStructuredData

| Name | Description | Type | Default Value | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------- | | faqs | An array of questions and answers to be rendered in the structured data | {question:string,answer:string}[] | undefined | | faqPageId | A unique id, usually a URI at a page level that is shared between multiple FaqStructuredData components. Required if more than one components are rendered on the same page | string | undefined |

Args - generateStructuredData(faqs, faqPageId)

| Name | Description | Type | Default Value | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------- | | faqs | An array of questions and answers to be rendered in the structured data | {question:string,answer:string}[] | undefined | | faqPageId | A unique id, usually a URI at a page level that is shared between multiple generateStructuredData calls. Required if more than one JSON-ld object is needed | string | undefined |