Components

Prose

Format a block of running text.

Passed WCAG 2.1 AA

Line length

75 characters (68ex) max-width: Yosemite National Park is set within California’s Sierra Nevada mountains. It’s famed for its giant, ancient sequoias, and for Tunnel View, the iconic vista of towering Bridalveil Fall and the granite cliffs of El Capitan and Half Dome.

Spacing

Page heading

Great Smoky Mountains National Park straddles the border of North Carolina and Tennessee.

Section heading

Section of the page

The sprawling landscape encompasses lush forests and an abundance of wildflowers that bloom year-round. Streams, rivers and waterfalls appear along hiking routes that include a segment of the Appalachian Trail.

Subsection of the page

World renowned for its diversity of plant and animal life, the beauty of its ancient mountains, and the quality of its remnants of Southern Appalachian mountain culture, this is America's most visited national park.

Right now scientists think that we only know about 17 percent of the plants and animals that live in the park, or about 17,000 species of a probable 100,000 different organisms.

Subsection of the page

Entrance to Great Smoky Mountains National Park is free. The park is one of the few national parks where no entrance fees are charged.

  • Unordered list item
  • Unordered list item
  • Unordered list item
    • Nested unordered list item
    • Nested unordered list item
      • 3rd level nesting
      • 3rd level nesting
      • 3rd level nesting
    • Nested unordered list item
    • Nested unordered list item

Right now scientists think that we only know about 17 percent of the plants and animals that live in the park, or about 17,000 species of a probable 100,000 different organisms.

  1. Ordered list item
  2. Ordered list item
    1. Nested ordered list item
    2. Nested ordered list item
    3. Nested ordered list item
    4. Nested ordered list item
  3. Ordered list item
Bordered table
Document title Description Year
Declaration of Independence Statement adopted by the Continental Congress declaring independence from the British Empire. 1776
Bill of Rights The first ten amendments of the U.S. Constitution guaranteeing rights and freedoms. 1791
Declaration of Sentiments A document written during the Seneca Falls Convention outlining the rights that American women should be entitled to as citizens. 1848
Emancipation Proclamation An executive order granting freedom to slaves in designated southern states. 1863 

<div class="usa-line-length-example">
  <h3 class="site-preview-heading margin-top-0">Line length</h3>
  <section class="typography-example usa-prose margin-top-1">
    <p>
      <strong>75 characters (68ex) max-width:</strong> Yosemite National Park is
      set within California’s Sierra Nevada mountains. It’s famed for its giant,
      ancient sequoias, and for Tunnel View, the iconic vista of towering
      Bridalveil Fall and the granite cliffs of El Capitan and Half Dome.
    </p>
  </section>
</div>
<h3 class="site-preview-heading">Spacing</h3>
<section
  class="example-spacing usa-prose margin-top-1 font-sans-sm measure-3 bg-primary-lighter"
