Props ​

Esta página asume que ya has leído Fundamentos de Componentes. Léelo primero si eres nuevo en los componentes.

Declaración de Props ​

Los componentes de Vue requieren una declaración explícita de props para que Vue sepa qué props externas pasadas al componente deben tratarse como atributos de paso directo (lo cual se discutirá en su sección dedicada).

<script setup>
const props = defineProps(['foo'])

console.log(props.foo)
</script>

export default {
  props: ['foo'],
  setup(props) {
    // setup() recibe props como primer argumento.
    console.log(props.foo)
  }
}

export default {
  props: ['foo'],
  created() {
    // las props se exponen en `this`
    console.log(this.foo)
  }
}

Además de declarar las props usando un array de strings, también podemos usar la sintaxis de objeto:

export default {
  props: {
    title: String,
    likes: Number
  }
}

// en <script setup>
defineProps({
  title: String,
  likes: Number
})

// en no-<script setup>
export default {
  props: {
    title: String,
    likes: Number
  }
}

Para cada propiedad en la sintaxis de declaración de objeto, la clave es el nombre de la prop, mientras que el valor debe ser la función constructora del tipo esperado.

Esto no solo documenta tu componente, sino que también advertirá a otros desarrolladores que usen tu componente en la consola del navegador si pasan el tipo incorrecto. Discutiremos más detalles sobre la validación de props más adelante en esta página.

<script setup lang="ts">
defineProps<{
  title?: string
  likes?: number
}>()
</script>

const { foo } = defineProps(['foo'])

watchEffect(() => {
  // se ejecuta solo una vez antes de la 3.5
  // se vuelve a ejecutar cuando la prop "foo" cambia en la 3.5+
  console.log(foo)
})

const props = defineProps(['foo'])

watchEffect(() => {
  // `foo` transformado a `props.foo` por el compilador
  console.log(props.foo)
})

const { foo = 'hola' } = defineProps<{ foo?: string }>()

const { foo } = defineProps(['foo'])

watch(foo /* ... */)

watch(() => foo /* ... */)

useComposable(() => foo)

Detalles de Pase de Props ​

Casos de Nombres de Props ​

Declaramos nombres de props largos usando camelCase porque esto evita tener que usar comillas al usarlos como claves de propiedad, y nos permite referenciarlos directamente en expresiones de template porque son identificadores JavaScript válidos:

defineProps({
  greetingMessage: String
})

export default {
  props: {
    greetingMessage: String
  }
}

<span>{{ greetingMessage }}</span>

Técnicamente, también puedes usar camelCase al pasar props a un componente hijo (excepto en templates en el DOM). Sin embargo, la convención es usar kebab-case en todos los casos para alinearse con los atributos HTML:

<MyComponent greeting-message="hola" />

Usamos PascalCase para etiquetas de componentes cuando es posible porque mejora la legibilidad de el template al diferenciar los componentes de Vue de los elementos nativos. Sin embargo, no hay tanto beneficio práctico en usar camelCase al pasar props, por lo que elegimos seguir las convenciones de cada lenguaje.

Props Estáticas vs. Dinámicas ​

Hasta ahora, has visto props pasadas como valores estáticos, como en:

<BlogPost title="Mi viaje con Vue" />

También has visto props asignadas dinámicamente con v-bind o su atajo :, como en:

<!-- Asigna dinámicamente el valor de una variable -->
<BlogPost :title="post.title" />

<!-- Asigna dinámicamente el valor de una expresión compleja -->
<BlogPost :title="post.title + ' de ' + post.author.name" />

Pasando Diferentes Tipos de Valores ​

En los dos ejemplos anteriores, pasamos valores de string, pero cualquier tipo de valor puede pasarse a una prop.

Número ​

<!-- Aunque `42` es estático, necesitamos v-bind para decirle a Vue que -->
<!-- esto es una expresión JavaScript en lugar de un string.            -->
<BlogPost :likes="42" />

<!-- Asigna dinámicamente el valor de una variable. -->
<BlogPost :likes="post.likes" />

Booleano ​

<!-- Incluir la prop sin valor implicará `true`. -->
<BlogPost is-published />

<!-- Aunque `false` es estático, necesitamos v-bind para decirle a Vue que -->
<!-- esto es una expresión JavaScript en lugar de un string.               -->
<BlogPost :is-published="false" />

<!-- Asigna dinámicamente el valor de una variable. -->
<BlogPost :is-published="post.isPublished" />

Array ​

<!-- Aunque el array es estático, necesitamos v-bind para decirle a Vue que -->
<!-- esto es una expresión JavaScript en lugar de un string.                -->
<BlogPost :comment-ids="[234, 266, 273]" />

<!-- Asigna dinámicamente el valor de una variable. -->
<BlogPost :comment-ids="post.commentIds" />

Objeto ​

<!-- Aunque el objeto es estático, necesitamos v-bind para decirle a Vue que -->
<!-- esto es una expresión JavaScript en lugar de un string.                 -->
<BlogPost
  :author="{
    name: 'Verónica',
    company: 'Veridian Dynamics'
  }"
 />

