Framer Component Best Practices

Best practices for building and improving React components in Framer with property controls, animations, and accessibility.

Core Rules

Component Structure

import { addPropertyControls, ControlType } from "framer";
import { motion } from "framer-motion"; // NOT from "framer"

interface MyComponentProps {
  /* typed props */
}

/**
 * @framerSupportedLayoutWidth any-prefer-fixed
 * @framerSupportedLayoutHeight any-prefer-fixed
 */
export default function MyComponent(props: MyComponentProps) {
  // component
}

addPropertyControls(MyComponent, {
  /* controls */
});

Platform Constraints

These will cause errors if violated:

1. •Single file, default export - Use named function syntax (not arrow functions), no named exports
2. •Imports - Only react, react-dom, framer, framer-motion. Import motion from "framer-motion", not "framer"
3. •Position - Use position: relative on the root element, never fixed
4. •SSR - Guard window/document access: if (typeof window !== "undefined")
5. •Annotations - Include @framerSupportedLayoutWidth/Height in a /** */ block comment immediately above the component function
6. •Types - Provide a typed props interface (e.g. MyComponentProps). Avoid NodeJS types like Timeout — use number instead

Layout Annotations

Detect auto vs fixed sizing: check if style.width or style.height is "100%".

Property Controls

To make components configurable in Framer's properties panel, add property controls:

• •To make colors customizable, use ControlType.Color. Reuse the same prop for elements sharing a color.
• •To make text styling customizable, use ControlType.Font with controls: "extended" and defaultFontType: "sans-serif".
• •For images, use ControlType.ResponsiveImage. Set defaults in the component body via destructuring (the control doesn't support defaultValue).
• •Provide a defaultValue for every prop so components render correctly in the Framer canvas. Include at least one item in ControlType.Array controls.
• •ComponentName.defaultProps is not supported in Framer — use defaultValue on the property control instead.
• •Use hidden for conditional visibility: hidden: (props) => !props.showFeature
• •Prefer sliders over steppers unless step values are large.
• •Keep controls focused — make key elements configurable, hardcode the rest.
• •See Property Control Guide for detailed patterns, font styling rules, and recommended default values.

Image Defaults (in component body)

const {
  image = {
    src: "https://framerusercontent.com/images/GfGkADagM4KEibNcIiRUWlfrR0.jpg",
    alt: "Default",
  },
} = props;

Animation Performance

import { useIsStaticRenderer } from "framer";
import { useInView } from "framer-motion";

const isStatic = useIsStaticRenderer();
const ref = useRef(null);
const isInView = useInView(ref);

if (isStatic) return <StaticPreview />; // Show useful static state
// Pause animations when out of viewport

• •For very complex animations, consider WebGL instead of framer-motion.
• •Static preview should include visual effects, not just text.
• •Wrapping state updates in startTransition() prevents UI blocking and keeps interactions smooth.

Text

• •For auto-sized components with text, apply width: max-content or minWidth: max-content to prevent text from collapsing.

Common Errors

• •WebGL cross-origin: handle SecurityError: Failed to execute 'texImage2D' for cross-origin images.
• •Inverted Y-axis: check if WebGL images render upside down and accommodate.

Accessibility

• •aria roles on interactive elements
• •Semantic HTML (<nav>, <article>, <section>)
• •alt="" on decorative images
• •4.5:1 color contrast

Term Interpretation

• •"responsive" → width/height 100%
• •"modern" → 8px radius, 16px spacing, subtle shadows
• •"minimal" → limited colors, whitespace
• •"interactive" → hover/active states
• •"accessible" → ARIA, semantic HTML
• •"props"/"properties" → Framer property controls

Reference Files

• •Property Controls - All ControlType documentation with examples
• •Property Control Types - TypeScript interfaces for all control types
• •Property Control Guide - Font patterns, styling rules, and recommended default values
• •Example Components - Cookie banner, image compare, sticky notes, twemoji