This release focuses on:

• Better design flexibility
• Improved performance
• Easier configuration
• Powerful new features

Whether you’re a new user or a long-time user, version 3.0 makes building beautiful and effective Table of Contents easier than ever.

A Brand-New Settings Experience

Version 3.0 introduces a complete redesign of the settings interface. Everything is now faster, cleaner, and easier to use.

What’s New

• Fully redesigned settings page
• Search bar to quickly locate settings
• Live Preview panel
• Quick Settings panel
• Improved color picker
• Import presets
• Active session checker

The new interface helps you configure your Table of Contents in seconds instead of minutes.

Live Preview: See Changes Instantly

No more guesswork. The new Live Preview panel lets you instantly see how your Table of Contents looks while adjusting settings. The preview is 100% accurate as it leverages an iframe as if it was a visitor viewing the TOC.

This makes styling:

• Faster
• More intuitive
• More precise

Perfect for quickly finding the right design.

New Onboarding Wizard

Getting started is now easier than ever with the new Onboarding Wizard.

New users can:

• Choose a theme
• Preview the TOC in real time as they move through the steps
• Configure key settings
• Get a polished Table of Contents instantly

Perfect for beginners and a great time-saver for everyone.

New Color Palette System

Adjusting your Table of Contents colors to match your brand’s has never been easier. Previous versions required setting a separate color for every element: hover states, numbering, borders, badges, one by one. v3 changes that completely.

The new Color Palette system uses a small set of semantic colors that cascade intelligently across your entire TOC. Set your website’s Accent color once, and every theme-specific detail adapts automatically. And every color you define in the palette becomes a reusable swatch, available across all settings to override any specific element if needed.

Benefits

• Consistent branding
• Faster customization
• Easier theme switching

Update colors once — apply everywhere.

New and Upgraded Themes

Version 3.0 introduces new v3 themes and major upgrades to existing ones.

Updated Core Themes

• Default (v3) — This is an updated version of the “basic light/dark” theme
• Original (v3)
• Hero (v3)

These themes now include:

• Dark mode support
• Compatible with the Color Palette
• Better spacing
• Theme-specific options

New PRO Themes

PRO users also get brand new premium themes:

• Modern (v3)
• Mantis
• Flowline
• Vertik (v3)
• Glass
• Aurora
• Sequoia

These themes bring new visual styles ranging from minimal to bold.

Timeline TOC Mode (PRO)

Introducing Timeline Mode — a brand-new way to display your Table of Contents.

Features

• Proportionally spaced markers
• Perfect for long-form content
• Clean vertical reading experience
• Overlapping Progress bar available

This is one of the most unique and visually distinctive TOC modes available.

More Styling Power

Version 3.0 adds many new styling options:

Numbering Badge Styles

Make your TOC adopt a modern, refreshing look that pairs nicely with modern themes.

• Toggle button styles
• Numbering colors and backgrounds
• Header advanced customization (PRO)
• Top-level heading styling (PRO)
• Separator between top-level headings (PRO)

These options allow deeper customization without writing CSS.

Floating TOC Improvements (PRO)

Floating TOC now includes powerful new controls. Until v2, the floating widget would only show the active heading.

Since v3, the floating widget can either show:

• The active heading (the original floating mode)
• The TOC title
• A single icon
• A custom text

Floating Improvements

• Adjustable width
• Visibility trigger options
• Relative positioning

Slide-Out TOC Improvements (PRO)

The Blend into panel option allows the Table of Contents inside the slide-out panel to visually merge with the panel itself. Instead of appearing as a separate boxed element, the TOC adopts a more seamless, integrated look. This is achieve by removing extra backgrounds, borders, or spacing that would otherwise create a “box-within-a-box” effect.

This creates a cleaner and more modern appearance, especially when using slide-out panels, where the Table of Contents feels like a natural part of the panel rather than an embedded component. Perfect for minimalist designs and distraction-free reading experiences.

Slide-Out Improvements

• Blend into panel option
• New toggle icons
• Dynamic toggle shadow
• Toggle button advanced customization

Reading Time Estimate

You can now display reading time estimates directly in your Table of Contents.

This helps:

• Improve engagement
• Set reader expectations
• Enhance UX for long content

Additional New Features

Version 3.0 also introduces:

• TOC alignment (left, center, right)
• Regional numbering support
• Base font size option
• Extended headings scope
• Title attribute disable option

New TOC Icons

• Newspaper
• Spotlight
• List collapse
• List ordered
• Asterisk
• Atom
• Sparkles

Performance & Technical Improvements

Version 3.0 also includes major improvements under the hood:

• Improved TOC processing engine
• Improved smooth scrolling
• Better jump link behavior
• Selective CSS loading
• Cleaner inline styles
• Grid-based layout improvements

