NUI-Widgets documentation has moved to Storybook hosted on Github Pages.

Section

import Section from '@concur/nui-widgets/lib/Section/Section';

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.

Section can optionally contain a Section.Content component.

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 toolbar1 = (
    <ButtonToolbar muted>
        <ButtonDropdown
            id='dropdownExample'
            textLabel='View:'
            title='Unsubmitted'
            type='link'>
            <MenuItem>Unsubmitted</MenuItem>
            <MenuItem>Submitted</MenuItem>
            <MenuItem>Paid</MenuItem>
        </ButtonDropdown>
    </ButtonToolbar>
);

<Section
    title='Section Title'
    titleContent={toolbar1}
    titleContentAlignment='left'>
    <Section.Content>Child Content</Section.Content>
</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">
   <Section.Content>Child Content</Section.Content>
</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.

const paragraph = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque mattis, justo ac mattis convallis, est ligula maximus felis, sed pretium. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed at porta eros, vel fermentum lacus.";

<Section title='Section Title'>
    <Section.Content>{paragraph}</Section.Content>
</Section>

Title Content

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.

const toolbar1 = (
    <ButtonToolbar muted>
        <ButtonDropdown
            id='dropdownExample'
            textLabel='View:'
            title='Unsubmitted'
            type='link'>
            <MenuItem>Unsubmitted</MenuItem>
            <MenuItem>Submitted</MenuItem>
            <MenuItem>Paid</MenuItem>
        </ButtonDropdown>
    </ButtonToolbar>
);

const paragraph = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque mattis, justo ac mattis convallis, est ligula maximus felis, sed pretium. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed at porta eros, vel fermentum lacus.";

<Section
    headingLevel={3}
    title='Section Title'
    titleContent={toolbar1}>
    <Section.Content>{paragraph}</Section.Content>
</Section>

<Section
    headingLevel={3}
    title='Section Title'
    titleContent={toolbar1}
    titleContentAlignment='left'>
    <Section.Content>{paragraph}</Section.Content>
</Section>

Icons

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 Available Icons.

const toolbar1 = (
    <ButtonToolbar muted>
        <ButtonDropdown
            id='dropdownExample'
            textLabel='View:'
            title='Unsubmitted'
            type='link'>
            <MenuItem>Unsubmitted</MenuItem>
            <MenuItem>Submitted</MenuItem>
            <MenuItem>Paid</MenuItem>
        </ButtonDropdown>
    </ButtonToolbar>
);

const paragraph = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque mattis, justo ac mattis convallis, est ligula maximus felis, sed pretium. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed at porta eros, vel fermentum lacus.";

<Section
    iconName='air'
    title='Section Title'
    titleContent={toolbar1}
    titleIsHidden>
    <Section.Content>{paragraph}</Section.Content>
</Section>

Expandable

See SectionExpandable.

Usage

Properties

Name Type Default Description
children Node Required The “body” of the section; that is, any content that exists outside the <header> element but inside the <section> element.
title Node Required Content of the section heading. Must not contain only whitespace because concise yet descriptive headings are extremely important to screen readers. If this needs to be visually hidden, set the titleIsHidden property to true.
className String   Custom classes to be added to the wrapping <section>.
headerClassName String   Custom classes to be added to the <header>.
headingClassName String   Custom classes to be added to the <h#> tag, where # is the headingLevel.
headingLevel Number 2 Sets the semantic heading level for the section heading: <h2>. Allowable values are 2 through 6. (<h1> headings are managed by the framework itself.)
iconName String   If set, an icon will be displayed to the left of the title text (and will be visible even when titleIsHidden is true). See Available Icons for a complete list.
sectionRef Ref or Function   Attach a ref to the <section> element.
titleContent Node   Any content that resides to the right of the heading. Most often this will be used for buttons, status information, or other toolbar-like controls. It will normally align with the vertical center of the <h#> element, but will wrap beneath if necessary.
titleContentAlignment String 'right' Defines whether titleContent will be left- or right-justified after the initial <h#> heading. Allowable values are 'left' and 'right'.
titleIsHidden Boolean false If true, the title text will be hidden from sighted readers but will remain accessible to screen readers.

Section.Content

Properties

Property Type Default Description
children Node   The content that will appear within the <p> tag.
className String   Custom classes to add to the <p> tag.

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