Query Blog Index

Quick Start

Copy these into your project:

• the <section class="kql"> element from index.html, between the EXTRACT START and EXTRACT END comments
• assets/style.css
• assets/script.js
• assets/img/ (or your own photographs)

Load the fonts and styles, then GSAP, Flip and the section script after the markup:

Code snippet omitted: it ships with the download.

Everything outside the <section> in index.html (the page background and body margin) is demo furniture. No build step is needed.

Make it yours

Posts

Each post is one <li class="kql-post" data-kql-post> inside <ol data-kql-list>, newest first. To add a post, copy a whole <li> and edit it; to remove or reorder posts, delete or move whole <li> elements. Keep the list in date order: with an empty filter the first post is the lead and the next two are cards.

Inside each post:

What	Where
Link and title	.kql-post__title a (href and text). Keep the title plain text; it is highlighted while filtering
Date	<time datetime="YYYY-MM-DD">, displayed text is yours to format
Topic	.kql-post__topic. Topic buttons and counts are built from these, in order of first appearance
Version (optional)	.kql-post__ver. Delete the span for posts without one
Summary	.kql-post__dek, shown in the lead and card slots
Author and read time	.kql-post__by and its inner <span>
Photo (optional)	.kql-post__media with its <img>

The whole card is clickable through the title link. There is no count limit; with a single post the section shows it as the lead and the filter still works. With only one topic, no topic buttons are shown.

Photos

Each photo is an ordinary <img> inside .kql-post__media:

• Files: assets/img/<name>.webp at 1600 x 1000, with an 800 x 500 copy in srcset. Any landscape photo works; 16:10 or 3:2 at 1600px wide or more is ideal. The frame is 16:10 on wide screens and 4:3 on phones, and the image is cropped to fill it.
• Replace: change src, srcset (or delete srcset), width/height to your file's size, and alt.
• Focal point: add style="--kql-focus: 50% 30%" to the <img> to move the crop (it sets object-position).
• No photo: delete the whole .kql-post__media div. In the lead or card slot the post then shows a plate with its version number, or its date when it has no version.

Load the first post's photo eagerly (as in the demo) and give the rest loading="lazy".

Heading, filter and footer

• Heading and intro: .kql__title (an h2; change the tag freely, the styles use the class) and .kql__sub.
• Feed link: .kql__feed. Older posts link: .kql__older. Both point at placeholder anchors you should replace.
• Filter label, placeholder, keyboard hints and the empty-state text live in <template data-kql-controls>. The script copies them into place, so they never show without JavaScript. The ruler text (Latest post, Best match for ...) is written by the script.
• The note in .kql__foot describes the demo content; delete it.

Brand variables

Set these on .kql (or a class you add to it):

Variable	Default	Controls
--kql-ground	#0b0d10	Section background
--kql-surface, --kql-surface-2	#12151a, #181c22	Filter bar, hovered rows, plates
--kql-line, --kql-line-strong	#242931, #353b45	Hairlines and borders
--kql-text, --kql-muted	#eceef1, #949ba6	Text colours
--kql-accent	#5de4ff	Prompt, focus, pressed topic, matches, version tags
--kql-accent-ink	#04161b	Text on a filled accent (matching version tag)
--kql-font-sans, --kql-font-mono	Geist, Geist Mono	Type roles
--kql-width, --kql-gutter, --kql-space	1360px, fluid, fluid	Content width, side padding, top and bottom space
--kql-radius	6px	Corners

A light rebrand example:

Code snippet omitted: it ships with the download.

Check the contrast of your accent against your ground; arbitrary colours are not automatically accessible.

Behaviour and options

• data-duration="0.5" on .kql sets the base transition length in seconds.
• The script mounts every [data-query-blog] on the page. For content added later, or frameworks that re-render:

Code snippet omitted: it ships with the download.

Ranking: every word typed must appear somewhere in the post. Title matches weigh most, then version, topic, summary, author and date; ties keep the newest first. A light stem lets "cache" find "caching".

Accessibility and integration

• Tested with keyboard, touch, reduced motion (including switching it while the page is open), JavaScript disabled and GSAP blocked.
• Without JavaScript the filter bar never renders and every post is listed and linked, newest first. Without GSAP the filter works with instant changes.
• / focuses the filter of the section most in view unless the visitor is typing in a field. In the filter, Down moves to the first result, Enter opens the top result and Escape clears. In the list, Up and Down move between posts, Home and End jump, and Escape returns to the filter.
• Result counts are announced through a polite status once typing pauses.
• Topic buttons use aria-pressed. IDs are made unique per instance, so two copies can share a page.
• The layout follows the section's own width (container queries), so it works in narrow columns as well as full width. It does not pin, scroll-jack or install a smooth scroller.

Dependencies and credits

• GSAP 3.15 core and Flip, loaded from jsDelivr. GSAP and its plugins are free under the GSAP standard licence.
• Geist and Geist Mono by Vercel, via Google Fonts, SIL Open Font License.
• The photographs are generated concept images made for this demo. Keelson, its people, posts and figures are fictional sample content; replace them with your own.