htmltools Library for HTML Generation

Warnings

• breaking `HTML` objects no longer inherit directly from `str` and now inherit from `collections.UserString`.
  Fix: Avoid treating `HTML` objects as raw strings directly. If string-like operations are needed, access the underlying string via the object's methods or by explicit conversion if `UserString` methods are insufficient. This was done to prevent confusion and unexpected behavior when `HTML` objects were implicitly converted or manipulated as plain strings.
• breaking `TagList` objects no longer inherit directly from `list` and now inherit from `collections.UserList`.
  Fix: Avoid treating `TagList` objects as raw lists directly. Access elements and perform list-like operations using the object's methods (e.g., `append`, `extend`, indexing) rather than relying on direct list inheritance. This change aims to reduce confusion and provide more controlled behavior.
• breaking `Tag` and `TagList`'s method `.get_html_string()` now returns a plain `str` instead of an `HTML` object.
  Fix: If you previously expected the return value of `.get_html_string()` to be an `HTML` object (e.g., for further `HTML` object-specific methods), you might need to re-wrap the result in `HTML()` explicitly, although in most rendering contexts, a standard `str` should be sufficient.
• gotcha The `css()` function translates Python keyword arguments into CSS property names. It automatically converts `_` (underscore) and `camelCase` to `kebab-case`.
  Fix: When using `css()`, prefer Pythonic names like `background_color` or `backgroundColor`; the function will correctly convert them to `background-color` in the output CSS. This is a convenience feature, but can be confusing if not expected.
• gotcha The default value for the `_add_ws` parameter in `Tag` functions changed for inline vs. block elements in version 0.2.0.
  Fix: By default, block elements like `div()` now have `_add_ws=True` (add whitespace), while inline elements like `span()` have `_add_ws=False` (no whitespace). If precise control over whitespace between sibling elements is critical, explicitly set `_add_ws=True` or `_add_ws=False` on `Tag` function calls.

Install

• pip install htmltools Install stable version

Imports

• HTML

  from htmltools import HTML

• TagList

  from htmltools import TagList

• Tag

  from htmltools import Tag

  While `Tag` exists, it's generally recommended to use the tag functions from `htmltools.tags` (e.g., `tags.div()`, `tags.a()`) for convenience rather than instantiating `Tag` directly.
• tags

  from htmltools import tags

  `tags` is an object that provides convenient access to common HTML tag functions (e.g., `tags.div`, `tags.p`).
• HTMLDependency

  from htmltools import HTMLDependency

  Used for bundling CSS and JavaScript resources.
• css

  from htmltools import css

  A helper function for generating CSS style declarations.

Quickstart

This quickstart demonstrates creating a hierarchical HTML structure using `tags` functions, applying CSS styles with `css()`, defining an `HTMLDependency` for external assets, and rendering the combined output to a string using `TagList().get_html_string()`.

from htmltools import HTML, TagList, tags, HTMLDependency, css

# Create a simple HTML tag
my_div = tags.div(
    tags.h1('Hello, htmltools!'),
    tags.p('This is a paragraph generated programmatically.'),
    tags.a('Learn more', href='https://github.com/rstudio/py-htmltools'),
    _class='container',
    style=css(background_color='lightblue', padding='15px')
)

# Create an HTML dependency (e.g., for a CSS file)
my_dependency = HTMLDependency(
    name='my-custom-css',
    version='1.0.0',
    source={'package': 'my_app', 'subdir': 'assets'},
    stylesheet={'href': 'style.css'}
)

# Combine into a TagList and render
output_html = TagList(my_div, my_dependency).get_html_string()

print(output_html)