Blocks: interactive components beyond the kit

The UI kit covers forms, tables, sheets and pages. Some screens need more: a stepper for a quantity, a price filter with two handles, photos in a carousel, a month of bookings, a board of cards to drag. The renox-blocks crate adds eleven such components, as template macros built on the kit:

They're a separate crate, not part of the kit, so the kit stays small: a page loads the blocks' script only when it has a block, and then only the code of the blocks it has. examples/bikeshop uses every one of them; its /about/blocks page shows them side by side.

In this guide:

• Add it to your app
• How blocks behave
• Input blocks
• Showing data
• Scheduling and work
• Texts in other languages
• Changing the look
• How the files load
• Testing

#Words you'll meet

#Add it to your app

Add the crate next to renox, at the same version:

[dependencies]
renox = "1.0"
renox-blocks = "1.0"

Then add its module:

use renox::prelude::*;
use renox_blocks::Blocks;

pub fn app() -> App {
    App::new().module(Blocks::new())
}

The module adds the macros (renox-blocks/blocks.html) and serves the blocks' stylesheet and scripts under /_renox/blocks/. The blocks are built on the UI kit, so the page's layout needs {{ renox_ui() }} as for the kit's own components. Import what a page uses:

{% from "renox-blocks/blocks.html" import quantity, swatches, gallery %}

#How blocks behave

Every block follows the same rules, so you can rely on them without reading each one:

