Edit Page

#Property Controls

Add controls to your components to allow customization via the Framer X interface.

Property Controls allow code components to add interface elements to Framer X that are accessible from within your components via properties. This allows you to create customizable settings for anyone that uses it. Custom controls can be added via the addPropertyControls function.

First, pass along the name of your component (here it’s MyComponent), then an object with all control definitions. In this example, we’re only adding a single custom property: text. If you drag the component on the Canvas in Framer X, you’ll be able to override the text contents of the component.

import * as React from "react"
import {
  Frame,
  addPropertyControls,
  ControlType,
} from "framer"

export function MyComponent(props) {
  return <Frame>{props.text}</Frame>
}

MyComponent.defaultProps = {
  text: "Hello World!",
}

addPropertyControls(MyComponent, {
  text: { type: ControlType.String, title: "Text" },
})

#Hiding Controls

Controls can be hidden by adding the hidden function to the property description. The function receives an object containing the set properties and returns a boolean. In this example we hide the text property entirely when the connected property (the toggle) is false.

Now you can toggle the visibilty of the text property control by changing the toggle boolean from within the property panel in Framer X.

export function MyComponent(props) {
  return <div>{props.text}</div>
}

MyComponent.defaultProps = {
  text: "Hello World!",
  toggle: true,
}

addPropertyControls(MyComponent, {
  toggle: {
    type: ControlType.Boolean,
    title: "Toggle",
    enabledTitle: "Show",
    disabledTitle: "Hide",
  },
  text: {
    type: ControlType.String,
    title: "Text",
    hidden(props) {
      return props.toggle === false
    },
  },
})

#Array

#ControlType.Array

A property control that allows multiple values per ControlType, provided as an array via properties. For most control types this will be displayed as an additional section in the properties panel allowing as many fields to be provided as required.

For a ControlType.ComponentInstance the Frame will also gain an additional outlet control on the Canvas that allows links to be created between frames.

addPropertyControls(MyComponent, {
  images: {
    type: ControlType.Array,
    propertyControl: {
      type: ControlType.Image
    }
  },
  children: {
    type: ControlType.Array,
    propertyControl: {
      type: ControlType.ComponentInstance
    }
  },
})

#Boolean

#ControlType.Boolean

A property control that displays an on / off checkbox. The associated property will be true or false, depending on the state of the checkbox. Includes an optional defaultValue, which is set to true by default. You can also customize the labels displayed in the property panel with the enabledTitle and disabledTitle properties.

addPropertyControls(MyComponent, {
  isCentered: {
    type: ControlType.Boolean,
    title: "Center",
    defaultValue?: true,
    enabledTitle?: "On",
    disabledTitle?: "Off",
  },
})

#Color

#ControlType.Color

A property control that represents a color value. It will be provided as a string via properties. This control is displayed as a color field and will provide the selected color in either HEX ("#fff") or HSL (hsla(203, 87%, 50%, 0.5)) notation, depending on whether there is an alpha channel.

addPropertyControls(MyComponent, {
  background: {
    type: ControlType.Color,
    defaultValue: "#fff",
  },
})

#ComponentInstance

#ControlType.ComponentInstance

A property control that references to another components on the canvas, provided via a property. The component will have an outlet to allow linking to other Frames. Available Frames will also be displayed in a dropdown menu in the properties panel. The component reference will be provided as a property. As a convention, the name for the property is usually just children.

Multiple components can be linked by combining the ComponentInstance type with the ControlType.Array.

addPropertyControls(MyComponent, {
  children: {
    type: ControlType.ComponentInstance,
  },
})

#Enum

#ControlType.Enum

A property control that represents a list of options. The selected option will be provided as a property. This control is displayed as a dropdown menu in which a user can select one of the items.

addPropertyControls(MyComponent, {
  value: {
    type: ControlType.Enum,
    defaultValue: "a",
    options: ["a", "b", "c"],
    optionTitles: ["Option A", "Option B", "Option C"],
  },
})

#File

#ControlType.File

A property control that represents a resource. It will be provided as an URL via properties. Displayed as an file picker that will open a native file browser. The selected file will be provided as a fully qualified URL. The allowedFileTypes property must be provided to specify acceptable file types.

addPropertyControls(MyComponent, {
  asset: {
    type: ControlType.File,
    allowedFileTypes: ["pdf"],
  },
})

#FusedNumber

#ControlType.FusedNumber

A property control that can be used to take a single number or four distinct numeric input fields. The typical use case for this control is for visual properties like border, padding or margin. It will display an input field to accept a single value, alongside a segmented control allowing four distinct values to be provided.

addPropertyControls(MyComponent, {
  title: {
    type: ControlType.FusedNumber,
    defaultValue: 0,
    toggleKey: "isPerSide",
    valueKeys: ["top", "left", "right", "bottom"],
    valueLabels: ["T", "L", "R", "B"],
    min: 0,
  },
})

#Image

#ControlType.Image

A property control that represents an image resource. It will be provided as an URL via properties. Displayed as an image picker with associated file picker. The chosen asset will be provided as a fully qualified URL.

addPropertyControls(MyComponent, {
  avatar: {
    type: ControlType.Image,
  }
})

#Number

#ControlType.Number

A property control that accepts any numeric value. This will be provided directly as a property. Will display an input field with a range slider by default. The displayStepper option can be provided to include a stepper control instead.

addPropertyControls(MyComponent, {
  offset: {
    type: ControlType.Number,
    defaultValue: 5,
    min: 0,
    max: 10,
    unit: "px",
    step: 0.1,
    displayStepper: true,
  },
})

#SegmentedEnum

#ControlType.SegmentedEnum

A property control that represents a list of option. The selected option will be provided as a property. This control is displayed as a segmented control. Otherwise, it behaves exactly the same as ControlType.Enum.

addPropertyControls(MyComponent, {
  value: {
    type: ControlType.SegmentedEnum,
    defaultValue: "a",
    options: ["a", "b", "c"],
    optionTitles: ["Option A", "Option B", "Option C"],
  },
})

#String

#ControlType.String

A property control that accepts plain text values. This will be provided directly as a property. Will display an input field with an optional placeholder value.

addPropertyControls(MyComponent, {
  offset: {
    type: ControlType.String,
    defaultValue: "Framer X",
    placeholder: "Type something…",
  },
}