Hooks & Filters

This reference is for developers who want to extend ReadNinja programmatically. All hooks and filters are stable and available in both Free and Pro.

PHP filters

Filter	Parameters	Description
`rpb_is_pro`	`bool`	Returns `true` if the Pro license is active
`rpb_should_display`	`bool $display, int $post_id`	Programmatically control whether the bar is rendered
`rpb_bar_config`	`array $config`	Modify the JS config array before it's output to the page
`rpb_settings_tabs`	`array $tabs`	Add or remove tabs on the settings page

`rpb_is_pro`

Lets other plugins check whether Pro is active without hard-coding class names or constants.

add_action( 'init', function () {
    if ( apply_filters( 'rpb_is_pro', false ) ) {
        // Pro-only logic here
    }
} );

`rpb_should_display`

Runs just before ReadNinja decides whether to render the bar on the current request. Return false to hide it, true to force it. Use it to hide the bar on very short posts:

add_filter( 'rpb_should_display', function ( $display, $post_id ) {
    $content   = get_post_field( 'post_content', $post_id );
    $word_count = str_word_count( wp_strip_all_tags( $content ) );

    if ( $word_count < 300 ) {
        return false;
    }
    return $display;
}, 10, 2 );

`rpb_bar_config`

Gives you the full JS config array right before it's passed to the front-end. Use it to inject custom values, override colors based on post meta, or add extra data for your own scripts.

add_filter( 'rpb_bar_config', function ( $config ) {
    if ( is_singular( 'podcast' ) ) {
        $config['color']  = '#ff6b35';
        $config['height'] = 6;
    }
    return $config;
} );

`rpb_settings_tabs`

Adds a custom tab to the settings page. Combine with the rpb_render_tab_{tab} action to fill its content.

add_filter( 'rpb_settings_tabs', function ( $tabs ) {
    $tabs['custom'] = __( 'Custom', 'my-plugin' );
    return $tabs;
} );

PHP actions

Action	Parameters	Description
`rpb_after_bar_render`	`int $post_id`	Fires after the bar HTML is output
`rpb_render_tab_{tab}`	—	Inject content into any settings page tab

Example — add an extra <div> right after the progress bar on singular posts:

add_action( 'rpb_after_bar_render', function ( $post_id ) {
    echo '<div class="my-custom-ribbon" data-post="' . esc_attr( $post_id ) . '"></div>';
} );

Example — fill the content of the custom tab registered above:

add_action( 'rpb_render_tab_custom', function () {
    echo '<h2>My custom tab</h2>';
    echo '<p>Any settings markup goes here.</p>';
} );

Browser events

ReadNinja dispatches a single DOM event you can listen for on the front-end.

Event	Target	Detail
`rpb:threshold-reached`	`document`	`{ percent: number }`

This event fires once per page load, exactly when the reader crosses the configured threshold (Pro feature — see Threshold trigger).

document.addEventListener('rpb:threshold-reached', (e) => {
  console.log('Reader reached', e.detail.percent, '%')
  // show popup, fire analytics event, etc.
})