<!-- Asigna dinámicamente el valor de una variable. -->
<BlogPost :author="post.author" />

Enlazando Múltiples Propiedades Usando un Objeto ​

Si deseas pasar todas las propiedades de un objeto como props, puedes usar v-bind sin un argumento (v-bind en lugar de :prop-name). Por ejemplo, dado un objeto post:

export default {
  data() {
    return {
      post: {
        id: 1,
        title: 'Mi Viaje con Vue'
      }
    }
  }
}

const post = {
  id: 1,
  title: 'Mi Viaje con Vue'
}

El siguiente template:

<BlogPost v-bind="post" />

Será equivalente a:

<BlogPost :id="post.id" :title="post.title" />

Flujo de Datos Unidireccional ​

Todas las props forman un enlace unidireccional descendente entre la propiedad hija y la propiedad padre: cuando la propiedad padre se actualiza, fluirá hacia el hijo, pero no al revés. Esto evita que los componentes hijos muten accidentalmente el estado del padre, lo que puede dificultar la comprensión del flujo de datos de tu aplicación.

Además, cada vez que el componente padre se actualiza, todas las props en el componente hijo se actualizarán con el valor más reciente. Esto significa que no debes intentar mutar una prop dentro de un componente hijo. Si lo haces, Vue te advertirá en la consola:

const props = defineProps(['foo'])

// ❌ advertencia, ¡las props son de solo lectura!
props.foo = 'bar'

export default {
  props: ['foo'],
  created() {
    // ❌ advertencia, ¡las props son de solo lectura!
    this.foo = 'bar'
  }
}

Normalmente, hay dos casos en los que es tentador mutar una prop:

1. La prop se utiliza para pasar un valor inicial; el componente hijo quiere usarlo como una propiedad de datos local después. En este caso, lo mejor es definir una propiedad de datos local que use la prop como su valor inicial:

   js

   const props = defineProps(['initialCounter'])
   
   // counter solo usa props.initialCounter como valor inicial;
   // está desconectado de futuras actualizaciones de props.
   const counter = ref(props.initialCounter)

   js

   export default {
     props: ['initialCounter'],
     data() {
       return {
         // counter solo usa this.initialCounter como valor inicial;
         // está desconectado de futuras actualizaciones de props.
         counter: this.initialCounter
       }
     }
   }

2. La prop se pasa como un valor bruto que necesita ser transformado. En este caso, lo mejor es definir una propiedad computada usando el valor de la prop:

   js

   const props = defineProps(['size'])
   
   // propiedad computada que se autoactualiza cuando la prop cambia
   const normalizedSize = computed(() => props.size.trim().toLowerCase())

   js

   export default {
     props: ['size'],
     computed: {
       // propiedad computada que se autoactualiza cuando la prop cambia
       normalizedSize() {
         return this.size.trim().toLowerCase()
       }
     }
   }

Mutando Props de Objetos / Arrays ​

Cuando se pasan objetos y arrays como props, aunque el componente hijo no puede mutar el enlace de la prop, sí podrá mutar las propiedades anidadas del objeto o array. Esto se debe a que en JavaScript los objetos y arrays se pasan por referencia, y es excesivamente costoso para Vue evitar tales mutaciones.

El principal inconveniente de tales mutaciones es que permiten al componente hijo afectar el estado del padre de una manera que no es obvia para el componente padre, lo que potencialmente dificulta el razonamiento sobre el flujo de datos en el futuro. Como mejor práctica, debes evitar tales mutaciones a menos que el padre y el hijo estén fuertemente acoplados por diseño. En la mayoría de los casos, el hijo debe emitir un evento para permitir que el padre realice la mutación.

Validación de Props ​

Los componentes pueden especificar requisitos para sus props, como los tipos que ya has visto. Si no se cumple un requisito, Vue te advertirá en la consola de JavaScript del navegador. Esto es especialmente útil al desarrollar un componente que está destinado a ser utilizado por otros.

Para especificar validaciones de prop, puedes proporcionar un objeto con requisitos de validación a la macro defineProps()opción props, en lugar de un array de strings. Por ejemplo:

defineProps({
  // Verificación de tipo básica
  // (los valores `null` y `undefined` permitirán cualquier tipo)
  propA: Number,
  // Múltiples tipos posibles
  propB: [String, Number],
  // String requerida
  propC: {
    type: String,
    required: true
  },
  // String requerida pero que puede ser nula
  propD: {
    type: [String, null],
    required: true
  },
  // Número con un valor predeterminado
  propE: {
    type: Number,
    default: 100
  },
  // Objeto con un valor predeterminado
  propF: {
    type: Object,
    // Los valores predeterminados de objetos o arrays deben ser devueltos
    // desde una función factory. La función recibe las
    // props sin procesar recibidas por el componente como argumento.
    default(rawProps) {
      return { message: 'hola' }
    }
  },
  // Función validadora personalizada
  // todas las props se pasan como 2do argumento en 3.4+
  propG: {
    validator(value, props) {
      // El valor debe coincidir con uno de estos strings
      return ['success', 'warning', 'danger'].includes(value)
    }
  },
  // Función con un valor predeterminado
  propH: {
    type: Function,
    // A diferencia del valor predeterminado de objeto o array, esta no es
    // una función factory - es una función para servir como valor predeterminado
    default() {
      return 'Función predeterminada'
    }
  }
})

