dotfiles/.local/aider/projects/runcats/read/docs/quasar-components.md

Below is a cheat-sheet of the Quasar components most teams reach for first, each with a minimal syntax example and the props/events you’ll touch 90 % of the time. (For exhaustive API cards, jump to the linked docs pages.)

---

1. Layout primitives

<q-layout>

<q-layout view="hHh lpR fFf" container>
  <q-header elevated>…</q-header>
  <q-drawer v-model="left" show-if-above>…</q-drawer>

  <q-page-container>
    <router-view />
  </q-page-container>
</q-layout>

Key props

prop	type	purpose
view	String	The 3×3 matrix that decides if header/footer/drawers are Hidden/Reveal/Fixed on each platform.
container	Boolean	Constrains layout to parent width (nice for centered apps).
height-hint	Number	SSR fallback when JS can’t compute window height.

Events: @scroll, @resize.

---

<q-header> / <q-footer>

<q-header elevated reveal height-hint="56">…</q-header>

Common props: elevated, reveal, bordered, height-hint; events @reveal, @hide.

<q-drawer>

<q-drawer v-model="left" side="left" overlay behavior="desktop" width="260">
  …
</q-drawer>

Important props: v-model, side, overlay, behavior, width, mini, mini-to-overlay, bordered.

<q-page> & friends

<q-page> goes inside <q-page-container> and auto-offsets for the header/footer/drawers. Add <q-page-sticky> or <q-page-scroller> when you need floating buttons or “back-to-top”.

---

2. Action components

<q-btn>

<q-btn color="primary"
       icon="save"
       label="Save"
       outline
       :loading="saving"
       @click="save" />

frequently-used prop	effect
label, icon, icon-right	Button content.
color, text-color	Palette control.
flat, outline, unelevated, push, round, dense	Visual variants.
size	XS → XL tokens or CSS value.
to, href, type	Router / link / native-form support.
disable, loading, ripple	Interactivity toggles.

<q-tabs> + <q-tab> / <q-route-tab>

<q-tabs v-model="tab" align="justify" dense>
  <q-tab name="info"  icon="info"  label="Info"/>
  <q-tab name="posts" icon="article" label="Posts"/>
</q-tabs>

<q-tab-panels v-model="tab" animated>
  <q-tab-panel name="info"> … </q-tab-panel>
  <q-tab-panel name="posts"> … </q-tab-panel>
</q-tab-panels>

Key props: v-model, align, breakpoint, vertical, dense, shrink, class. QTab adds name, icon, label, alert, badge.

---

3. Forms & inputs

<q-input>

<q-input v-model="email"
         type="email"
         label="E-mail"
         outlined
         clearable
         :rules="[val => !!val || 'Required']"/>

Essential props: type, label, placeholder, outlined|filled|borderless|rounded, dense, clearable, prefix, suffix, hint, error, error-message, debounce, rules, lazy-rules.

<q-select>

<q-select v-model="country"
          :options="countries"
          option-label="name"
          option-value="code"
          emit-value map-options
          filled clearable />

Hot props: options, option-label, option-value, emit-value, map-options, multiple, use-input, use-chips|chips, dense, clearable, popup-content-class, loading, virtual-scroll.

<q-form>

<q-form @submit.prevent="submit" ref="f">
  …
</q-form>

@submit, @reset events; imperative methods validate(), resetValidation(), getValidationComponents().

Quasar Form-Input Components

