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.

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

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

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

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

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

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.

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 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. 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, {
  offset: {
    type: ControlType.String,
    defaultValue: "Framer X",
    placeholder: "Type something…",
  },
}