These changes improve:

• Performance
• Compatibility
• Reliability

Breaking Changes

To keep the plugin modern and maintainable:

• Removed v1 legacy support (previously announced)
• Deprecated hexadecimal and binary numeration types

Bug Fixes

• Fixed auto-insert formatting bug
• Fixed bullet spacing issue
• Minor bug fixes

Available Now

Joli Table of Contents 3.0 is the most powerful version yet.

With:

• Redesigned UI
• New themes
• Timeline mode
• Live preview
• Performance improvements

This release represents a major step forward.

Update today and experience the new Joli Table of Contents.

The post Introducing Joli Table of Contents 3.0: The Biggest Update Yet appeared first on wpjoli.

The default look of the table of contents is rather simple and will blend well with most themes. However, under the hood Joli Table of Contents has been designed to be fully customizable.

In this article, I will customize an exemple table of contents from scratch, by leveraging Joli Table of Contents’ advanced customization features.

The default table of contents

In our example, we will use the default “Basic Light” theme. This is how it looks like with the default settings:

Basic styles: borders / rounded corners / colors

The first we are going to do to get a more custom look using the plugin’s settings is the following:

• Add a border
• Round the corners
• Change some colors

Custom border

To add a border, let’s go to the settings page. Under STYLES > TABLE OF CONTENTS, let’s set the Border to 3px on each side.

Next, we are going to set the Border radius to 12px on each corner. This setting will make the corners rounded.

Now let’s give a custom color to the border, and this is how the settings look like so far:

At this point, our table of contents looks like this:

Table of contents colors

For our style, we want to have a blue colored header with the table of contents title in white and a white background for the table of contents body (behind the headings).