Component	Minimal syntax example	What it’s for
QField	vue<br><q-field label="Label"><template #control>…</template></q-field>	Gives any custom control a Quasar-style label, hint, error/validation and dense/outlined looks.
QInput	vue<br><q-input v-model="text" outlined label="Name" />	Text / number / email etc. input with masks, debounced v-model, built-in rules & slots.
QSelect	vue<br><q-select v-model="val" :options="opts" clearable />	Single- or multi-select dropdown / autocomplete (can be filterable, chip-style, virtual-scrolled).
QCheckbox	vue<br><q-checkbox v-model="agree" label="I agree" />	Standard checkbox with tri-state (checked / unchecked / indeterminate) support.
QRadio	vue<br><q-radio v-model="gender" val="M" label="Male" />	Mutually-exclusive option picker for small sets.
QToggle	vue<br><q-toggle v-model="on" label="Enabled" />	Mobile-style ON/OFF switch — boolean input with accessible keyboard support.
QOptionGroup	vue<br><q-option-group v-model="picked" :options="opts" type="checkbox" />	Renders a whole list of radios / checkboxes / toggles in one shot, keeping models in sync.
QBtnToggle	vue<br><q-btn-toggle v-model="view" :options="opt" toggle-color="primary" />	Segmented-control alternative to radios, but looking like grouped buttons.
QSlider	vue<br><q-slider v-model="age" :min="0" :max="100" />	Single-thumb numeric slider with discrete or continuous steps.
QRange	vue<br><q-range v-model="range" :min="0" :max="100" />	Dual-thumb range selector for min/max numeric values.
QKnob	vue<br><q-knob v-model="vol" :max="100" />	Rotary dial (built on QCircularProgress) for coarse or fine-grained numeric input.
QRating	vue<br><q-rating v-model="stars" :max="5" />	Star (or custom icon) rating picker that can be readonly or interactive.
QFile	vue<br><q-file v-model="files" multiple label="Choose files" />	File-chooser that returns FileList or Array<File> and shows previews/count.
QUploader	vue<br><q-uploader url="/api/upload" label="Upload" />	Drag-and-drop or click-to-upload component with queue, retry and progress bars.
QColor	vue<br><q-color v-model="hex" format="hex" />	Inline or pop-up color picker with HEX/RGB/HSV and palette presets.
QDate	vue<br><q-date v-model="day" mask="YYYY-MM-DD" />	Calendar date picker (Gregorian & Persian); supports ranges and shortcuts.
QTime	vue<br><q-time v-model="time" format24h />	Clock-face or input-field time picker with seconds, intervals and AM/PM/24-h modes.
QEditor	vue<br><q-editor v-model="html" min-height="10rem" />	Full WYSIWYG rich-text editor that reads/writes HTML and lets you extend its toolbar.

These inputs plug straight into QForm validation and inherit Quasar’s design-system props (color, dense, dark, etc.)

---

4. Data display

<q-card>

<q-card flat bordered class="my-card">
  <q-card-section class="text-h6">Title</q-card-section>

  <q-card-section>Body content…</q-card-section>

  <q-card-actions align="right">
    <q-btn flat label="Close" v-close-popup/>
  </q-card-actions>
</q-card>

Useful props: flat, bordered, square, dark. Slot helpers: q-card-section, q-card-actions, q-card-media.

<q-table>

<q-table
  :rows="rows"
  :columns="columns"
  row-key="id"
  selection="multiple"
  :pagination.sync="paged"
  :filter="filter"
  :loading="busy" />

Quick-hit props: rows, columns, row-key, selection, selected, pagination, rows-per-page-options, filter, dense, grid, virtual-scroll, loading, scoped slots for full customisation.

---

5. Overlays & feedback

<q-dialog>

<q-dialog v-model="show" persistent transition-show="scale">
  <q-card style="min-width: 350px">
    …content…
  </q-card>
</q-dialog>

Main props: v-model, persistent, maximized, full-width, full-height, position, transition-show, transition-hide, no-backdrop-dismiss. Events: @show, @hide.

<q-inner-loading>

<div class="relative-position">
  <q-inner-loading :showing="busy" />
  …content…
</div>

Props: showing, optional label, label-class, size, color.

---

Below are all Quasar components that were not covered in the previous cheat-sheet, with a one-line syntax sample and a very short “what it’s for” blurb.

