lab components / Text

Highlight

Draw the attention of users to important data and metrics.

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { Highlight } from "@siteimprove/fancylab";

#Examples

The Highlight component consists of four namespaced components:

Highlight.Layout takes care of sizing, spacing, and responsive behavior.
Highlight.Item contains the data that needs to be highlighted.
Highlight.Title serves as the subtle heading of a highlight item.
Highlight.Value presents a string or number in a visually salient manner.

#Default

This is the default implementation of the Highlight component. Things to take note of:

The component can be used inside any container, but is mainly intended for use inside of a Card.
An aria-label is required. It should describe what the collection of highlight items concerns.
Although not required, you'll usually want to wrap a number in a FormattedNumber component.

Number

20,492

Percentage

54.84%

Currency

USD1,234,567.00

Empty

Tooltip

Yes

CodeHTML output

<Card>
	<Highlight.Layout aria-label="Highlights">
		<Highlight.Item>
			<Highlight.Title>Number</Highlight.Title>
			<Highlight.Value>
				<FormattedNumber number={20492} format="number" />
			</Highlight.Value>
		</Highlight.Item>
		<Highlight.Item>
			<Highlight.Title>Percentage</Highlight.Title>
			<Highlight.Value>
				<FormattedNumber number={0.5484} format="percent" />
			</Highlight.Value>
		</Highlight.Item>
		<Highlight.Item>
			<Highlight.Title>Currency</Highlight.Title>
			<Highlight.Value>
				<FormattedNumber number={1234567} format="currency" />
			</Highlight.Value>
		</Highlight.Item>
		<Highlight.Item>
			<Highlight.Title>Empty</Highlight.Title>
			<Highlight.Value>
				<FormattedNumber number={null} />
			</Highlight.Value>
		</Highlight.Item>
		<Highlight.Item>
			<Highlight.Title>
				<Tooltip variant={{ type: "text" }} content="This title has a tooltip.">
					Tooltip
				</Tooltip>
			</Highlight.Title>
			<Highlight.Value>Yes</Highlight.Value>
		</Highlight.Item>
	</Highlight.Layout>
</Card>

By default, the Highlight.Title component outputs an h3 level heading. That's because the component will often be nested inside of a Card with an h2 level heading. When this is not the case, the headingLevel property can be used to output a different heading level.

Number

20,492

Percentage

54.84%

Currency

USD1,234,567.00

Empty

Tooltip

Yes

CodeHTML output

<Card>
	<Highlight.Layout aria-label="Highlights">
		<Highlight.Item>
			<Highlight.Title headingLevel="h5">Number</Highlight.Title>
			<Highlight.Value>
				<FormattedNumber number={20492} format="number" />
			</Highlight.Value>
		</Highlight.Item>
		<Highlight.Item>
			<Highlight.Title headingLevel="h5">Percentage</Highlight.Title>
			<Highlight.Value>
				<FormattedNumber number={0.5484} format="percent" />
			</Highlight.Value>
		</Highlight.Item>
		<Highlight.Item>
			<Highlight.Title headingLevel="h5">Currency</Highlight.Title>
			<Highlight.Value>
				<FormattedNumber number={1234567} format="currency" />
			</Highlight.Value>
		</Highlight.Item>
		<Highlight.Item>
			<Highlight.Title headingLevel="h5">Empty</Highlight.Title>
			<Highlight.Value>
				<FormattedNumber number={null} />
			</Highlight.Value>
		</Highlight.Item>
		<Highlight.Item>
			<Highlight.Title headingLevel="h5">
				<Tooltip variant={{ type: "text" }} content="This title has a tooltip.">
					Tooltip
				</Tooltip>
			</Highlight.Title>
			<Highlight.Value>Yes</Highlight.Value>
		</Highlight.Item>
	</Highlight.Layout>
</Card>

#Extra content

A Highlight.Item component can contain more than a Highlight.Title and Highlight.Value. Simply add the extra content as another child. Correct spacing will automatically be applied.

Number

The answer to life, the universe, and everything.

Progress

54.84%

CodeHTML output

<Card>
	<Highlight.Layout aria-label="Highlights">
		<Highlight.Item>
			<Highlight.Title>Number</Highlight.Title>
			<Highlight.Value>
				<FormattedNumber number={42} format="number" />
			</Highlight.Value>
			<Paragraph tone="subtle">The answer to life, the universe, and everything.</Paragraph>
		</Highlight.Item>
		<Highlight.Item>
			<Highlight.Title>Progress</Highlight.Title>
			<Highlight.Value>
				<FormattedNumber number={0.5484} format="percent" />
			</Highlight.Value>
			<ProgressBar value={54.84} total={100} />
		</Highlight.Item>
	</Highlight.Layout>
