chris/dotfiles
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
main
dotfiles/.local/aider/projects/runcats/read/docs/quasar-components.md

276 lines
20 KiB
Markdown
Raw Permalink Normal View History

Add aider prompts for runcats project
2025-06-20 23:11:38 +01:00
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>`
```vue
<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>`
```vue
<q-header elevated reveal height-hint="56">…</q-header>
```
Common props: `elevated`, `reveal`, `bordered`, `height-hint`; events `@reveal`, `@hide`.
### `<q-drawer>`
```vue
<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>`
```vue
<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>`
```vue
<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>`
```vue
<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>`
```vue
<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>`
```vue
<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>`
```vue
<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>`
```vue
<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>`
```vue
<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>`
```vue
<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.
Reference in New Issue Copy Permalink