Playground

Customize the Prose properties to see different variations.

function greet() { console.log("Hello!"); }

Installation

Overview

The Prose component system provides tools to apply beautiful and consistent typographic styles to long-form text content, such as blog posts, articles, or documentation pages. It offers two primary ways of working:

1. Wrapping with <Prose>: You can wrap standard HTML elements (like <h1>, <p>, <blockquote>) within the <Prose> component. It automatically detects these elements and applies predefined base styles (proseStyles) and typographic scale styles (proseSizes) based on the element type or an optional data-prose-type attribute. It also allows setting a global typographic scale for all nested content.
2. Using Standalone Helper Components: You can use the exported, pre-styled helper components (like H1, P, Lead, InlineCode, etc.) directly in your JSX, even outside a <Prose> wrapper. These components apply their base styles automatically and can accept an individual scale prop.

This system leverages predefined style configurations and allows for easy customization of the overall text scale and the semantic wrapper element when using <Prose>.

Usage Examples

1. Using <Prose> with Raw HTML

The <Prose> component automatically styles standard HTML tags and applies the specified scale.

2. Using Standalone Helper Components

You can use helpers directly, without <Prose>, and control their scale individually.

3. Using Helper Components Inside <Prose>

Helpers inside <Prose> inherit the global scale.

4. Using data-prose-type (Inside <Prose>)

Use this attribute on native HTML elements inside <Prose> when you want Prose to apply a specific style configuration other than the one associated with the element's default tag name. It tells <Prose> which key from proseStyles and proseSizes to use for that specific element.

Note: data-prose-type is generally not needed when using the helper components (like <Lead>, <InlineCode>), as they already apply the correct base styles internally. Its main use is for customizing how <Prose> styles raw HTML tags.

Features

• Automatic Typographic Styling (within <Prose>): Applies base styles to standard HTML elements or elements with data-prose-type.
• Typographic Scaling: Supports multiple scales (xs, sm, default, lg) via the scale prop to adjust font sizes and related styles (proseSizes).
• Flexible Usage: Use the <Prose> wrapper for automatic styling or use standalone helper components for explicit styling.
• data-prose-type Support (within <Prose>): Allows overriding the default styling for a native HTML element by specifying a data-prose-type attribute (e.g., <p data-prose-type="lead">).
• Customizable Wrapper Element (for <Prose>): Allows specifying the root HTML element (div, main, section, article) using the as prop.
• Helper Components: Exports pre-styled components (e.g., H1, P, Code) that encapsulate base styles and accept an individual scale prop.
• Tailwind CSS Friendly: Designed for seamless integration with Tailwind CSS utility classes and the cn utility.

Scale Prop Behavior

• Global Scale (<Prose scale="...">): When you set the scale prop on the <Prose> wrapper, it attempts to apply that scale to all content inside it.
  • For native HTML elements (like <h1>, <p>) directly inside <Prose>, the wrapper applies the specified scale's styles directly.
  • For helper components (like <H1>, <P>) directly inside <Prose>, the wrapper passes its scale value down to the helper component as a prop.
• Individual Scale (<H1 scale="...">): Helper components can receive an individual scale prop. They use this prop to apply the appropriate scale styles internally.
• Override Behavior: If a helper component (e.g., <H1>) is used directly inside a <Prose> wrapper, the scale prop set on the <Prose> wrapper takes precedence. The value from <Prose scale="..."> will be passed down to the <H1>, overwriting any scale prop you might have set directly on the <H1> itself in that specific instance.
• When to Use Individual Scale: Setting the scale prop on an individual helper component primarily makes sense when you are using that component outside of a <Prose> wrapper, or if the parent <Prose> wrapper is using the defaultscale and you want to override just one specific element.

Exported Helper Components

These components encapsulate base styles and accept the scale prop:

• H1, H2, H3, H4
• P
• A
• Blockquote
• Code (renders <pre><code>...</code></pre>)
• InlineCode (renders <code>...</code>)
• Lead, SubLead (render <p>)
• Large (renders <div>)
• Small (renders <small>)
• Muted (renders <p>)
• Strong (renders <strong>)
• Ul, Ol, Li

Advantages

• Consistency: Ensures uniform typography.
• Maintainability: Centralizes styles.
• Flexible Scaling: Easy adjustment of text scale via the scale prop.
• Semantic Control: Choose the right wrapper with as or use semantic helper components.
• Usage Flexibility: Works via wrapping or standalone components.

Helper Component Props

Helper components (H1, P, Lead, etc.) accept standard HTML attributes for their underlying element and also the following special prop:

Prose Props