Props

Props are properties sent from the Design Editor to your component(s).

Base

All props share these common properties:

Name/type	Description
name string	Name of the prop
type string	Type of the prop. Can be one of the following: `string \| number \| boolean \| image \| video \| audio \| color \| icon \| object \| array \| select \| link \| upload \| menu \| layout \| variable`.
title string	Title of the prop visible in the edtior. If not set, a sentence case of the name will be used
description string	Description of the prop visible in the editor.
component ReactNode	Replaces the field with a custom React component.
initialValue JSON	The initial value for the field. Have to match the type of the field. Can also be a function or `async` function returning the value. Function takes one argument with the type context.
validate boolean \| function	Can either be `boolean` or a function returning `boolean`. The first argument of the function is the `value` of the field and the second is the context of the entire form.
hidden boolean \| function	Hide/show field. Can either be `boolean` or a function returning `boolean`. The first argument of the function is the context of the entire form. The second is the `index` of the current array item, or `undefined` if the field is not inside an array. Can be used to toggle visibility based on values from other fields, e.g. `hidden: (context, index) => !context.value.cards[index].showTitle`.
onChange function	A custom `onChange` for the field. The first argument of the function is the `value` of the field and the second is the context of the entire form.
storage string	Select where to store values for the component (like API keys etc.). Can be `project \| workspace \| account`.

String

A field type for string.

type: "string",

Options:

Options	Description
type string	Can be `'text' \| 'date' \| 'email' \| 'url' \| 'password'`. Default is `text`.
multiline boolean \| number	Select if the field should be multiline or not. Can either be `boolean` or a `number` representing the lines of the text the field should include.
minLength number	The minimum characters for the field.
maxLength number	The maximum characters for the field.

Example:

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      name: 'title',
      type: 'string',
      options: {
        minLength: 10,
        maxLength: 20,
      },
    },
  ],
});

See recipe: Hello World

Number

A field type for number.

type: "number",

Options	Description
min number	The minimum number for the field.
max number	The maximum number for the field.
format string	This will appear as a suffix for the number. Can be `'%' \| 'px' \| 'deg'`.
display string	The appearance of the field. Can be `'input' \| 'slider'`. Used for displaying a slider instead of a number field. Default is: `input`.
scale number	Set a custom scale for the field. If you want percent from 0-1 set scale to 100

Example:

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      name: 'price',
      type: 'number',
      options: {
        min: 100,
        max: 1000,
      },
    },
  ],
});

Boolean

A field type for boolean. This will display a toggle switch in the form.

type: "boolean",

Example:

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      name: 'showOnMobile',
      type: 'boolean',
    },
  ],
});

See recipe: Conditional rendering

Select

Can be used to display either radio buttons, a dropdown or multiselect.

type: "select",

Options:

Options	Description
items array	An array of options in this format: `label: string, value: string`. Can also be `async`.
display string	Can be: `'checkbox' \| 'radio' \| 'dropdown' \| 'autocomplete'`. Default is `dropdown`.
multiselect boolean	If it should be possible to select multiple values.

Example:

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      name: 'selectFruits',
      type: 'select',
      options: {
        display: 'radio',
        items: [
          { label: 'Apple', value: 'apple' },
          { label: 'Orange', value: 'orange' },
          { label: 'Banana', value: 'banana' },
        ],
      },
    },
  ],
});

See recipe: Select

Image

A field type for image. This will display an image upload field in the editor.

type: "image",

Example:

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      name: 'image',
      type: 'image',
    },
  ],
});

See recipe: Image with caption

Video

A field type for video. This will display a video upload field in the editor.

type: "video",

Example:

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      name: 'video',
      type: 'video',
    },
  ],
});

Audio

A field type for audio. This will display an audio upload field in the editor.

type: "audio",

Example:

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      name: 'audio',
      type: 'audio',
    },
  ],
});

Color

A field type for color. This will display a color picker in the editor.

type: "color",

Example:

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      name: 'backgroundColor',
      type: 'color',
    },
  ],
});

See recipe: Editable CSS

Icon

A field type for icon. This will display an icon/shape picker in the editor.

type: "icon",

Example:

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      name: 'icon',
      type: 'icon',
    },
  ],
});

Link

A field for link. This will display a link field in the editor. This will give a search field for internal links. If an internal link is not selected it will behave like an external link.

type: "link",

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      name: 'link',
      type: 'link',
    },
  ],
});

Object

A field type for object. This can be used to display fields in a group. All the Vev props can be used as fields.

type: "object",
fields: VevProps[],

Example

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      name: 'header',
      type: 'object',
      fields: [
        {
          name: 'title',
          type: 'string',
        },
        { name: 'subtitle', type: 'string' },
        { name: 'image', type: 'image' },
      ],
    },
  ],
});

Array

A field type for array. The of property defines which item types are available when adding to the list.

Simple arrays

For arrays of a single primitive type, set of to 'string' or 'number':

{
  name: 'tags',
  type: 'array',
  of: 'string',
}

Array of objects (most common)

Wrap fields in a single object entry. Since there is only one option, no type dropdown is shown — every item has the same fields:

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      name: 'products',
      type: 'array',
      of: [
        {
          name: 'product',
          type: 'object',
          fields: [
            { name: 'title', type: 'string' },
            { name: 'price', type: 'number' },
            { name: 'image', type: 'image' },
          ],
        },
      ],
    },
  ],
});

Mixed arrays

When of contains multiple entries, the editor shows a dropdown when adding an item so the user can choose the type:

{
  name: 'content',
  type: 'array',
  of: [
    { name: 'Text', type: 'string' },
    { name: 'Image', type: 'image' },
  ],
}

List preview

Every element in an array field, can have custom list preview. If not defined, the Editor will try to fined the fields from the data.

Options	Description
preview object	can either be an `object` or a `function` which returns an object: `title: string, image: string`.

Example

{
  name: "products",
  type: "array",
  of: [
    {
      name: "item",
      type: "object",
      preview(value) {
        return {
          title: value.title,
          image: value.image,
        };
      },
      fields: [
        {
          name: "title",
          type: "string",
        },
        { name: "image", type: "image" },
      ],
    },
  ],
}

See recipe: Card list

Layout

A field to be used for layout.

type: "layout",
fields: VevProps[],

Options:

Options	Description
display string	Can be `row \| column`. Default is `row`.

Example:

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      type: 'layout',
      options: {
        display: 'row',
      },
      fields: [
        { name: 'x', type: 'number' },
        { name: 'y', type: 'number' },
        { name: 'z', type: 'number' },
      ],
    },
  ],
});

Upload

A field to be used for uploading files.

type: "upload",
fields: VevProps[],

Options:

Options	Description
accept string	A comma separated list of unique file type specifiers.

Example

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      type: 'upload',
      accept: '.jpg,.png',
    },
  ],
});

Variable

A field used for getting variable keys. Use in conjunction with useVariable and useSetVariable.

type: "variable",

Options:

Options	Description
variableType string	Filter variables by type. Can be `'color' \| 'number' \| 'font' \| 'text'`.

Example

registerVevComponent(MyComponent, {
  name: 'My component',
  props: [
    {
      name: 'variableKey',
      type: 'variable',
    },
  ],
});

See Recipes for practical examples using props.

Base

String

Number

Boolean

Select

Image

Video

Audio

Color

Icon

Link

Object

Example

Array

Simple arrays

Array of objects (most common)

Mixed arrays

List preview

Example

Layout

Upload

Example

Menu

Example

Variable

Example