Component Hierarchy

Component Hierarchy

Follow this selection order when choosing components for ResRequest projects.

Selection Priority

1. ShadCN-Vue Components (First Choice)

Located at @/​components/​ui/

Always check ShadCN-Vue first. These are the base UI components.

NEVER modify files in @/​components/​ui/ - these are managed by ShadCN.

2. Custom Components (Second Choice)

Located at @/​components/​custom/

Project-specific wrappers and extensions of ShadCN components.

3. Feature Components (Third Choice)

Located at @/​components/[feature]/

Domain-specific components for features like email-threads, comments, bookings.

ShadCN-Vue Component Reference

Buttons

import { Button } from '@/​components/​ui/​button'

<Button>Default</​Button>
<Button variant="destructive">Delete</​Button>
<Button variant="outline">Cancel</​Button>
<Button variant="secondary">Secondary</​Button>
<Button variant="ghost">Ghost</​Button>
<Button variant="link">Link</​Button>
<Button size="sm">Small</​Button>
<Button size="lg">Large</​Button>
<Button disabled>Disabled</​Button>

Form Inputs

import { Input } from '@/​components/​ui/​input'
import { Label } from '@/​components/​ui/​label'
import { Textarea } from '@/​components/​ui/​textarea'
import { Checkbox } from '@/​components/​ui/​checkbox'
import { RadioGroup, RadioGroupItem } from '@/​components/​ui/​radio-group'
import { Switch } from '@/​components/​ui/​switch'

// Basic input
<div class="space-y-2">
    <Label for="email">Email</​Label>
    <Input id="email" type="email" v-model="email" />
</​div>

Select/​Dropdown

import {
    Select,
    SelectContent,
    SelectItem,
    SelectTrigger,
    SelectValue,
} from '@/​components/​ui/​select'

<Select v-model="selected">
    <SelectTrigger>
        <SelectValue placeholder="Select option" />
    </​SelectTrigger>
    <SelectContent>
        <SelectItem value="option1">Option 1</​SelectItem>
        <SelectItem value="option2">Option 2</​SelectItem>
    </​SelectContent>
</​Select>

Cards

import {
    Card,
    CardContent,
    CardDescription,
    CardFooter,
    CardHeader,
    CardTitle,
} from '@/​components/​ui/​card'

<Card>
    <CardHeader>
        <CardTitle>Card Title</​CardTitle>
        <CardDescription>Card description</​CardDescription>
    </​CardHeader>
    <CardContent>
        <p>Card content</​p>
    </​CardContent>
    <CardFooter>
        <Button>Action</​Button>
    </​CardFooter>
</​Card>

Dialogs/​Modals

import {
    Dialog,
    DialogContent,
    DialogDescription,
    DialogFooter,
    DialogHeader,
    DialogTitle,
    DialogTrigger,
} from '@/​components/​ui/​dialog'

<Dialog v-model:open="isOpen">
    <DialogTrigger as-child>
        <Button>Open Dialog</​Button>
    </​DialogTrigger>
    <DialogContent>
        <DialogHeader>
            <DialogTitle>Dialog Title</​DialogTitle>
            <DialogDescription>Dialog description</​DialogDescription>
        </​DialogHeader>
        <div>Content here</​div>
        <DialogFooter>
            <Button variant="outline" @click="isOpen = false">Cancel</​Button>
            <Button @click="save">Save</​Button>
        </​DialogFooter>
    </​DialogContent>
</​Dialog>

Tables

import {
    Table,
    TableBody,
    TableCell,
    TableHead,
    TableHeader,
    TableRow,
} from '@/​components/​ui/​table'

<Table>
    <TableHeader>
        <TableRow>
            <TableHead>Name</​TableHead>
            <TableHead>Email</​TableHead>
            <TableHead>Actions</​TableHead>
        </​TableRow>
    </​TableHeader>
    <TableBody>
        <TableRow v-for="user in users" :key="user.id">
            <TableCell>{{ user.name }}</​TableCell>
            <TableCell>{{ user.email }}</​TableCell>
            <TableCell>
                <Button size="sm" variant="ghost">Edit</​Button>
            </​TableCell>
        </​TableRow>
    </​TableBody>
</​Table>

Badges

import { Badge } from '@/​components/​ui/​badge'