export default {
  props: {
    // Verificación de tipo básica
    //  (los valores `null` y `undefined` permitirán cualquier tipo)
    propA: Number,
    // Múltiples tipos posibles
    propB: [String, Number],
    // String requerida
    propC: {
      type: String,
      required: true
    },
    // String requerida pero que puede ser nula
    propD: {
      type: [String, null],
      required: true
    },
    // Número con un valor predeterminado
    propE: {
      type: Number,
      default: 100
    },
    // Objeto con un valor predeterminado
    propF: {
      type: Object,
      // Los valores predeterminados de objetos o arrays deben ser devueltos
      // desde una función factory. La función recibe las
      // props sin procesar recibidas por el componente como argumento.
      default(rawProps) {
        return { message: 'hola' }
      }
    },
    // Función validadora personalizada
    // todas las props se pasan como 2do argumento en 3.4+
    propG: {
      validator(value, props) {
        // El valor debe coincidir con uno de estos strings
        return ['success', 'warning', 'danger'].includes(value)
      }
    },
    // Función con un valor predeterminado
    propH: {
      type: Function,
      // A diferencia del valor predeterminado de objeto o array, esta no es
      // una función factory - es una función para servir como valor predeterminado
      default() {
        return 'Función predeterminada'
      }
    }
  }
}

Detalles adicionales:

• Todas las props son opcionales por defecto, a menos que se especifique required: true.

• Una prop opcional ausente que no sea Boolean tendrá un valor undefined.

• Las props Boolean ausentes se convertirán a false. Puedes cambiar esto configurando un default para ella, por ejemplo: default: undefined para que se comporte como una prop no booleana.

• Si se especifica un valor default, se utilizará si el valor de la prop resuelto es undefined; esto incluye tanto cuando la prop está ausente como cuando se pasa un valor undefined explícito.

Cuando falla la validación de una prop, Vue producirá una advertencia en la consola (si se utiliza la versión de desarrollo).

Verificaciones de Tipo en Tiempo de Ejecución ​

El type puede ser uno de los siguientes constructores nativos:

• String
• Number
• Boolean
• Array
• Object
• Date
• Function
• Symbol
• Error

Además, type también puede ser una clase o función constructora personalizada y la aserción se realizará con una verificación instanceof. Por ejemplo, dada la siguiente clase:

class Person {
  constructor(firstName, lastName) {
    this.firstName = firstName
    this.lastName = lastName
  }
}

Podrías usarla como el type de una prop:

defineProps({
  author: Person
})

export default {
  props: {
    author: Person
  }
}

Vue usará instanceof Person para validar si el valor de la prop author es realmente una instancia de la clase Person.

Tipo Nulo ​

Si el tipo es requerido pero puede ser nulo, puedes usar la sintaxis de array que incluye null:

defineProps({
  id: {
    type: [String, null],
    required: true
  }
})

export default {
  props: {
    id: {
      type: [String, null],
      required: true
    }
  }
}

Ten en cuenta que si type es solo null sin usar la sintaxis de array, permitirá cualquier tipo.

Conversión Booleana ​

Las props con tipo Boolean tienen reglas de conversión especiales para imitar el comportamiento de los atributos booleanos nativos. Dado un <MyComponent> con la siguiente declaración:

defineProps({
  disabled: Boolean
})

export default {
  props: {
    disabled: Boolean
  }
}

El componente puede usarse así:

<!-- equivalente a pasar :disabled="true" -->
<MyComponent disabled />

<!-- equivalente a pasar :disabled="false" -->
<MyComponent />

Cuando una prop se declara para permitir múltiples tipos, también se aplicarán las reglas de conversión para Boolean. Sin embargo, hay un caso límite cuando tanto String como Boolean están permitidos: la regla de conversión booleana solo se aplica si Boolean aparece antes de String:

// disabled se convertirá a true
defineProps({
  disabled: [Boolean, Number]
})

// disabled se convertirá a true
defineProps({
  disabled: [Boolean, String]
})

// disabled se convertirá a true
defineProps({
  disabled: [Number, Boolean]
})

// disabled se analizará como un string vacío (disabled="")
defineProps({
  disabled: [String, Boolean]
})

// disabled se convertirá a true
export default {
  props: {
    disabled: [Boolean, Number]
  }
}

// disabled se convertirá a true
export default {
  props: {
    disabled: [Boolean, String]
  }
}

// disabled se convertirá a true
export default {
  props: {
    disabled: [Number, Boolean]
  }
}

// disabled se analizará como un string vacío (disabled="")
export default {
  props: {
    disabled: [String, Boolean]
  }
}