Section

import { Section } from '@concur/nui-widgets';

Section components provide an easy way to define sections of a page. They have properly rendered headings and children and are accessible to visually impaired users. They should be used as a fundamental building block of page design.

Introduction

For designers, Section components provide an easy way to visually define sections of a page with properly rendered headings and children, as seen in the following example:

const toolbar = (
    <ButtonToolbar muted>
        <ControlLabel>Title Content:</ControlLabel>
        <Button type='link'>Link</Button>
    </ButtonToolbar>
);
<Section
    title='Section Title'
    titleContent={toolbar}
    titleContentAlignment='left' >
    <p>Child Content</p>
</Section>

For developers, Section components provide an easy way to semantically define sections of a page using <section>, <header> and <h#> HTML elements. For example, the following semantically meaningful HTML:

<section>
   <header>
      <h2>Section Title</h2>
   </header>
   <p>Child Content</p>
</section>

is easily generated by:

<Section title="Section Title">
   <p>Child Content<p>
</Section>

The above HTML elements provide important accessibility information and aid screen readers when parsing a page’s structure and content.

Examples

Default

Rendering with the only two required properties, title and children (which is implicitly constructed by React).

<Section
    title='h2 (default)'>
    {paragraph}
</Section>

Title Content

titleContent={toolbar}, headingLevel='h4'

Title content is anything intended to sit aligned with and to the right of the title. This is often used for toolbars, status information, or links. Note that the title content is right-aligned within the section by default.

Title content can be used to make a “custom” heading. The title property is used for providing simple text that improves accessibility. If the design favors complicated text as the visual heading, set the titleIsHidden property to true and put the custom node in the titleContent property and set titleContentAlignment to left.

<Section
    headingLevel='h4'
    title='h4, toolbar title content aligned right'
    titleContent={toolbar}>
    {paragraph}
</Section>

Icons

iconName='icon-air'

This example demonstrates both the titleIsHidden property and the iconName property. Regardless of the value of titleIsHidden, any section icon will always be visible. (Icon adornments like these have no audible description and are therefore invisible to screen readers.) A list of available icon names can be found at Icons.

<Section
    iconName='icon-air'
    title='Hidden From Sight, Visible To Screen Readers...'
    titleContent={toolbar}
    titleIsHidden>
    {paragraph}
</Section>

Type 2

Type 2 sections are essentially the same as the original type 1 sections with (very few) minor differences in markup and some significant differences in styling. Type 2 sections are often used in SAP Concur’s Travel product. Allowable values for type are '1' and '2' (and it’s possible that more types will be added in the future).

type='2', iconName='icon-star', titleContent={button}

Note that when a type 2 section is assigned an icon, the child elements are indented even further to ensure that they continue to align with the beginning of the title. One very important point to note with regard to type 2 sections: their headings all render exactly the same, no matter what semantic heading level you assign to them. <h2> through <h6> are all visually rendered the same: uppercase, bold, body font size. (However, it’s still important to assign them the appropriate semantic heading level to aid screen readers and visually impaired users.)

<Section
    iconName='icon-star'
    title='h2, type 2, icon (star), link button as title content'
    titleContent={button}
    type='2'>
    {paragraph}
</Section>

Expandable

See SectionExpandable.

Usage

Properties

Section components accept the following properties; see below to understand how these properties affect the generated HTML.

Generated HTML

The following demonstrates how each of the above properties fit into the generated HTML. The only two required properties are title (the heading text) and the implicit children (the child content); all other properties are optional:

<Section
   title='My Heading'
   className='cnqr-my-section'
   headingLevel='h3'
   iconName='icon-star'
   titleContent={button}
   titleContentAlignment='left'
   titleIsHidden
   type='1'>
   <p>This is my child content</p>
</Section>

This generates the following HTML:

<section class="cnqr-my-section">
   <header class="cnqr-align-left">
      <h3><i class="icon-star"></i><span class="screen-reader-only">My Heading</span></h3>
      <div>
         {button}
      </div>
   </header>
   <p>This is my child content</p>
</section>

Note that it’s possible to place Section components inside of other Section components, which makes it easy to create correctly structured pages (see also the Nested Sections example):

<Section title='Outer Content' headingLevel='h2'>
   <Section title='Inner Content Section 1' headingLevel='h3'/>
   <Section title='Inner Content Section 2' headingLevel='h3'/>
   <Section title='Inner Content Section 3' headingLevel='h3'>
     <Section title='Innermost Content' headingLevel='h4'/>
   </Section>
</Section>

Accessibility

Important considerations with regard to accessibility and the Section component:

• The use of Section components naturally leads to well-structured and accessible HTML.
• Nesting Section components within Section components naturally leads to well-structured and accessible pages, as outlined in the example, above.
• title is relied upon by the visually impaired; titles should be concise, yet accurate and descriptive. They must be renderable as plain text and should not contain control elements of any sort, such as buttons or drop-down lists – that’s what the titleContent property is for.
• headingLevel values must be properly selected to create valid HTML structures. An <h2> section cannot reside as a child inside a parent <h3> section, for example; the opposite order is correct.
• titleContent is unlikely to contain Section components (or anything that generates an <h#> heading). If you find yourself doing this then you quite likely need to re-think your structure.

Resources

• Semantic Elements @ https://www.w3schools.com
• Section Elements @ https://w3c.github.io
• Header Elements @ https://w3c.github.io
• Semantic Elements Best Practices @ https://stackoverflow.com