Edit Page

#Property Controls

Add controls to your components to allow customization via the Framer X interface.
Property Controls allow users to pass properties (or props) to a code component through the Framer X interface. When a user selects a code component on the canvas, its Property Controls are visible on the properties panel. As a component author, it’s up to you to decide which Property Controls to add and what options they should present to the user.

#Adding Controls

To give your component Property Controls, import both the addPropertyControls function and the ControlType type from the framer library.

Below your component, call the addPropertyControls function with two arguments: first, the name of your component; and second, an object that defines controls for different properties. You have several types of controls to choose from, each of which are documented on this page.

Property Controls only effect components on the canvas. For this reason, you'll still want to use defaultProps for your component's props, both to prevent errors as you code the component and when a designer creates an instance of your component from code.

In this example, we’re adding a Property Control for our component's text prop. On the canvas, selecting the component will now display a control that allows us to set this property.

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: "Hello World" },
})

#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 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.

export function MyComponent(props) {
  const frames = props.images.map(image => <Frame image={image} width={"1fr"} height={"1fr"} />)
  return <Stack size={"100%"}>{frames}</Stack>
}

addPropertyControls(MyComponent, {
  images: {
    type: ControlType.Array,
    propertyControl: {
      type: ControlType.Image
    }
  },
  // Allow up to five items
  maxCount: 5,
})

addPropertyControls(MyComponent, {
  children: {
    type: ControlType.Array,
    propertyControl: {
      type: ControlType.ComponentInstance
    },
    maxCount: 5,
  },
})

#Boolean

#ControlType.Boolean

A 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.

export function MyComponent(props) {
  return <Frame size={"100%"}>{props.showText ? "Hello World" : null}</Frame>
}

addPropertyControls(MyComponent, {
  showText: {
    type: ControlType.Boolean,
    title: "Show Text",
    defaultValue: true,
    enabledTitle: "On",
    disabledTitle: "Off",
  },
})

#Color

#ControlType.Color

A control that represents a color value. It will be included in the component props as a string. 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.

function MyComponent(props) {
  return <Frame background={props.background} size={"100%"} />
}

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

#ComponentInstance

#ControlType.ComponentInstance

A control that references to another component on the canvas, included in the component props as a React node. 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.

export function MyComponent(props) {
  return <Stack size={"100%"}>{props.children}</Stack>
}

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

#Enum

#ControlType.Enum

A property control that represents a list of options. The list contains primitive values and each value has to be unique. 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. displaySegmentedControl can be enabled to display a segmented control instead.

export function MyComponent(props) {
  const value = props.value || "a"
  const colors = { a: "red", b: "green", c: "blue" }
  return <Frame background={colors[value]} size={"100%"}>{value}</Frame>
}

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

#File

#ControlType.File

A control that allows the user to pick a file resource. It will be included in the component props as an URL string. 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.

export function MyComponent(props) {
  return (
    <Frame size={"100%"}>
      <video
        style={{ objectFit: "contain", props.width, props.height }}
        src={props.filepath}
        controls
      />
    </Frame>
  )
}

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

#FusedNumber

#ControlType.FusedNumber

A 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.

export function MyComponent({
  radius = 50,
  topLeft,
  topRight,
  bottomRight,
  bottomLeft,
  isMixed = false,
}) {
  const borderRadius = isMixed
    ? `${topLeft}px ${topRight}px ${bottomRight}px ${bottomLeft}px`
    : `${radius}px`
  return <Frame background={"red"} borderRadius={borderRadius} size={"100%"}></Frame>
}

addPropertyControls(MyComponent, {
  radius: {
    type: ControlType.FusedNumber,
    title: "Radius",
    defaultValue: 50,
    toggleKey: "isMixed",
    toggleTitles: ["All", "Individual"],
    valueKeys: ["topLeft", "topRight", "bottomRight", "bottomLeft"],
    valueLabels: ["NW", "NE", "SE", "SW"],
    min: 0,
  },
})

#Image

#ControlType.Image

A control that allows the user to pick an image resource. It will be included in the component props as an URL string. Displayed as an image picker with associated file picker. The chosen asset will be provided as a fully qualified URL.

function MyComponent(props) {
  return <Frame image={props.image} size={"100%"} />
}

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

#Number

#ControlType.Number

A 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 enabled to include a stepper control instead.

export function MyComponent(props) {
  return <Frame rotateZ={props.rotation} size={"100%"}>{rotation}</Frame>
}

addPropertyControls(MyComponent, {
  rotation: {
    type: ControlType.Number,
    defaultValue: 0,
    min: 0,
    max: 360,
    unit: "deg",
    step: 0.1,
    displayStepper: true,
  },
})

#SegmentedEnum

#ControlType.SegmentedEnum

Deprecated, please use ControlType.Enum and enable displaySegmentedControl.

export function MyComponent(props) {
  const value = props.value || "a"
  const colors = { a: "red", b: "green", c: "blue" }
  return <Frame background={colors[value]} size={"100%"}>{value}</Frame>
}

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

#String

#ControlType.String

A control that accepts plain text values. This will be provided directly as a property. Will display an input field with an optional placeholder value. If obscured attribute is set to true a password input field will be used instead of a regular text input so that the value in the input will be visually obscured, yet still be available as plain text inside the component

export function MyComponent(props) {
  return <Frame size={"100%"}>{props.title}</Frame>
}

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