Best Practices for Typography in Tailwind CSS

Posted on: August 01 2024

By Dave Becker

Hero image for Best Practices for Typography in Tailwind CSS

As most web site pages are moving towards more dynamic driven CMS based content, the Tailwind CSS Typography plugin can be the ideal companion for applying quick and elegant styling to any section of HTML markdown.

In this guide, you'll find everything you need to know to get started using the Tailwind Typography plugin, including:

What is @tailwindcss/typography plugin and why it's important?
The different types of typography modifiers and how they work.
How to customize the typography plugin to your needs.
Best use cases for the typography plugin.

Adding this plugin into the mix can greatly reduce the need to write any additional classes. So let's take a look at how to make any HTML code blocks look amazing!

What is the Tailwind Typography Plugin?

The @tailwindcss/typography plugin is an optional supplimental feature that can be added to add quick styling to any section of HMTL code.

As you may know, Tailwind is not opinionated about basic tags like h1, p, ul or li to name a few, in fact the framework removes these base styles by default.

The Typography plugin simply adds some general styling for the most basic HTML elements the can be applied to any wrapper element.

Why is the Typography Plugin Important?

The Typography plugin plays a very important role in the overall Tailwind framework, including:

Makes the @tailwindcss/typography optional.
Does not interfere with any general custom styling.
Is applied using a simple prose class wrapper.
Can reduce the need to write custom classes to do the same work as the plugin.
Can use the same breakpoint and utility modifiers to alter styling.
It can be completely customized.

There's many benefits to using the plugin but the one that stands out the most is it's ability to style dynamic CMS driven content.

As more and more businesses are using CMS for content driven areas of marketing, blogs and documentation, it's essential to have a way to consistently apply styles to dynamically rendered HTML blocks.

How Does the Typography Plugin Work?

The typography plugin generates all of the CSS classes you'll need for all of the base HTML elements.

It will add all of these generated typography classes to the final Tailwind CSS output.

In order to use the @tailwindcss/typography, it needs to be installed.

Installing the Typography Plugin

npm install @tailwindcss/typography

Once installed, it needs to be configured in the tailwind.config.js file.

tailwindcss config

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('@tailwindcss/typography')
  ]
  // ...
}

By default, the top level class name is called prose. If you need to rename this class for any reason, pass an additional object to the plugin specifying your custom className. For example:

Customize typography class name

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ..
  plugins: [
    require('@tailwindcss/typography')({
      className: 'your-custom-class',
    })
  ]
}

So now whenever applying styles, swap your new className instead of the default prose.

<article class="your-custom-class">
  ...
</article>

Getting started with the Typography Plugin

Now that the plugin is installed it can used in a number of ways to quickly apply styling to HTML blocks.

Let's cover a few of the basics with some examples.

How to apply typography classes

All of the generated utility classes from the typography plugin will be under one class name called prose.

The only thing that's needed is to add the prose class to the outer most HTML tag around the content you want to style. For example:

<article class="prose">
  <h1>Simple Typography Demo</h1>
  <p>A simple test to verify the plugin is installed correctly.</p>
  <ul>
    <li>One</li>
    <li>Two</li>
    <li>Three</li>
  </ul>
</article>

By using the prose class alone provides some base styling with a default gray typography theme is applied.

As mentioned earlier, one of the primary benefits of the typography plugin is applying it to dynamic markdown data that might come from a CMS or even static markdown page content.

Markdown content renders to basic HTML tags without any specific classes, so using the prose wrapper istantly adds some great styles. For example:

<article class="prose">
  {cmsMarkdownData}
</article>

Typography grayscale modifiers

The prose class was designed to be used with utility modifiers to adjust its grayscale styling. Here's a list of the supported grayscale modifiers.

prose-gray: Default grayscale
prose-slate: Slate grayscale
prose-zinc: Zinc grayscale
prose-neutral: Neutral grayscale
prose-stone: Stone grayscale

The differences in these grayscale modifiers is very subtle but will be noticed in the overall page design.

This is a very useful feature since most designs will use a color scheme and having grayscale options can provide a better typography setting to match a design.

The grayscale modifiers can be applied as follows:

HTML block with a prose neutral grayscale

<article class="prose prose-neutral">
  <h1>{title}</h1>
  <p>{description}</p>
  <div>
    {cmsMarkdownData}
  </div>
</article>

The prose-{*} grayscale class modifiers should be included with the prose class.