Component	Minimal syntax example	Purpose
QAjaxBar	<q-ajax-bar position="top" indeterminate />	Thin loading bar that auto-shows while Ajax/fetch calls run.
QAvatar	<q-avatar size="40px" icon="person" />	Circular/square avatar that holds an icon, text or image.
QBadge	<q-badge color="red" floating>3</q-badge>	Tiny counter / status dot to highlight numbers or states.
QBanner	<q-banner class="bg-warning">New version available!</q-banner>	Prominent in-page notice with optional actions.
QBar	<q-bar class="bg-grey-2">…</q-bar>	Ultra-slim horizontal bar—handy in headers, cards or Electron apps.
QBreadcrumbs	<q-breadcrumbs><q-breadcrumbs-el label="Home"/></q-breadcrumbs>	Shows current navigation hierarchy.
QBtnDropdown	<q-btn-dropdown label="More"><q-list>…</q-list></q-btn-dropdown>	Split button that reveals a menu of extra actions.
QBtnGroup	<q-btn-group><q-btn flat label="A"/><q-btn label="B"/></q-btn-group>	Visually groups buttons, sharing borders/radius.
QCarousel	<q-carousel v-model="slide"><q-carousel-slide name="1" :img-src="url"/></q-carousel>	Swipeable / auto-playing image or content slider.
QChatMessage	<q-chat-message sent text="Hi!" />	Chat bubble for messenger-style UIs.
QChip	<q-chip icon="tag" removable>Label</q-chip>	Small pill for tags, filters, contacts, etc.
QCircularProgress	<q-circular-progress indeterminate size="40px" />	Circular spinner / progress indicator.
QExpansionItem	<q-expansion-item label="Details">Hidden stuff</q-expansion-item>	Accordion row that reveals extra content when expanded.
QFab	<q-fab icon="add"><q-fab-action icon="edit"/></q-fab>	Floating action button plus optional speed-dial actions.
QIcon	<q-icon name="mdi-home" />	Embeds Material, MDI, FontAwesome (and more) icons.
QImg	<q-img src="banner.jpg" ratio="16/9" />	Optimised image with lazy-load and blur-up placeholder.
QInfiniteScroll	<q-infinite-scroll @load="fetchMore">…</q-infinite-scroll>	Auto-loads more data when scrolled near bottom.
QIntersection	<q-intersection transition="scale">…</q-intersection>	Emits events when element enters/leaves viewport.
QLinearProgress	<q-linear-progress value="0.6" color="primary" />	Horizontal progress bar, determinate or indeterminate.
QList / QItem	<q-list bordered><q-item><q-item-section>Row</q-item-section></q-item></q-list>	Vertical list rows with rich slots; ideal for menus or data lists.
QMarkupTable	<q-markup-table flat :rows="rows" :columns="cols" />	Static HTML table—lightweight alternative to QTable.
QMenu	<q-menu anchor="bottom right"><q-list>…</q-list></q-menu>	Context pop-over anchored to any element.
QNoSsr	<q-no-ssr><client-only-widget/></q-no-ssr>	Renders slot only on client (skips SSR).
QPopupEdit	vue<br><q-popup-edit v-model="qty"><q-input type="number" /></q-popup-edit>	“Click-to-edit” helper: turns any label or cell into an inline editable pop-up.
QResizeObserver	<q-resize-observer @resize="onSize" />	Fires event whenever the parent DOM element changes size.
QScrollObserver	<q-scroll-observer @scroll="onScroll" />	Emits position & direction as the page/container scrolls.
QPagination	<q-pagination v-model="page" :max="10" />	Page number / navigation control.
QParallax	<q-parallax src="mountain.jpg" height="300" />	Hero banner with parallax scroll effect.
QPopupProxy	<q-popup-proxy anchor="bottom middle">Popover</q-popup-proxy>	Generic anchored pop-up used by many pickers/menus.
QPullToRefresh	<q-pull-to-refresh @refresh="reload" />	Mobile swipe-down-to-refresh wrapper.
QResponsive	<q-responsive :ratio="4/3"><img … /></q-responsive>	Maintains aspect ratio for embedded content.
QScrollArea	<q-scroll-area style="height:200px">…</q-scroll-area>	Custom-styled scrollable container.
QSeparator	<q-separator inset />	Horizontal/vertical divider line.
QSkeleton	<q-skeleton type="text" width="70%" />	Placeholder shimmer for loading states.
QSlideItem	<q-slide-item @right="del"><template #right>Delete</template></q-slide-item>	Mobile list-item swipe actions (e.g. mail apps).
QSlideTransition	<q-slide-transition><div v-show="open">Panel</div></q-slide-transition>	Height/width slide animation wrapper.
QSpace	<q-space />	Flexbox spacer that takes up remaining space.
QSpinner	<q-spinner-hourglass size="40px" />	Dozens of SVG/CSS loaders beyond progress bars.
QSplitter	<q-splitter v-model="split"><template #before>…</template><template #after>…</template></q-splitter>	Draggable resizer between two panes.
QStepper	<q-stepper v-model="step"><q-step name="1" title="A"/></q-stepper>	Wizard / multi-step process tracker.
QTimeline	<q-timeline><q-timeline-entry title="Start" /></q-timeline>	Vertical chronological milestones.
QToolbar	<q-toolbar><q-toolbar-title>Title</q-toolbar-title></q-toolbar>	App/header bar hosting nav and actions.
QTooltip	<q-tooltip anchor="bottom middle">Help text</q-tooltip>	Hover/click tooltip—rich content supported.
QTree	<q-tree :nodes="data" node-key="id" />	Expandable/collapsible hierarchical data viewer.
QVideo	<q-video src="https://youtu.be/abc" ratio="16/9" />	Responsive embedded video player (HTML5, YouTube, Vimeo).
QVirtualScroll	<q-virtual-scroll :items="bigList" :item-size="48" v-slot="item">{{ item }}</q-virtual-scroll>	Renders only visible rows for huge lists—boosts performance.

Note: All these components share Quasar’s global props (dark, dense, size, color, etc.) and are tree-shakable—import only what you use for lean bundles.