</Card>

#No padding

Use the noPadding property to remove a Highlight.Item component's padding.

Padding

Yes

Padding

CodeHTML output

<Card>
	<Highlight.Layout aria-label="Highlights">
		<Highlight.Item>
			<Highlight.Title>Padding</Highlight.Title>
			<Highlight.Value>Yes</Highlight.Value>
		</Highlight.Item>
		<Highlight.Item noPadding>
			<Highlight.Title>Padding</Highlight.Title>
			<Highlight.Value>No</Highlight.Value>
		</Highlight.Item>
	</Highlight.Layout>
</Card>

#No gap

Use the noGap property to remove the space between the title, value, and other children elements nested inside a Highlight.Item component.

Gap

Yes

Gap

CodeHTML output

<Card>
	<Highlight.Layout aria-label="Highlights">
		<Highlight.Item>
			<Highlight.Title>Gap</Highlight.Title>
			<Highlight.Value>Yes</Highlight.Value>
		</Highlight.Item>
		<Highlight.Item noGap>
			<Highlight.Title>Gap</Highlight.Title>
			<Highlight.Value>No</Highlight.Value>
		</Highlight.Item>
	</Highlight.Layout>
</Card>

#Compact

Use the compact property of the Highlight.Layout compontent to render a smaller, bordered Highlight component. This version is intended for use inside containers other than a Card, such as a Side Panel or Modal.

Number

20,492

Percentage

54.84%

Currency

USD1,234,567.00

Empty

Tooltip

Yes

CodeHTML output

<Highlight.Layout aria-label="Highlights" compact>
	<Highlight.Item>
		<Highlight.Title headingLevel="h5">Number</Highlight.Title>
		<Highlight.Value>
			<FormattedNumber number={20492} format="number" />
		</Highlight.Value>
	</Highlight.Item>
	<Highlight.Item>
		<Highlight.Title>Percentage</Highlight.Title>
		<Highlight.Value>
			<FormattedNumber number={0.5484} format="percent" />
		</Highlight.Value>
	</Highlight.Item>
	<Highlight.Item>
		<Highlight.Title>Currency</Highlight.Title>
		<Highlight.Value>
			<FormattedNumber number={1234567} format="currency" />
		</Highlight.Value>
	</Highlight.Item>
	<Highlight.Item>
		<Highlight.Title>Empty</Highlight.Title>
		<Highlight.Value>
			<FormattedNumber number={null} />
		</Highlight.Value>
	</Highlight.Item>
	<Highlight.Item>
		<Highlight.Title>
			<Tooltip variant={{ type: "text" }} content="This title has a tooltip.">
				Tooltip
			</Tooltip>
		</Highlight.Title>
		<Highlight.Value>Yes</Highlight.Value>
	</Highlight.Item>
</Highlight.Layout>

#Properties

#Highlight.Layout

Number

20,492

Percentage

54.84%

Currency

USD1,234,567.00

Empty

Tooltip

Yes

CodePropsHTML output

Property	Description	Defined	Value
aria-labelRequired	`string`Labels the group of highlights.	YesNo
childrenOptional	`element`The content (highlight items) of the highlight section	YesNo
compactOptional	`boolean`Adds rounded border and reduces padding, spacing, and font-size	YesNo	truefalse
data-observe-keyOptional	`string`Unique string, used by external script e.g. for event tracking	YesNo
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo

#Highlight.Item

Number

20,492

CodePropsHTML output

Property	Description	Defined	Value
childrenOptional	`element`The content of the highlight	YesNo
noPaddingOptional	`boolean`Removes the highlight's padding	YesNo	truefalse
noGapOptional	`boolean`Removes the highlight's gap	YesNo	truefalse
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo

#Highlight.Title

Number

CodePropsHTML output

Property	Description	Defined
childrenOptional	`element`The content (label) of the title	YesNo
headingLevelOptional	`"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"`The heading level of the title (defaults to h3)	YesNo
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo

#Highlight.Value

20,492

CodePropsHTML output

Property	Description	Defined
childrenOptional	`element`The content (label) of the value	YesNo
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo

#Guidelines

#Best practices

Use the Highlight component for data and metrics that are clearly related.
Use the default version inside any type of container, such as a Card, Side Panel or Modal.
Use the compact version inside any type of container, other than a Card.
Let the Highlight component take up 100% of its container’s width.
Add spacing around the compact version, so it doesn’t take up 100% of it's container's width.
Try to limit the optional extra content to a single element.