Skip to content
ReferenceAdvancedUnderstand the extra keyword attributes components accept.

Keywords every component accepts

Beyond its own parameters, every component accepts extra keyword arguments. They fall into five families, and all five work on any component, from Button to Table.

from drafter import *


@route
def index() -> Page:
    return Page([
        Header("Every family at once", style_color="darkslateblue"),
        Button("Styled", "index", style_font_size="20px"),
        "\n",
        TextBox("word", "", placeholder="an HTML attribute at work"),
        "\n",
        Button("Wired", "index", on_mouseenter="react"),
        "\n",
        Output("noticeboard", ["Hover the Wired button."])
    ])


@route
def react() -> Fragment:
    return Fragment(["I felt that."], target="#noticeboard")


start_server()

style_*: one CSS property each

Any keyword starting with style_ sets the matching CSS property on that component. Underscores become hyphens: style_background_color="lavender" sets background-color. Values are CSS text, units included ("20px", not 20).

The styling functions set exactly the same properties from outside the constructor; use whichever reads better.

classes: names for CSS to find

classes="card" (or classes="card highlighted" for several) tags the component so a CSS rule from add_website_css or a theme can find it. The how-to is Custom CSS.

id: a name for targeting

id="scoreboard" gives the component a unique name on the page. Ids are how a Fragment finds its target (target="#scoreboard") and how a Label attaches to an input. Use each id only once per page; when two components share an id, targeting becomes unreliable.

on_*: events that call routes

Keywords like on_click, on_input, and on_change name a route (as a string, or the function itself) to run when that event happens. The supported events are blur, change, focus, input, keydown, keyup, keypress, mouseenter, mouseleave, mouseover, mouseout, click, and dblclick. The concept, with a worked demo, is Live updates.

Plain HTML attributes

Each component also understands the HTML attributes that make sense for its element: placeholder="Type here" or maxlength=20 on a TextBox, rows=6 on a TextArea, accept="image/*" on a FileUpload, disabled=True on a Button. A shared baseline of attributes (id, title, hidden, data_* attributes, and similar) works on every component. Underscores become hyphens on the way out, so data_role="hero" renders as data-role="hero".

If a component does not recognize a keyword as an attribute, Drafter treats the keyword as a CSS style instead. This rule is what makes bare color="red" work, but it also means an unsupported attribute quietly becomes a meaningless style rather than an error.

Notes

  • Misspellings fail silently. A misspelled style_colour or on_clik is not an error: it becomes a CSS property that no browser recognizes, so it has no visible effect. When a keyword seems to be ignored, check its spelling first.
  • Boolean attributes render bare: disabled=True renders as disabled, the way HTML expects, and disabled=False omits the attribute entirely.
  • Styles set here are testable with assert_style; other assertions ignore styling by default.