<Badge>Default</​Badge>
<Badge variant="secondary">Secondary</​Badge>
<Badge variant="destructive">Error</​Badge>
<Badge variant="outline">Outline</​Badge>

Alerts

import { Alert, AlertDescription, AlertTitle } from '@/​components/​ui/​alert'

<Alert>
    <AlertTitle>Heads up!</​AlertTitle>
    <AlertDescription>This is an alert message.</​AlertDescription>
</​Alert>

<Alert variant="destructive">
    <AlertTitle>Error</​AlertTitle>
    <AlertDescription>Something went wrong.</​AlertDescription>
</​Alert>

Tabs

import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/​components/​ui/​tabs'

<Tabs default-value="tab1">
    <TabsList>
        <TabsTrigger value="tab1">Tab 1</​TabsTrigger>
        <TabsTrigger value="tab2">Tab 2</​TabsTrigger>
    </​TabsList>
    <TabsContent value="tab1">Content 1</​TabsContent>
    <TabsContent value="tab2">Content 2</​TabsContent>
</​Tabs>

Custom Components

FloatingLabelInput (ALWAYS use for form fields)

import FloatingLabelInput from '@/​components/​custom/​FloatingLabelInput.vue'

<FloatingLabelInput
    v-model="form.name"
    label="Name"
    :error="form.errors.name"
    required
/>

<FloatingLabelInput
    v-model="form.email"
    label="Email"
    type="email"
    :error="form.errors.email"
/>

RRIcon (Custom icons)

import RRIcon from '@/​components/​custom/​icon/​RRIcon.vue'

<RRIcon name="calendar" />
<RRIcon name="user" class="h-5 w-5" />

Component Rules

1. Never Modify ShadCN Files

@/​components/​ui/ is READ-ONLY

To customise ShadCN components:
1. Create wrapper in @/​components/​custom/
2. Import and extend the base component
3. Add custom props/​styles in wrapper

2. Always Use FloatingLabelInput for Forms

<!-- WRONG: Raw Input -->
<Input v-model="name" />

<!-- CORRECT: FloatingLabelInput -->
<FloatingLabelInput v-model="name" label="Name" />

3. Use Tailwind Utilities Only

<!-- WRONG: Custom CSS -->
<style scoped>
.custom-button {
    background-color: blue;
}
</​style>

<!-- CORRECT: Tailwind classes -->
<Button class="bg-blue-500 hover:bg-blue-600">
    Custom Button
</​Button>

4. Check ShadCN Examples

Before creating a custom component, check if ShadCN already provides it:

• View examples at /​page/​admin/​shadcn-components in the app
• Check ShadCN-Vue documentation

5. Component Composition

Compose complex UIs from ShadCN primitives:

<Card>
    <CardHeader>
        <div class="flex items-center justify-between">
            <CardTitle>{{ title }}</​CardTitle>
            <Badge :variant="statusVariant">{{ status }}</​Badge>
        </​div>
    </​CardHeader>
    <CardContent>
        <Table>
            <!-- Table content -->
        </​Table>
    </​CardContent>
    <CardFooter class="flex justify-end gap-2">
        <Button variant="outline">Cancel</​Button>
        <Button>Save</​Button>
    </​CardFooter>
</​Card>

Import Patterns

Correct Imports

// ShadCN components - destructured import
import { Button } from '@/​components/​ui/​button'
import { Card, CardContent, CardHeader } from '@/​components/​ui/​card'

// Custom components - default import
import FloatingLabelInput from '@/​components/​custom/​FloatingLabelInput.vue'
import RRIcon from '@/​components/​custom/​icon/​RRIcon.vue'

// Feature components - default import
import CommentThread from '@/​components/​comments/​CommentThread.vue'

Import Organisation

// 1. Vue core
import { ref, computed, watch } from 'vue'

// 2. Inertia
import { useForm, router, Link } from '@inertiajs/​vue3'

// 3. ShadCN UI components
import { Button } from '@/​components/​ui/​button'
import { Card, CardContent } from '@/​components/​ui/​card'

// 4. Custom components
import FloatingLabelInput from '@/​components/​custom/​FloatingLabelInput.vue'

// 5. Composables
import { useBookings } from '@/​composables/​useBookings'

// 6. Types
import type { Booking, Property } from '@/​types'