>
  <h1>Page heading</h1>
  <p class="usa-intro">
    Great Smoky Mountains National Park straddles the border of North Carolina
    and Tennessee.
  </p>
  <h2>Section heading</h2>
  <h3>Section of the page</h3>
  <p>
    The sprawling landscape encompasses lush forests and an abundance of
    wildflowers that bloom year-round. Streams, rivers and waterfalls appear
    along hiking routes that include a segment of the Appalachian Trail.
  </p>
  <h4>Subsection of the page</h4>
  <p>
    World renowned for its diversity of plant and animal life, the beauty of its
    ancient mountains, and the quality of its remnants of Southern Appalachian
    mountain culture, this is America's most visited national park.
  </p>
  <p>
    Right now scientists think that we only know about 17 percent of the plants
    and animals that live in the park, or about 17,000 species of a probable
    100,000 different organisms.
  </p>
  <h5>Subsection of the page</h5>
  <p>
    Entrance to Great Smoky Mountains National Park is free. The park is one of
    the few national parks where no entrance fees are charged.
  </p>
  <ul>
    <li>Unordered list item</li>
    <li>Unordered list item</li>
    <li>
      Unordered list item
      <ul>
        <li>Nested unordered list item</li>
        <li>
          Nested unordered list item
          <ul>
            <li>3rd level nesting</li>
            <li>3rd level nesting</li>
            <li>3rd level nesting</li>
          </ul>
        </li>
        <li>Nested unordered list item</li>
        <li>Nested unordered list item</li>
      </ul>
    </li>
  </ul>
  <p>
    Right now scientists think that we only know about 17 percent of the plants
    and animals that live in the park, or about 17,000 species of a probable
    100,000 different organisms.
  </p>
  <ol>
    <li>Ordered list item</li>
    <li>
      Ordered list item
      <ol>
        <li>Nested ordered list item</li>
        <li>Nested ordered list item</li>
        <li>Nested ordered list item</li>
        <li>Nested ordered list item</li>
      </ol>
    </li>
    <li>Ordered list item</li>
  </ol>
  <table>
    <caption>
      Bordered table
    </caption>
    <thead>
      <tr>
        <th scope="col">Document title</th>
        <th scope="col">Description</th>
        <th scope="col">Year</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <th scope="row">Declaration of Independence</th>
        <td>
          Statement adopted by the Continental Congress declaring independence
          from the British Empire.
        </td>
        <td>1776</td>
      </tr>
      <tr>
        <th scope="row">Bill of Rights</th>
        <td>
          The first ten amendments of the U.S. Constitution guaranteeing rights
          and freedoms.
        </td>
        <td>1791</td>
      </tr>
      <tr>
        <th scope="row">Declaration of Sentiments</th>
        <td>
          A document written during the Seneca Falls Convention outlining the
          rights that American women should be entitled to as citizens.
        </td>
        <td>1848</td>
      </tr>
      <tr>
        <th scope="row">Emancipation Proclamation</th>
        <td>
          An executive order granting freedom to slaves in designated southern
          states.
        </td>
        <td>1863</td>
      </tr>
    </tbody>
  </table>
</section>
<style scoped>
  .example-spacing * {
    background-color: white;
  }
</style>

Guidance

Accessibility guidance

Test the prose component in your own project.

USWDS tested the prose component for accessibility. You should test your implementation, too.

Use prose accessibility tests

Using the prose component

  • usa-prose is meant for blocks of text where it’s more difficult to add custom classes to individual elements, like a blog post where the content is coming out of markdown or a CMS.
  • Adding usa-prose to any container adds USWDS default heading and body text styling to the following direct-child elements:
    • h1-h6
    • p
    • ul and ol, plus child li
    • table, plus child thead, th, td, and caption
  • Customize line-length by changing the value of $theme-text-measure and $theme-lead-measure in your USWDS settings configuration. Each setting accepts a measure token.
    • $theme-text-measure
    • $theme-lead-measure

Prose settings

This component has no settings.

Prose variants

This component has no variants.

Accessibility test status

The USWDS team did 4 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
4 2 0 2 0

Overview of recent accessibility test results:

  • Passed: 2
  • Passed with exceptions: 0
  • Conditional: 2
  • Failed: 0

Learn more on the prose accessibility tests page.

Package

  • Package usage: @forward "usa-prose";
  • Dependencies: uswds-fonts

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-05-15 N/A
  • Guidance
 No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2613

2023-06-09 3.5.0
  • Styles
  • Settings
 No

Added $theme-heading-margin-top and $theme-paragraph-margin-top system variables. More information: uswds#5158

2023-06-09 3.5.0
  • Styles
  • Settings
 Breaking

Breaking Removed usa-prose- mixins and placeholders from Sass. Users should instead use typeset- mixins in their place. This is a breaking change only if your project Sass uses usa-prose- mixins and placeholders. It does not affect the look of any usa-prose–styled element. More information: uswds#5158

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656