Htmx/docs/Issues/Components/00-API-Design-Guidelines.md

Component API Design Guidelines

Use this when creating or evolving components so the API remains predictable.

Goals

• Consistency across all components
• Safe defaults for user content
• Low ceremony for common use cases
• Explicit escape hatches for advanced scenarios

Baseline API Conventions

For every new component, prefer:

• className for caller-supplied Tailwind/CSS classes
• attributes for arbitrary HTML attributes (aria-*, data-*, test IDs)
• Strongly typed semantic options where practical (enums or constants)
• Named item records instead of tuples for complex lists

Safety Rules

1. Plain text input should be encoded by default.
2. Raw HTML should require an explicit trusted path.
3. Never require callers to manually concatenate unsafe attribute strings for normal usage.

Documentation Rules

Every component doc should include:

1. Quick example
2. All options
3. Security notes
4. Accessibility notes
5. JS dependency notes (if interactive)
6. Extension points (className, attributes)

Evolution Rules

1. Prefer additive changes first.
2. Mark old APIs as deprecated with migration examples.
3. Remove deprecated paths only in major release.

Review Checklist

• Is the API consistent with sibling components?
• Can callers add classes without wrapper divs?
• Can callers pass aria-* and data-* safely?
• Are semantic options type-safe?
• Are user-provided strings encoded by default?
• Are interactive JS requirements documented?