## Purpose

Enables comments to be added to a page.

The Comments widget enables threaded discussions directly on any cplace page. It provides a native collaboration mechanism where users can have conversations, give feedback, and discuss page content without leaving the page context.

## When to Use

- **Collaboration needs**: When team members need to discuss or provide feedback on page content
- **Review workflows**: For approval processes where reviewers need to leave feedback
- **Knowledge sharing**: On wiki or documentation pages where questions and clarifications arise
- **Task coordination**: On work items where team communication is needed

## Design Considerations

### Automatic Scoping

The Comments widget automatically displays the comment thread for the page it's placed on. Unlike other widgets, it requires no data source configuration or search filters—it simply works with the embedding page's comment thread.

### Layout Placement

Comments typically serve a supporting role rather than being the primary content. Consider these placement strategies:

**Below main content**: Place comments in a lower row when discussion is secondary to the main content. Users read the content first, then scroll to participate in discussion. Works well for documentation and wiki pages.

**Side-by-side with content**: Place comments next to the main content when users need to reference what they're discussing. Useful for review pages, task details, or anywhere discussion directly relates to visible content.

**Dedicated section**: Give comments full width when discussion is the primary purpose, such as in a "Discussion" alternative layout tab.

### Pairing with Other Widgets

Comments are frequently paired with the Files widget in a "utilities" row, providing both attachment management and discussion in a compact layout below main content.

When placed beside a content widget, both should have consistent visual height to maintain layout balance.

### Single Instance Principle

Only one Comments widget is needed per layout—multiple instances would show the same thread. If different discussion contexts are needed, consider using alternative layouts with different comment scopes.

## Trade-offs

| Consideration | Implication |
|---------------|-------------|
| Notification behavior | Comment activity may trigger notifications based on workspace settings |
| Permission dependency | Users need appropriate permissions to participate in discussions |
| Space allocation | Narrow layouts limit readability of longer discussion threads |

## Related Widgets

- **Files**: Often paired in a utilities row for attachments + discussion
- **Text/Rich String**: Content that users discuss
- **Attributes Group**: Details that provide context for discussion