• Plain fields. The input blocks send normal form fields, so Valid<T> reads them, a failed submit shows the old input and the error under the block (the kit's rx-error place), and bag= names an error bag as for the kit's fields. Every value is checked on the server again: a block that greys something out is a help, not a guarantee.
• The keyboard. Everything a pointer does, the keyboard does too; each block below says how.
• Screen readers. Every control has a name, states are said in words (never by colour alone), and the kanban board announces each move.
• The kit's look. Classes start with rx- like the kit's, colours, type, spacing and radii are the kit's tokens (--rx-*), and layouts are CSS grid, so themes, dark mode, the accent and the type scale follow the kit. Text meets WCAG AA contrast in light and dark.
• Motion. The gallery slides, a moved card glides into place and a timeline fades in, with the browser's own Web Animations on transform and opacity. Under prefers-reduced-motion nothing moves.
• CSP. No inline scripts or handlers: the blocks work under CSP=strict.
• htmx. A block that htmx swaps into the page later (a sheet, a fragment) is set up when it arrives.

#Input blocks

#quantity

A number with − and + buttons, for how many of something (a cart line, a stock count). It sends one field, name, so read it as an integer:

{{ quantity("qty", 1, min=1, max=10, label="Quantity") }}

The field is a native number input: Tab reaches it, the arrow keys step it and typing works. The buttons step it too (Tab skips them, since the arrow keys in the field do the same), grey out at the limits, and send input and change on each step, so htmx triggers and live validation see it. A cart that saves each change:

{{ quantity("quantity", line.quantity, min=1, max=20, hide_label=true,
            label="Quantity of " ~ line.name, id="qty-" ~ line.id,
            attrs={"hx-patch": route('cart.update', line.id), "hx-trigger": "change delay:300ms"}) }}

#range_slider

A range with two handles, such as a price filter. It sends two fields, name_min and name_max:

{{ range_slider("price_min", "price_max", 0, 1000000, step=25000,
                value_min=100000, value_max=500000, label="Price", format="money") }}

It is two native range inputs on one track, so each handle is a real slider: Tab reaches it, the arrow keys, Page Up/Down, Home and End move it, and a screen reader says its value in words. The handles never cross: the one moving stops at the other. Without JavaScript they are still two sliders that send both fields. Check min <= max on the server too (lte).

#keypad

A point-of-sale number pad that types into a field of the form, for a touch screen at a counter:

{{ input("paid", "Amount paid", attrs={"inputmode": "numeric", "maxlength": "9"}) }}
{{ keypad("rx-paid", decimal=true, enter_label="Pay") }}

The keys are one Tab stop: the arrow keys move between them, Home and End go to the first and last, Enter or Space presses one. While the pad has the focus, typing digits, the decimal point, Backspace and Delete (clear) works as on its keys. Each press sends input to the field (its maxlength is respected); the Enter key submits the field's form (requestSubmit, so required and htmx run as for a click). The decimal key shows the page language's separator.

#swatches

Variants (a frame size, a colour) as chips: a group of radio buttons, so one field, name:

{{ swatches("size", "Frame size", [
     {"value": "S", "label": "S", "note": "150–165 cm"},
     {"value": "M", "label": "M"},
     {"value": "XL", "label": "XL", "disabled": true}
   ], selected="M", required=true) }}
{{ swatches("colour", "Colour", [
     {"value": "teal", "label": "Teal", "color": "#0b6e66"},
     {"value": "sand", "label": "Sand", "color": "#d8c7a3"}
   ], kind="colour", attrs={"hx-get": route('product.variant', product.id),
     "hx-trigger": "change", "hx-target": "#price", "hx-include": "closest form"}) }}

Tab reaches the group and the arrow keys choose, as for any radios. A chosen chip has an accent border and a tick (a shape, not only a colour); a disabled one is crossed out and "sold out" for screen readers. With kind="colour" each chip shows its colour beside the label, so the colour is never the only way to tell. Works without JavaScript.

#datetime_range

A start and an end, each a day and a time, such as a rental from Friday 10:00 to Sunday 18:00. It sends two fields, name_start and name_end, each YYYY-MM-DDTHH:MM:

{{ datetime_range("starts_at", "ends_at", label="Rental", min="2026-10-06",
                  max="2026-12-31", step=30, opens=9, closes=19, required=true) }}

Each end is the kit's date_picker (type a day or pick it on the calendar) beside a select of times. The script writes the two fields that are sent and says how long the range is ("1 day 2 hours"); the end's calendar starts at the start's day, and an end before the start is pointed out at once. Read them as NaiveDateTime (Renox adds the seconds) and check the order on the server:

use renox::chrono::NaiveDateTime;
use renox::prelude::*;

#[derive(serde::Deserialize)]
struct RentalForm {
    starts_at: Option<NaiveDateTime>,
    ends_at: Option<NaiveDateTime>,
}

impl Validate for RentalForm {
    fn rules(&self, v: &mut Validator) {
        v.field("starts_at", &self.starts_at).required();
        v.field("ends_at", &self.ends_at)
            .required()
            .gt("starts_at", &self.starts_at);
    }
}

This block needs JavaScript (the sent fields are written by it).

#Showing data

#gallery

Photos as a carousel, with thumbnails under it and an enlarged view in the kit's sheet:

{{ gallery([
     {"src": "/img/city-1.jpg", "alt": "The City 3 from the side", "caption": "Teal, size M"},
     {"src": "/img/city-2.jpg", "alt": "Its handlebar", "large": "/img/city-2-big.jpg"}
   ], id="city-photos", label="Photos of the City 3") }}

The arrows, the thumbnails, a swipe, or the keyboard (Left/Right, Home/End while the focus is in the gallery) change the photo, and a screen reader hears which photo of how many it is. Only the current photo can be reached; "Enlarge" opens it in a sheet (Escape closes it and the focus comes back). Without JavaScript the photos scroll sideways and the thumbnails are links.

#history

A vertical timeline of what happened to something: an order, a repair, a document.

{{ history([
     {"time": "2026-10-06T09:12:00Z", "title": "Checked in", "body": "Brakes **squeal**.", "kind": "info"},
     {"time": "2026-10-06T11:40:00Z", "title": "Ready for pickup", "kind": "success", "by": "Marta"}
   ], label="Service history", date_format="%d %b %H:%M") }}

An ordered list, each event with its time first. kind sets the marker's colour and its icon, and screen readers hear it in words ("done", "needs attention"). body is Markdown (the markdown filter: raw HTML is shown as text). The events fade in one after the other the first time the list scrolls into view.

#compare_plans

Pricing cards side by side, then a table comparing every feature, with one plan highlighted:

{{ compare_plans([
     {"key": "basic", "name": "Basic", "price": 2900, "interval": "month",
      "description": "For weekend rides.", "perks": ["A check-up a month"], "url": "/plans/basic"},
     {"key": "rider", "name": "Rider", "price": 4900, "interval": "month", "url": "/plans/rider"},
     {"key": "fleet", "name": "Fleet", "price_label": "Ask us", "url": "/contact"}
   ], [
     {"label": "Visits a month", "values": {"basic": "1", "rider": "2", "fleet": "Unlimited"}},
     {"label": "Pickup and delivery", "values": {"basic": false, "rider": true, "fleet": true}}
   ], highlight="rider", label="Service plans") }}

The cards sit on a CSS grid (one column on a phone, up to four). The highlighted card has the accent border and a "Most popular" badge, and its column in the table is tinted. In the table true is a tick and false a dash, with "Included" and "Not included" for screen readers. On a phone the table scrolls sideways inside its frame (the keyboard can scroll it too), with the feature names staying put.

#Scheduling and work

#month_calendar

One month as a grid of days with what happens on each, and links to the months around it. On a phone it becomes a list of the days that have something.

{{ month_calendar("2026-10", [
     {"date": "2026-10-06", "time": "09:30", "title": "Tune-up · City 3", "url": "/visits/4", "kind": "info"},
     {"date": "2026-10-06", "title": "Rental: Trail 5", "kind": "success"}
   ], url=route('visits.index'), today="2026-10-06", label="Service visits") }}

The days are an ordered list on a seven-column grid, so a screen reader reads them in order, each with its full weekday and "Today" when it is. The previous and next months are links (?month=YYYY-MM on url), so each month has its own address; pair them with hx-boost and hx-select to change only the calendar. The template has no clock: pass today from the handler. The month is worked out in the template, so no Rust helper is needed.

#availability

A timeline of resources (bikes, rooms, people) against hours or days, with the booked and free slots; a free slot is a link or a small form that books it:

{{ availability(["09:00", "10:00", "11:00", "12:00"], [
     {"label": "Trail 5", "note": "M · #12", "slots": [
        {"state": "booked", "span": 2, "title": "Ana R."},
        {"state": "free", "url": "/rent?bike=12&at=11"},
        {"state": "free", "action": "/rentals", "fields": {"bike": 12, "at": "12:00"}}]}
   ], label="Bikes free today", corner="Bike") }}

It is a table: each resource is a row heading and each time a column heading, so a screen reader reads "Trail 5, 11:00, Book". Every free slot says what it books ("Book Trail 5 at 11:00"). Booked slots are striped and closed ones dashed, each with its word, so no state rests on colour alone; a legend says what they mean. On a phone the table scrolls sideways inside its frame with the resources staying put. A slot with action is a form POSTed with its fields and the CSRF field, so booking needs no JavaScript.

#kanban

Columns of cards moved between columns by dragging, or with the keyboard, each move sent to the server with htmx:

{{ kanban("jobs", [
     {"key": "waiting", "title": "Waiting", "cards": [
        {"id": 7, "title": "Tune-up", "subtitle": "City 3 · Ana", "badge": "Today", "badge_kind": "warning"}]},
     {"key": "working", "title": "In the stand", "cards": []},
     {"key": "ready", "title": "Ready", "cards": []}
   ], url=route('jobs.move'), values={"store": 2}, label="Workshop jobs") }}

Each move is an htmx POST to url with the fields card (the card's id), column (the new column's key) and position (0 for the top), plus values and the CSRF header htmx gets from Renox. Answer 2xx to keep the move; any other status puts the card back and says so:

use renox::prelude::*;

#[derive(serde::Deserialize)]
struct Move {
    card: Option<i64>,
    column: Option<String>,
    position: Option<i64>,
}

impl Validate for Move {
    fn rules(&self, v: &mut Validator) {
        v.field("card", &self.card).required();
        v.field("column", &self.column)
            .required()
            .one_of(&["waiting", "working", "ready"]);
        v.field("position", &self.position).required().min(0);
    }
}

/// Saves the card's column and order (after checking the person may move it).
async fn move_card(Valid(_form): Valid<Move>) -> StatusCode {
    StatusCode::NO_CONTENT
}

With a mouse, drag a card anywhere; with a finger or a pen, drag it by its handle (the dots), so a swipe elsewhere still scrolls the page. With the keyboard, Tab to a card, then Space or Enter picks it up, the arrow keys move it (Up/Down in its column, Left/Right to the next column), Space or Enter drops it and Escape puts it back; without a card picked up the arrow keys move between cards. Every step is announced. A card's own link (url) still opens it. After the server answered, the board sends rx:kanban-moved with {card, column, position, ok} in detail. Without JavaScript the board is a read-only list.

kanban_card(card) prints one card, for a fragment that adds a card to a board already on the page; the board sets it up when htmx swaps it in.

#Texts in other languages

The blocks' texts are English unless your app's lang files have them, under the same keys (renox_blocks::TEXTS lists them all, with the English):

{
  "blocks": {
    "quantity": { "label": "Cantidad", "increase": "Uno más (:label)", "decrease": "Uno menos (:label)" },
    "gallery": { "next": "Foto siguiente", "previous": "Foto anterior", "position": "Foto :n de :total" },
    "calendar": { "today": "Hoy", "month_10": "Octubre" }
  }
}

:name placeholders are filled as the t function fills them. Texts you pass to a macro (label=, enter_label=, a plan's cta) are yours, so translate them with t as usual.

#Changing the look

The blocks use the kit's tokens, so a theme that changes the accent, the surfaces or the radii changes them too. To change one block's markup, copy the macros into your app as resources/views/renox-blocks/blocks.html: your file replaces the crate's.

#How the files load

The first block on a page prints two tags: the blocks' stylesheet and blocks.js, a JavaScript module. The module looks at the page (and at whatever htmx swaps in later) and imports a block's code only when the page has that block: a product page with a gallery and a stepper loads gallery.js and quantity.js, nothing else. swatches, compare_plans, month_calendar and availability need no code at all.

The files are compiled into the crate, with no library and no build step. The app serves them itself from /_renox/blocks/, under names that carry a hash of their content, with a year-long cache and no session cookie. A browser runs each module once per page.

#Testing

The input blocks are plain form fields, so test your handlers by posting what the browser would send:

use renox::prelude::*;
use renox::testing::TestApp;

#[derive(serde::Deserialize, Validate)]
struct CartLine {
    #[validate(required, between(1, 20))]
    quantity: Option<i64>,
    #[validate(required, one_of(&["S", "M", "L"]))]
    size: Option<String>,
}

struct Cart;

impl Module for Cart {
    fn name(&self) -> &'static str { "cart" }

    fn routes(&self) -> Routes {
        Routes::new().post("/cart", |Valid(line): Valid<CartLine>| async move {
            format!("{} × {}", line.quantity.unwrap_or(0), line.size.unwrap_or_default())
        })
    }
}

#[renox::test]
async fn a_line_is_added() {
    let app = TestApp::new(App::new().module(renox_blocks::Blocks::new()).module(Cart)).await;
    app.post("/cart", &[("quantity", "2"), ("size", "M")])
        .await
        .assert_ok()
        .assert_see("2 × M");
    // The stepper stops at its max in the browser; the server stops it too.
    app.htmx()
        .post("/cart", &[("quantity", "21"), ("size", "M")])
        .await
        .assert_invalid("quantity");
}

TestApp doesn't run JavaScript, so check the blocks themselves in a browser (see testing.md); the crate's own checks are tests/browser/blocks.test.mjs.