custom_ui/frontend/documentation/components/Modal.md

Dynamic Modal Component Documentation

Overview

A flexible and customizable modal component built with Vuetify's v-dialog. This component provides extensive configuration options and supports slot-based content rendering.

Basic Usage

<template>
  <Modal
    v-model:visible="isModalVisible"
    :options="modalOptions"
    @close="handleClose"
    @confirm="handleConfirm"
  >
    <p>Your modal content goes here</p>
  </Modal>
</template>

<script setup>
import { ref } from 'vue'
import Modal from './components/Modal.vue'

const isModalVisible = ref(false)
const modalOptions = {
  title: 'My Modal',
  maxWidth: '500px'
}

const handleClose = () => {
  console.log('Modal closed')
}

const handleConfirm = () => {
  console.log('Modal confirmed')
}
</script>

Props

visible (Boolean)

• Default: false
• Description: Controls the visibility state of the modal
• Usage: Use with v-model:visible for two-way binding

options (Object)

• Default: {}
• Description: Configuration object for customizing modal behavior and appearance

Options Object Properties

Dialog Configuration

• persistent (Boolean, default: false) - Prevents closing when clicking outside or pressing escape
• fullscreen (Boolean, default: false) - Makes the modal fullscreen
• maxWidth (String, default: '500px') - Maximum width of the modal
• width (String) - Fixed width of the modal
• height (String) - Fixed height of the modal
• attach (String) - Element to attach the modal to
• transition (String, default: 'dialog-transition') - CSS transition name
• scrollable (Boolean, default: false) - Makes the modal content scrollable
• retainFocus (Boolean, default: true) - Retains focus within the modal
• closeOnBack (Boolean, default: true) - Closes modal on browser back button
• closeOnContentClick (Boolean, default: false) - Closes modal when clicking content
• closeOnOutsideClick (Boolean, default: true) - Closes modal when clicking outside
• closeOnEscape (Boolean, default: true) - Closes modal when pressing escape key

Styling Options

• overlayColor (String) - Color of the backdrop overlay
• overlayOpacity (Number) - Opacity of the backdrop overlay
• zIndex (Number) - Z-index of the modal
• dialogClass (String) - Additional CSS classes for the dialog
• cardClass (String) - Additional CSS classes for the card
• cardColor (String) - Background color of the card
• cardVariant (String) - Vuetify card variant
• elevation (Number) - Shadow elevation of the card
• flat (Boolean) - Removes elevation
• noRadius (Boolean) - Removes border radius

Header Configuration

• title (String) - Modal title text
• showHeader (Boolean, default: true) - Shows/hides the header
• showHeaderDivider (Boolean) - Shows divider below header
• headerClass (String) - Additional CSS classes for header
• showCloseButton (Boolean, default: true) - Shows/hides close button
• closeButtonColor (String, default: 'grey') - Color of close button
• closeIcon (String, default: 'mdi-close') - Icon for close button

Content Configuration

• message (String) - Default message content (HTML supported)
• contentClass (String) - Additional CSS classes for content area
• contentHeight (String) - Fixed height of content area
• contentMaxHeight (String) - Maximum height of content area
• contentMinHeight (String) - Minimum height of content area
• noPadding (Boolean) - Removes padding from content area

Actions Configuration

• showActions (Boolean, default: true) - Shows/hides action buttons
• actionsClass (String) - Additional CSS classes for actions area
• actionsAlign (String) - Alignment of action buttons ('left', 'center', 'right', 'space-between')

Button Configuration

• showConfirmButton (Boolean, default: true) - Shows/hides confirm button
• confirmButtonText (String, default: 'Confirm') - Text for confirm button
• confirmButtonColor (String, default: 'primary') - Color of confirm button
• confirmButtonVariant (String, default: 'elevated') - Variant of confirm button
• showCancelButton (Boolean, default: true) - Shows/hides cancel button
• cancelButtonText (String, default: 'Cancel') - Text for cancel button
• cancelButtonColor (String, default: 'grey') - Color of cancel button
• cancelButtonVariant (String, default: 'text') - Variant of cancel button
• loading (Boolean) - Shows loading state on confirm button

Behavior Configuration

• autoCloseOnConfirm (Boolean, default: true) - Auto-closes modal after confirm
• autoCloseOnCancel (Boolean, default: true) - Auto-closes modal after cancel
• onOpen (Function) - Callback function when modal opens
• onClose (Function) - Callback function when modal closes

Events

• update:visible - Emitted when visibility state changes
• close - Emitted when modal is closed
• confirm - Emitted when confirm button is clicked
• cancel - Emitted when cancel button is clicked
• outside-click - Emitted when clicking outside the modal
• escape-key - Emitted when escape key is pressed

Slots

Default Slot

<Modal>
  <p>Your content here</p>
</Modal>

Title Slot

<Modal>
  <template #title>
    <v-icon class="mr-2">mdi-account</v-icon>
    Custom Title
  </template>
</Modal>

Actions Slot

<Modal>
  <template #actions="{ close, options }">
    <v-btn @click="customAction">Custom Action</v-btn>
    <v-btn @click="close">Close</v-btn>
  </template>
</Modal>

Usage Examples

Basic Modal

const basicOptions = {
  title: 'Information',
  maxWidth: '400px'
}

Confirmation Modal

const confirmOptions = {
  title: 'Confirm Action',
  persistent: false,
  confirmButtonText: 'Delete',
  confirmButtonColor: 'error',
  cancelButtonText: 'Keep'
}

Form Modal

const formOptions = {
  title: 'Add New Item',
  maxWidth: '600px',
  persistent: true,
  confirmButtonText: 'Save',
  loading: isLoading.value
}

Fullscreen Modal

const fullscreenOptions = {
  fullscreen: true,
  showActions: false,
  scrollable: true
}

Custom Styled Modal

const customOptions = {
  maxWidth: '500px',
  cardColor: 'primary',
  elevation: 12,
  overlayOpacity: 0.8,
  transition: 'scale-transition'
}

Advanced Usage

With Reactive Options

<script setup>
import { ref, computed } from 'vue'

const loading = ref(false)
const formValid = ref(false)

const modalOptions = computed(() => ({
  title: 'Dynamic Title',
  loading: loading.value,
  confirmButtonText: formValid.value ? 'Save' : 'Validate First',
  persistent: !formValid.value
}))
</script>

Multiple Modals

<template>
  <!-- Each modal can have different configurations -->
  <Modal v-model:visible="modal1" :options="options1">
    Content 1
  </Modal>
  
  <Modal v-model:visible="modal2" :options="options2">
    Content 2
  </Modal>
</template>

Best Practices

1. Use persistent modals for forms to prevent accidental data loss
2. Set appropriate maxWidth for different screen sizes
3. Use loading states for async operations
4. Provide clear button labels that describe the action
5. Use slots for complex content instead of the message option
6. Handle all events to provide good user feedback
7. Test keyboard navigation and accessibility features

Responsive Behavior

The modal automatically adjusts for mobile devices:

• Reduced padding on smaller screens
• Appropriate font sizes
• Touch-friendly button sizes
• Proper viewport handling

Accessibility

The component includes:

• Proper ARIA attributes
• Keyboard navigation support
• Focus management
• Screen reader compatibility
• High contrast support