Skip to content
lib components / Text

Paragraph

Use this component for blocks of text. In other words, one or more complete sentences, like this text.

ExamplesPropertiesGuidelinesNotable Changes
import { Paragraph } from "@siteimprove/fancylib";

If your text is a single word or short snippet, use the inline text component instead. Unless it functions as the title of a page or section, then use the heading component.

#Examples

The paragraph component features various properties for customizing its appearance. Adjust the properties if it helps users complete their tasks. Specifically, by making the text's appearance match its message and importance. Don't make adjustments purely because of aesthetic reasons. The following sections showcase the properties and explain when to use them.

#Default

The componenent's default appearance is best suited for neutral information of regular importance that does not need to be the first thing that a user notices.

This is a default paragraph.

<Paragraph>This is a default paragraph.</Paragraph>

#Size

Use this property to adjust how attention-grabbing the paragraph should be.

The size of this paragraph is x-small.


The size of this paragraph is small (the default).


The size of this paragraph is medium.


The size of this paragraph is large.


The size of this paragraph is x-large.


The size of this paragraph is xx-large.


The size of this paragraph is xxx-large.

<Paragraph size="xSmall">The size of this paragraph is x-small.</Paragraph> <br /> <Paragraph size="small">The size of this paragraph is small (the default).</Paragraph> <br /> <Paragraph size="medium">The size of this paragraph is medium.</Paragraph> <br /> <Paragraph size="large">The size of this paragraph is large.</Paragraph> <br /> <Paragraph size="xLarge">The size of this paragraph is x-large.</Paragraph> <br /> <Paragraph size="xxLarge">The size of this paragraph is xx-large.</Paragraph> <br /> <Paragraph size="xxxLarge">The size of this paragraph is xxx-large.</Paragraph>

#Tone

Use this property to make the paragraph's color support its semantic message.

The tone of this paragraph is neutral-dark (the default). It can be used for neutral messages.


The tone of this paragraph is neutral-light. It can be used for neutral messages on dark backgrounds.


The tone of this paragraph is positive. It can be used for positive messages.


The tone of this paragraph is negative. It can be used for negative messages.


The tone of this paragraph is warning. It can be used for warning messages.


The tone of this paragraph is subtle. It can be used for neutral, but less important messages.

<Paragraph tone="neutralDark"> The tone of this paragraph is neutral-dark (the default). It can be used for neutral messages. </Paragraph> <br /> <div style={{ backgroundColor: "#3C485E", height: 35, display: "flex", alignItems: "center" }}> <Paragraph tone="neutralLight"> The tone of this paragraph is neutral-light. It can be used for neutral messages on dark backgrounds. </Paragraph> </div> <br /> <Paragraph tone="positive"> The tone of this paragraph is positive. It can be used for positive messages. </Paragraph> <br /> <Paragraph tone="negative"> The tone of this paragraph is negative. It can be used for negative messages. </Paragraph> <br /> <Paragraph tone="warning"> The tone of this paragraph is warning. It can be used for warning messages. </Paragraph> <br /> <Paragraph tone="subtle"> The tone of this paragraph is subtle. It can be used for neutral, but less important messages. </Paragraph>

#Emphasis

Use this property to make the paragraph's visual weight match the importance of its message.

This paragraph has a normal emphasis (the default). It can be used for regular messages.


This paragraph has a medium emphasis. It can be used for moderately important messages.


This paragraph has a strong emphasis. It can be used for very important messages.

<Paragraph emphasis="normal"> This paragraph has a normal emphasis (the default). It can be used for regular messages. </Paragraph> <br /> <Paragraph emphasis="medium"> This paragraph has a medium emphasis. It can be used for moderately important messages. </Paragraph> <br /> <Paragraph emphasis="strong"> This paragraph has a strong emphasis. It can be used for very important messages. </Paragraph>

#Alignment

Use this property to center or right align the text in paragraphs. Use it sparingly and only for short paragraphs, since it negatively affects readability.

This paragraph is left aligned (the default).


This paragraph is center aligned.


This paragraph is right aligned.

<Paragraph alignment="left">This paragraph is left aligned (the default).</Paragraph> <br /> <Paragraph alignment="center">This paragraph is center aligned.</Paragraph> <br /> <Paragraph alignment="right">This paragraph is right aligned.</Paragraph>

#Line height

This property is by default set to multi-line, since paragraphs frequently wrap across multiple lines. In certain cases, it is certain that a paragraph will stay on a single line and the "extra" vertical height might be unwanted layout-wise. In these (rare) cases, the property can be set to single-line.

This paragraph's line-height property is set to multi-line, which is the default value. As you can see, a line height that is larger than the font size prevents the lines from sticking together.


The line-height property of this paragraph is set to single-line. As you can see, a line height that is equal to the font size results in lines that stick together, which negatively impacts the reading experience.

<Paragraph lineHeight="multi-line"> This paragraph's line-height property is set to multi-line, which is the default value. As you can see, a line height that is larger than the font size prevents the lines from sticking together. </Paragraph> <br /> <Paragraph lineHeight="single-line"> The line-height property of this paragraph is set to single-line. As you can see, a line height that is equal to the font size results in lines that stick together, which negatively impacts the reading experience. </Paragraph>

#Properties

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

PropertyDescriptionDefinedValue
idOptional
stringCustom unique id
childrenOptional
ReactNodeContent to be displayed
sizeOptional
"large" | "medium" | "small" | "xLarge" | "xSmall" | "xxLarge" | "xxxLarge"Controls font-size
alignmentOptional
"center" | "left" | "right"Controls vertical alignment
lineHeightOptional
"multi-line" | "single-line"Controls line-height
toneOptional
"negative" | "neutralDark" | "neutralLight" | "positive" | "subtle" | "warning"Controls visual tone
emphasisOptional
"medium" | "normal" | "strong"Controls font-weight
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)

#Guidelines

#Best practices

  • Use for blocks of text, which can be defined as one or more full sentences.
  • Use the styling properties for functional, not aesthetic, purposes.
  • Wrap multiple paragraphs (with or without headings) in the text container component. This component applies correct spacing between typographic components.

#Do not use when

  • The text is just a single word or short snippet. Use the inline text component instead.
  • The text functions as the title of a page (section). Use the heading component instead.

#Accessibility

Using the paragraph component for blocks of text makes that text more meaningful to assistive technologies, such as screenreaders. This provides assisitive technology users with a clear and structured overview of a page's content and makes it easier for them to navigate that content.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

  • Be direct — users scan pages for information instead of reading.
  • Put the most important information first.
  • Stick to one idea per sentence.
  • Keep sentences below 25 words — longer sentences are harder to comprehend.
  • Frontload sentences with the important details.
  • Use headings to break up text and make it easier to scan for information.

#Notable Changes

#Version 0.0.x

The name of this component was changed from P to Paragraph when it was moved from FancyPFG to FancyLib.