WP_Comment_Query with 5 top level comments per page?

Question

I'm trying to replicate the option in WordPress's settings page that says:

[x] Break comments into pages with ((5)) top level comments per page and the ((first)) page displayed by default

Right now I have the following comment query, but it only displays 5 comments, also counting the replies.

The behavior I want is 5 top-level comments, and all the replies those top-level comments might have. How do I achieve this?

Current Code

$args = array(
    'post_id' => $post_id,
    'type' => 'comment',
    'status' => 'approve',
    
    'number' => 5,
    'hierarchical' => 'threaded'
);

$comments_query = new WP_Comment_Query;
$comments = $comments_query->query($args);

Output

Total of 5 comments

Comment 1

• Reply to comment 1
• Reply to comment 1

Comment 2

Comment 3

Desired Output

5 top-level comments and all their replies

Comment 1

• Reply to comment 1
• Reply to comment 1

Comment 2

Comment 3

• Reply to comment 3
• Reply to comment 3
• Reply to comment 3

Comment 4

Comment 5

• Reply to comment 5

Answer 1

Updated

The hierarchical parameter controls whether to include comment descendants in the comments results.

From the inline docs we have that it accepts the following values:

• 'threaded' returns a tree, with each comment's children stored in a children property on the WP_Comment object.
• 'flat' returns a flat array of found comments plus their children.
• false to leave out descendants.

It also says that

The parameter is ignored (forced to false) when $fields is 'ids' or 'counts'.

Both the 'threaded' and 'flat' options makes use of the WP_Comment_Query::fill_descendants() method:

Instead of calling get_children() separately on each child comment, we do a single set of queries to fetch the descendant trees for all matched top-level comments.

but the threaded option has additional snippet that uses the add_child() method of the WP_Comment object to construct the children property.

---

As @Swen mentioned in comments, one should use the 'threaded' option.

It looks like the true value would in fact give the same as the 'flat' option.