Typography scale modifiers

The scale modifiers can be used to scale a whole section of content or to emphasis a certain section or excerpt for example.

The prose class supports the standard text size modifiers.

prose-sm
prose-base (Default)
prose-lg
prose-xl
prose-2xl

For example, to emphasis the font size for an excerpt you could add prose-2xl to the following blockquote.

<article class="prose prose-neutral">
  <h1>{title}</h1>
  <p>{description}</p>
  <blockquote class="prose-2xl">
    {excerpt}
  </blockquote>
  <div>
    {cmsMarkdownData}
  </div>
</article>

The Typography plugin also supports the same breakpoint modifiers.

For example, the following utility modifiers will increase the font scale for mobile breakpoints.

<article class="prose prose-neutral">
  <span className="prose-xl lg:prose-base">
    {cmsMarkdownData}
  </span>
</article>

Dark mode modifiers

The Typography plugin even has some default support for dark mode inverted styles using dark:prose-invert.

This is a very quick way to convert page content to a dark mode without having to define any dark mode custom CSS classes or add any Tailwind utility classes.

<body class="bg-slate-800">
  ...
  <article class="prose prose-slate dark:prose-invert">
      {cmsMarkdownData}
  </article>
  ...
</body>

Excluding blocks from prose plugin styles

If you ever need to escape and exclude any HTML block within the prose class wrapper, you can use the not-prose class.

<article class="prose prose-neutral">
  <h1>Title</h1>
  <p>Description</p>
 
  <p class="not-prose">content...</p>

  <img class="not-prose" src="/some/path/phota.png"/>
</article>

Customizing the Typography Plugin

So now that we've seen how to apply some quick typography styles, there's always going to be the need for customization. Let's take a look at some examples.

Customize using utility modifiers

The first approach and probably the easiest is to modify the styles using the modifiers provided by the plugin.

Using the prose-{tag}:{utility} notation, will apply a specific utility for all of targeted tags.

To target the h1 and img tags, use the following modifiers.

prose-h1:{utility}
prose-img:{utility}

<article class="prose prose-neutral prose-h1:text-blue-800 prose-img:rounded-lg">
  <h1>Title</h1>
  <p>Description</p>
 
  <h2>Topic Section 1</h2>
  <p>content...</p>

  <h2>Topic Section 2</h2>
  <p>content...</p>

  <img src="/some/path/phota.png"/>
</article>

There's a modifier for each of the core HTML tags and they can even be applied to breakpoints. Here's an example to target large devices only.

<article class="prose prose-neutral lg:prose-p:text-xl lg:prose-h1:text-5xl">
  <h1>Title</h1>
  <p>Description</p>
 
  <h2>Topic Section 1</h2>
  <p>content...</p>
</article>

Customize the plugin globally

In most cases the same styles may need to be applied for all prose sections and tags across the website.

In this case the plugin can be customized at the theme level and globally modified.

The typography plugin will merge any customizations defined inside of the typography object. This can either be an object or function.

Sometimes it's better to define a function so it can receive a reference to the theme object.

tailwindcss config

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      typography: (theme ) => {
        return {
          DEFAULT: {
            css: {
              // sets the font size
              fontSize: theme('fontSize.md'),
              // allows for full width
              maxWidth: 'none',
              // adds a background hover
              a: {
                // uses CS-in-JS object notation
                '&:hover': { 
                  backgroundColor: theme('colors.blue.200'),
                },
              },
              // defines code block font size and color
              code: {
                fontSize: theme('fontSize.base'),
                color: theme('colors.blue.700'),
              }
            }
          }
        }
      }
    }
  },
  // ...
}

By returning the DEFAULT modified object, the default CSS can be modified directly. In this example, I've customized some of the typography features.

As you can see it's a very flexible plugin. If you notice the use of CS-in-JS notation, which would normally require writing a custom plugin just to use this type of syntax in Tailwind.

Not having to write a custom plugin to have full customization of the rendered styles is a huge plus.

In Conclusion

So now we've seen what the plugin is used for and how to apply the styles to any section of code. This is by far one of the most useful plugins in my opinion.

As most apps are starting to leverage CMS systems for marketing, blogs or documentation, it makes it easy to style dynamic content very easily.

Here's a recent article on Building a blog with Next.js which uses the @tailwindcss/typography plugin to style dynamic markdown. The same technique can be applied to any frontend technology.

Hope this article was informative.