Framer Code Components Overrides

Framer Code Development

Section tags: [C] applies to code components, [O] to code overrides, [C/O] to both.

Pitfalls (quick lookup)

Contents

• Foundations — components vs overrides, annotations, starter templates
• Authoring — property controls, fonts, color tokens
• Rendering & SSR — hydration, canvas detection, concurrent rendering, npm imports
• CMS — text timing in overrides, code-component CMS pattern
• Overrides — specific patterns — variant control, fiber handlers
• DOM & Performance — scroll detection, live-read refs, portals, common patterns
• Media — HLS video, WebGL
• Debug — gated logging

Foundations

Code Components vs Overrides

Code Components `[C]`: Custom React components added to canvas. Support addPropertyControls.

Code Overrides `[O]`: Higher-order components wrapping existing canvas elements. Do NOT support addPropertyControls.

Required Annotations [C/O]

Always include at minimum:

/**
 * @framerDisableUnlink
 * @framerIntrinsicWidth 100
 * @framerIntrinsicHeight 100
 */

Full set:

• @framerDisableUnlink — Prevents unlinking when modified
• @framerIntrinsicWidth / @framerIntrinsicHeight — Default dimensions
• @framerSupportedLayoutWidth / @framerSupportedLayoutHeight — any, auto, fixed, any-prefer-fixed

Code Override Pattern [O]

import type { ComponentType } from "react"
import { useState, useEffect } from "react"

/**
 * @framerDisableUnlink
 */
export function withFeatureName(Component): ComponentType {
    return (props) => {
        // State and logic here
        return <Component {...props} />
    }
}

Naming: Always use withFeatureName prefix.

Overrides Must Be Literal Exports (picker detection) [O]

Framer's override picker statically scans the file and only lists exports it can syntactically recognize as an override — a literal function declaration or an arrow assigned directly to the export. An export whose value is the return of a function call is invisible to the scanner: it won't appear in the Override dropdown (even though it would work if referenced by name).

This bites hardest when you try to DRY up several near-identical overrides with a factory:

// ❌ BROKEN — factory hides the overrides from the picker.
// Only literal functions in the file get listed; these three never appear.
const setVariant = (name) => (Component) => (props) => {
    const [, setStore] = useStore()
    return <Component {...props} onClick={() => setStore({ variant: name })} />
}
export const withSetVariant1 = setVariant("Variant 1") // not listed
export const withSetVariant2 = setVariant("Variant 2") // not listed
export const withSetVariant3 = setVariant("Variant 3") // not listed

// ✅ CORRECT — each override is a literal function; all are listed.
export function withSetVariant1(Component): ComponentType {
    return (props) => {
        const [, setStore] = useStore()
        return <Component {...props} onClick={() => setStore({ variant: "Variant 1" })} />
    }
}

Both literal forms are recognized: export function withX(Component) {…} or export const withX = (Component) => (props) => …. The rule: never produce an override by calling a helper — repeat the literal per override, even if it's more verbose. (Full worked example — 3 setters + 1 reader sharing a store — in references/patterns.md → Shared State Between Overrides.)

Code Component Pattern [C]

import { motion } from "framer-motion"
import { addPropertyControls, ControlType } from "framer"

/**
 * @framerDisableUnlink
 * @framerIntrinsicWidth 300
 * @framerIntrinsicHeight 200
 */
export default function MyComponent(props) {
    const { style } = props
    return <motion.div style={{ ...style }}>{/* content */}</motion.div>
}

MyComponent.defaultProps = {
    // Always define defaults
}

addPropertyControls(MyComponent, {
    // Controls here
})

Authoring

Property Controls Reference [C]

See references/property-controls.md for complete control types and patterns.

Font Handling [C/O]

Never access font properties individually. Always spread the entire font object.

// ❌ BROKEN - Will not work
style={{
    fontFamily: props.font.fontFamily,