{"id":5250,"library":"htmltools","title":"htmltools Library for HTML Generation","description":"htmltools is a Python library providing tools for creating, manipulating, and writing HTML. It facilitates the programmatic generation of HTML structures, including tags, attributes, and dependencies. The library is currently at version 0.6.0 and is actively maintained by Posit, with a consistent release cadence to add features and address issues.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/rstudio/py-htmltools","tags":["html","web development","templating","frontend","shiny"],"install":[{"cmd":"pip install htmltools","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for type hints and compatibility.","package":"typing-extensions","optional":false},{"reason":"Used for version parsing and comparison.","package":"packaging","optional":false}],"imports":[{"symbol":"HTML","correct":"from htmltools import HTML"},{"symbol":"TagList","correct":"from htmltools import TagList"},{"note":"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.","wrong":"from htmltools.tags import div","symbol":"Tag","correct":"from htmltools import Tag"},{"note":"`tags` is an object that provides convenient access to common HTML tag functions (e.g., `tags.div`, `tags.p`).","symbol":"tags","correct":"from htmltools import tags"},{"note":"Used for bundling CSS and JavaScript resources.","symbol":"HTMLDependency","correct":"from htmltools import HTMLDependency"},{"note":"A helper function for generating CSS style declarations.","symbol":"css","correct":"from htmltools import css"}],"quickstart":{"code":"from htmltools import HTML, TagList, tags, HTMLDependency, css\n\n# Create a simple HTML tag\nmy_div = tags.div(\n    tags.h1('Hello, htmltools!'),\n    tags.p('This is a paragraph generated programmatically.'),\n    tags.a('Learn more', href='https://github.com/rstudio/py-htmltools'),\n    _class='container',\n    style=css(background_color='lightblue', padding='15px')\n)\n\n# Create an HTML dependency (e.g., for a CSS file)\nmy_dependency = HTMLDependency(\n    name='my-custom-css',\n    version='1.0.0',\n    source={'package': 'my_app', 'subdir': 'assets'},\n    stylesheet={'href': 'style.css'}\n)\n\n# Combine into a TagList and render\noutput_html = TagList(my_div, my_dependency).get_html_string()\n\nprint(output_html)","lang":"python","description":"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()`."},"warnings":[{"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.","message":"`HTML` objects no longer inherit directly from `str` and now inherit from `collections.UserString`.","severity":"breaking","affected_versions":">=0.6.0"},{"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.","message":"`TagList` objects no longer inherit directly from `list` and now inherit from `collections.UserList`.","severity":"breaking","affected_versions":">=0.6.0"},{"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.","message":"`Tag` and `TagList`'s method `.get_html_string()` now returns a plain `str` instead of an `HTML` object.","severity":"breaking","affected_versions":">=0.6.0"},{"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.","message":"The `css()` function translates Python keyword arguments into CSS property names. It automatically converts `_` (underscore) and `camelCase` to `kebab-case`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The default value for the `_add_ws` parameter in `Tag` functions changed for inline vs. block elements in version 0.2.0.","severity":"gotcha","affected_versions":">=0.2.0 (change from older behavior)"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}