Documentation Index
Fetch the complete documentation index at: https://mintlify.com/vuetifyjs/vuetify/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The useDefaults() composable provides access to Vuetify’s defaults system, allowing components to inherit default prop values from parent providers or global configuration.
Import
import { useDefaults } from 'vuetify'
Signature
function useDefaults<T extends Record<string, any>>(
props: T,
name?: string
): T
function useDefaults(
props?: undefined,
name?: string
): Record<string, any>
Parameters
props
Record<string, any>
default:"{}"
Component props object to merge with defaults
Component name for looking up defaults. If not provided, will be auto-detected from the component’s name or __name property.
Return Value
Proxied props object that merges component props with defaults. Values are resolved in this order:
- Explicitly provided props
- Component-specific defaults
- Global defaults
- Original prop value
Defaults Hierarchy
Defaults are resolved in the following order (highest priority first):
- Explicitly set props - Props passed directly to the component
- Component defaults - Defaults set for specific component name
- Global defaults - Defaults set for all components
- Default prop values - Component’s default prop values
Usage Examples
Basic Usage
<script setup>
import { useDefaults } from 'vuetify'
const props = defineProps({
color: String,
variant: String,
size: String
})
// Merge props with defaults for this component
const defaults = useDefaults(props, 'VBtn')
// defaults.color will use global or component-specific default if not provided
</script>
With Subcomponent Defaults
<script setup>
import { useDefaults } from 'vuetify'
const props = defineProps({
color: String,
density: String
})
const defaults = useDefaults(props)
// This also provides defaults to child components
</script>
<template>
<!-- Child VBtn will inherit defaults from parent -->
<v-card>
<v-card-actions>
<v-btn>Button inherits defaults</v-btn>
</v-card-actions>
</v-card>
</template>
Auto-detect Component Name
<script setup>
import { useDefaults } from 'vuetify'
// Component name is auto-detected from defineOptions or component name
defineOptions({ name: 'MyCustomButton' })
const props = defineProps({
color: String
})
// Will look for defaults under 'MyCustomButton'
const defaults = useDefaults(props)
</script>
Accessing Nested Defaults
<script setup>
import { useDefaults } from 'vuetify'
const props = defineProps({
color: String
})
const defaults = useDefaults(props, 'VCard')
// If defaults include VCardTitle defaults,
// they'll be available to child components
</script>
<template>
<v-card>
<v-card-title>Title inherits defaults</v-card-title>
</v-card>
</template>
Class and Style Merging
<script setup>
import { useDefaults } from 'vuetify'
const props = defineProps({
class: [String, Array, Object],
style: [String, Array, Object],
color: String
})
const defaults = useDefaults(props)
// class and style from defaults are merged (not replaced)
// with component props
</script>
<template>
<div :class="defaults.class" :style="defaults.style">
Content
</div>
</template>
Configuration Examples
Global Defaults
// vuetify.config.ts
import { createVuetify } from 'vuetify'
export default createVuetify({
defaults: {
global: {
ripple: false,
density: 'comfortable'
},
VBtn: {
color: 'primary',
variant: 'elevated'
},
VTextField: {
variant: 'outlined',
density: 'compact'
}
}
})
Scoped Defaults via Provider
<template>
<v-defaults-provider
:defaults="{
VBtn: {
color: 'secondary',
variant: 'text'
},
VTextField: {
variant: 'filled'
}
}"
>
<!-- All buttons and text fields here use these defaults -->
<v-btn>Secondary Text Button</v-btn>
<v-text-field label="Filled TextField" />
</v-defaults-provider>
</template>
Nested Component Defaults
// vuetify.config.ts
import { createVuetify } from 'vuetify'
export default createVuetify({
defaults: {
VCard: {
variant: 'elevated',
VCardTitle: {
class: 'text-h6'
},
VCardActions: {
VBtn: {
variant: 'text'
}
}
}
}
})
Special Props
_as Prop
Use the _as prop to apply defaults from a different component:
<script setup>
import { useDefaults } from 'vuetify'
const props = defineProps({
_as: String,
color: String
})
// If _as="VBtn", will use VBtn defaults
const defaults = useDefaults(props, 'MyComponent')
</script>
Advanced Usage
Conditional Defaults
<script setup>
import { useDefaults } from 'vuetify'
import { computed } from 'vue'
const props = defineProps({
disabled: Boolean,
color: String
})
const defaults = useDefaults(props)
const computedColor = computed(() =>
props.disabled ? 'grey' : defaults.color
)
</script>
Custom Default Provider
<script setup>
import { provideDefaults } from 'vuetify'
import { ref } from 'vue'
const customDefaults = ref({
VBtn: {
color: 'accent',
elevation: 2
}
})
provideDefaults(customDefaults)
</script>
<template>
<div>
<!-- Buttons here use custom defaults -->
<v-btn>Accent Button</v-btn>
</div>
</template>
Notes
- Must be called within a component setup function
- Throws an error if the Vuetify defaults provider is not found
- Automatically provides subcomponent defaults to child components
class and style props are merged (arrays combined) rather than replaced- Component name is auto-detected from Vue component metadata
- The returned props object is a Proxy that dynamically resolves values
See Also