README

A lightweight fluent builder for generating accessible HTML breadcrumb navigation in WordPress. Supports Schema.org microdata, ARIA attributes, icons (including dashicons), custom separators, and flexible configuration.

Installation

composer require arraypress/wp-breadcrumbs

Usage

Fluent Builder

use ArrayPress\Breadcrumbs\Breadcrumbs;

Breadcrumbs::create()
    ->add( 'Home', '/', 'dashicons-admin-home' )
    ->add( 'Products', '/products/' )
    ->add_current( 'Widget Pro' )
    ->display();

One-Liners

// Render from an array of items
echo render_breadcrumbs( [
    [ 'label' => 'Home', 'url' => '/' ],
    [ 'label' => 'Blog', 'url' => '/blog/' ],
    [ 'label' => 'My Post' ],
] );

// Echo directly
display_breadcrumbs( [
    [ 'label' => 'Dashboard', 'url' => admin_url() ],
    [ 'label' => 'Settings' ],
] );

Helper Function

// Create a builder via helper
create_breadcrumbs()
    ->add( 'Buckets', $buckets_url, 'dashicons-cloud' )
    ->add( $bucket_name, $bucket_url )
    ->add_current( $prefix )
    ->display();

With Icons

// WordPress dashicons (auto-detected by prefix)
Breadcrumbs::create()
    ->add( 'Home', '/', 'dashicons-admin-home' )
    ->add( 'Media', '/media/', 'dashicons-admin-media' )
    ->add_current( 'image.jpg' )
    ->display();

// Raw HTML icons (SVG, img, etc.)
Breadcrumbs::create()
    ->add( 'Home', '/', '<svg>...</svg>' )
    ->add_current( 'Page' )
    ->display();

Custom Configuration

Breadcrumbs::create( [
    'separator'  => '/',
    'aria_label' => 'File navigation',
    'nav_class'  => 'my-breadcrumbs',
] )
    ->add( 'Root', '/' )
    ->add( 'Documents', '/docs/' )
    ->add_current( 'readme.md' )
    ->display();

// Or configure via fluent methods
Breadcrumbs::create()
    ->separator( '»' )
    ->aria_label( 'Site navigation' )
    ->nav_class( 'custom-nav' )
    ->add( 'Home', '/' )
    ->add_current( 'About' )
    ->display();

Bulk Items

$items = [
    [ 'label' => 'Home', 'url' => '/', 'icon' => 'dashicons-admin-home' ],
    [ 'label' => 'Products', 'url' => '/products/' ],
    [ 'label' => 'Widgets', 'url' => '/products/widgets/' ],
    [ 'label' => 'Widget Pro' ],
];

Breadcrumbs::create()->add_items( $items )->display();

Inspection

$breadcrumbs = Breadcrumbs::create()
    ->add( 'Home', '/' )
    ->add( 'Blog', '/blog/' )
    ->add_current( 'Post' );

$breadcrumbs->count();      // 3
$breadcrumbs->has_items();   // true
$breadcrumbs->is_empty();    // false
$breadcrumbs->first();       // Item { label: 'Home', url: '/' }
$breadcrumbs->last();        // Item { label: 'Post', url: null }
$breadcrumbs->items();       // [ Item, Item, Item ]

Array & JSON Output

$breadcrumbs = Breadcrumbs::create()
    ->add( 'Home', '/' )
    ->add_current( 'About' );

$breadcrumbs->to_array();          // Array of item data
echo json_encode( $breadcrumbs );  // JSON serializable
echo (string) $breadcrumbs;        // Rendered HTML

Item Value Object

use ArrayPress\Breadcrumbs\Item;

$item = new Item( 'Products', '/products/', 'dashicons-cart' );

$item->label();       // 'Products'
$item->url();         // '/products/'
$item->icon();        // 'dashicons-cart'
$item->attributes();  // []
$item->is_link();     // true
$item->has_icon();    // true
$item->to_array();    // [ 'label' => ..., 'url' => ..., ... ]

HTML Output

The rendered HTML follows semantic best practices:

<nav class="arraypress-breadcrumbs" aria-label="Breadcrumb">
    <ol class="arraypress-breadcrumbs__list" itemscope itemtype="https://schema.org/BreadcrumbList">
        <li class="arraypress-breadcrumbs__item" itemprop="itemListElement" itemscope
            itemtype="https://schema.org/ListItem">
            <a href="/" itemprop="item">
                <span class="dashicons dashicons-admin-home" aria-hidden="true"></span>
                <span itemprop="name">Home</span>
            </a>
            <meta itemprop="position" content="1">
        </li>
        <li class="arraypress-breadcrumbs__separator" aria-hidden="true">&#8250;</li>
        <li class="arraypress-breadcrumbs__item arraypress-breadcrumbs__item--active" itemprop="itemListElement"
            itemscope itemtype="https://schema.org/ListItem" aria-current="page">
            <span itemprop="name">About</span>
            <meta itemprop="position" content="2">
        </li>
    </ol>
</nav>

Methods

Builder

Configuration

Getters

Rendering

Output

Item Methods

Configuration Defaults

Requirements

• PHP 7.4+
• WordPress 5.0+

License

GPL-2.0-or-later