Under STYLES > TABLE OF CONTENTS, let’s set the table of contents Background color to our custom blue color (#5838e9). This will make the whole table of contents blue.

Under STYLES > TABLE OF CONTENTS TITLE, let’s set the table of contents Title color to white (#ffffff).

What we want to do now, is to set a different body color. Let’s make it white, and slightly transparent to bring out a tiny bit of a blue shade.

Under STYLES > TABLE OF CONTENTS BODY, we are setting a white, with an opacity of 96%.

If you are wondering why I did not just change the Header background color, it’s because of the table of contents border that we set. In this particular case, the anti-aliasing from the rounded corners was creating a small, but noticeable hair thin white line near the corners. So by setting the blue background color at a deeper level (the TOC root), it prevents this visual defect from happening.

The table of contents now looks like this:

Because of the blue color around the heading area, the space between the TOC title and the headings looks narrower. Let’s fix this by setting a Margin bottom to the Header.

Under STYLES > TABLE OF CONTENTS HEADER, we are setting the bottom Margin to 14px.

Finally, let’s change the headings color to match our table of contents color.

Under STYLES > HEADINGS TEXT LINK, we are setting the Color to our custom blue.

This is what the table of contents looks like at this point:

Increase spacing between headings

In order to make the table of contents look less packed, we are now going to increase the space between the headings.

Under STYLES > HEADINGS TEXT LINK, we are setting the Padding top and bottom to 5px each, to keep it even. We are using padding instead margin in this case because it will provide more area to the heading to click on.

The table of content now looks like this:

Custom background image

Let’s push the customization a little further now by using some custom CSS. The goal here is to set a custom background pattern on top of our slightly transparent white body background.

To make things simple, we are going to use an SVG pattern generator like Pattern Monster, and all we have to do is to pick a pattern, customize colors (make sure to adjust transparency).

The website lets you copy the corresponding CSS code by a click of a button but because it is not possible to save HTML in the settings, we need to encode the SVG in base 64.

The website fffuel.co lets you do that easily. Just import or paste your SVG, and it will generate automatically the corresponding URL string that we can use for our CSS.

To make our table of contents body have this custom background, we need to target it with CSS using the .wpj-jtoc--body class. All we have to do now is to paste the base 64 encoded CSS code generated and here we have our CSS rule:

Under STYLES > CUSTOM CSS, let’s just paste this custom CSS.

.wpj-jtoc--body {
    background-image: url("data:image/svg+xml;base64,PHN2ZyBpZD0ncGF0dGVybklkJyB3aWR0aD0nMTAwJScgaGVpZ2h0PScxMDAlJyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnPjxkZWZzPjxwYXR0ZXJuIGlkPSdhJyBwYXR0ZXJuVW5pdHM9J3VzZXJTcGFjZU9uVXNlJyB3aWR0aD0nMjAnIGhlaWdodD0nMjAnIHBhdHRlcm5UcmFuc2Zvcm09J3NjYWxlKDIpIHJvdGF0ZSgwKSc+PHJlY3QgeD0nMCcgeT0nMCcgd2lkdGg9JzEwMCUnIGhlaWdodD0nMTAwJScgZmlsbD0naHNsYSgwLCAwJSwgMTAwJSwgMCknLz48cGF0aCBkPSdNMC0xMEMtLjAxMS00LjQ5LTQuNDg1LjAzLTEwIC4wMy00LjQ4NS4wMy0uMDExIDQuNDkgMCAxMCAuMDExIDQuNDk4IDQuNDkzLjAwMSAxMC0uMDEgNC40OTMtLjAyLjAxMi00LjQ5OCAwLTEwem0wIDIwYy0uMDExIDUuNTEtNC40ODUgMTAuMDMtMTAgMTAuMDMgNS41MTUgMCA5Ljk4OSA0LjQ2IDEwIDkuOTcuMDExLTUuNTAyIDQuNDkzLTkuOTk5IDEwLTEwLjAxQzQuNDkzIDE5Ljk4LjAxMiAxNS41MDIgMCAxMHptMjAtMjBDMTkuOTg5LTQuNDkgMTUuNTE1LjAzIDEwIC4wM2M1LjUxNSAwIDkuOTg5IDQuNDYgMTAgOS45Ny4wMTEtNS41MDIgNC40OTMtOS45OTkgMTAtMTAuMDEtNS41MDctLjAxLTkuOTg4LTQuNDg4LTEwLTkuOTl6bTAgMjBjLS4wMTEgNS41MS00LjQ4NSAxMC4wMy0xMCAxMC4wMyA1LjUxNSAwIDkuOTg5IDQuNDYgMTAgOS45Ny4wMTEtNS41MDIgNC40OTMtOS45OTkgMTAtMTAuMDEtNS41MDctLjAxLTkuOTg4LTQuNDg4LTEwLTkuOTl6JyAgc3Ryb2tlLXdpZHRoPScxJyBzdHJva2U9J2hzbGEoMjU5LCA1OSUsIDU5JSwgMC4wNCknIGZpbGw9J25vbmUnLz48cGF0aCBkPSdNMTAgMEM5Ljk4OSA1LjUxIDUuNTE1IDEwLjAzIDAgMTAuMDNjNS41MTUgMCA5Ljk4OSA0LjQ2IDEwIDkuOTcuMDExLTUuNTAyIDQuNDkzLTkuOTk4IDEwLTEwLjAxLTUuNTA3LS4wMS05Ljk4OC00LjQ4OC0xMC05Ljk5eicgIHN0cm9rZS13aWR0aD0nMScgc3Ryb2tlPSdoc2xhKDI1OSwgNTklLCA1OSUsIDAuMDQpJyBmaWxsPSdub25lJy8+PC9wYXR0ZXJuPjwvZGVmcz48cmVjdCB3aWR0aD0nODAwJScgaGVpZ2h0PSc4MDAlJyB0cmFuc2Zvcm09J3RyYW5zbGF0ZSgwLDApJyBmaWxsPSd1cmwoI2EpJy8+PC9zdmc+");
}

Here is our table of contents with a custom background:

Custom styles for specific headings depth

Let’s keep pushing our customization journey by leveraging another built-in capability of Joli Table of Contents.

For each generated heading, Joli Table of Contents automatically “tags” it with a specific depth class. This way, it is easy to target different depth for styling.

The way it works is the following: if the heading is of type H2, it will get the .--jtoc-h2 CSS class. if the heading is of type H3, it will get the .--jtoc-h3 CSS class, and so on until H6 depth.

From there, and because of the way Joli Table of Contents works, we need to create a specific CSS rule to target specific heading depth. We cannot just use the .--jtoc-h2 class by itself or it will give an unwanted result.

Here is the rule that you need to follow: .--jtoc-h2>.wpj-jtoc--item-content a

This rule targets all headings of type H2, and all links contained within .wpj-jtoc--item-content, directly after the .--jtoc-h2 element.

In the following example, we are going to style every heading of type H2, and make the font weight to be bold.

The custom CSS needs to be pasted in the Custom CSS section of the settings.

.wpj-jtoc .--jtoc-h2>.wpj-jtoc--item-content a {
    font-weight: bold;
}

This is what the Table of contents looks like now:

Custom HTML after specific headings

Now, to go even further, we are going to create a visual “separation” between each heading of type H2. For simplicity’s sake, we are going to create a simple horizontal line.

To achieve this, we are going to leverage the built-in action hooks and insert custom HTML dynamically.

For this specific task, the most appropriate hook is joli_toc_before_begin_item_content. When the hook is triggered, it comes with a variable ($args) containing the current heading information while it’s being processed.

$args is an Array and contains the following offsets:

    $args['id']      // The heading id (its html anchor)
    $args['title']   // The heading title as it will show
    $args['counter'] // The heading counter (1, or 1.1, or 2.1.1, etc)
    $args['depth']   // The heading depth (from 2 to 6)
    $args['url']     // Optional url that would override the id

We can the use this to have a fine control over the way our custom HTML will be inserted.

Our goal is to insert an horizontal line before each heading of type H2, except for the first one.

To do that, we are making sur that the counter must be different from “1” which corresponds to the very first heading. The second condition will be matched against the depth. We only want depth of level 2.

The following snippet must be placed in your theme’s functions.php.

add_action('joli_toc_before_begin_item_content', function ($args) {
    //Skip first heading and only process H2 headings
    if ($args['counter'] != '1' && $args['depth'] == 2){
        echo '<hr>'; //Horizontal line
    }
}, 10, 1);

Here is our table of contents now with the horizontal lines:

Custom bullet points instead of standard numeration

To give a more unique look to our table of contents, we are going to get rid of the numeration, and instead, we want to have custom bullet points shaped as a pill.

First of all, we need to turn off the numeration in the settings:

The next step is to use another action hook in order to inject custom HTML right before each heading.

The hook that we need for this is joli_toc_after_begin_item_link.

The following snippet must be placed in your theme’s functions.php.

add_action('joli_toc_after_begin_item_link', function ($args) {
    echo '<span class="pill-bullet"></span>'; // Custom HTML that will be inserted before each heading
}, 10, 1);

The second step in this process is to give some styles to the .pill-bullet class so that our pill shaped bullet point actually show up.

In the Custom CSS section, we are going to add this rule that will render a “green pill” :

.pill-bullet {
    display: inline-block;
    width: 20px;
    height: 8px;
    background: #34ddb4;
    margin-right: 10px;
    border-radius: 10px;
}

We can see here that the numeration has been replaced by our custom HTML. If we wanted to, we could add more complexity and have different colors or shapes per heading depth.

Add a custom link at the bottom of the Table Of Contents

Still using action hooks, let’s see how we can add a custom link to the bottom of our TOC. This link will be present on every single TOC.

The hook that we need for this is joli_toc_after_headings.

In this example, out link will be wrapped in a div with some inline styles to make the link centered. The following snippet must be placed in your theme’s functions.php.

add_action('joli_toc_after_headings', function ($args) {
    echo '<div style="text-align:center;width:100%"><a href="https://my-custom-link.com" class="ext-link">External link</a></div>';
}, 10, 1);

Still in the Custom CSS section, we are going to give some basic style to our text link :

a.ext-link {
    text-transform: uppercase;
    font-size: 10px;
    font-weight: 700;
    color: gray;
}

And voilà ! Here is our table of contents with the link at the bottom:

Altering headings

This is another advanced feature that you can use to have full control over your headings.

Whether you want to target a specific keyword or add a random string, you can use the joli_toc_headings filter hook to alter the actual output.

In the following example, we are going to remove the vowels from every heading. It is not really useful, but it is just to demonstrate how it’s done and so you can use the same pattern for a more useful application.

The following snippet must be placed in your theme’s functions.php.

add_filter('joli_toc_headings', 'filter_headings', 10, 2);

function filter_headings( $headings ){ 
    $headings = array_map(function($heading){
            //Remove vowels from titles
            $heading['title'] = preg_replace("/[aeiouAEIOU]/", "", $heading['title']);
        return $heading;
    }, $headings);

    return $headings;
}

Here is the table of contents with the vowels removed from the headings !

Another similar example, but this time the function will remove any combination of a number and a dot at the start of a heading.

For instance, “2. Top 5 pets for a big backyard” would become “Top 5 pets for a big backyard”. This would give a cleaner look at the table of contents when there is already the numeration activated and you have some random headings in the page that contain numbers.

add_filter('joli_toc_headings', 'filter_headings', 10, 2);

function filter_headings( $headings ){ 
    $headings = array_map(function($heading){
            //Remove first number and dot from titles
            $heading['title'] = preg_replace("/^\d+.\s+/", "", $heading['title']);
        return $heading;
    }, $headings);

    return $headings;
}

Conclusion

As you can see, there are many ways to customize Joli Table of Contents. Some customizations require a little bit of code but there are already plenty of customizations available from the settings.

Joli Table of Contents bundle a large array of hooks that allow for extensive customization. Make sure to have a look at the documentation to have a good outlook of what’s possible to achieve.

Keep in mind that all the customizations shown in this article work for both the Free and the Pro version of Joli Table of Contents.

The post How to Customize Joli Table of Contents: Beginner & Advanced Tips appeared first on wpjoli.