Framer code components are React components you write in TypeScript or JavaScript and drop into a Framer canvas like any built-in element. They give developers full access to React, Framer Motion, and the wider npm ecosystem inside a visual editor, letting teams build custom interactions, integrations, and data displays that no-code primitives cannot reach.
What Code Components Unlock
Framer is a visual editor for the most common 90 percent of web design needs. The remaining 10 percent often requires custom logic: a live data feed, a specialized animation, a third-party widget, or a calculation displayed on the page. Code components let developers write that custom logic in React and expose it to designers as a normal component instance with editable properties.
The model is identical to working in any React codebase, with the added benefit that the resulting component is immediately usable in a visual environment by anyone on the team. A developer writes the component once, the designer places it on pages, configures its props through the Framer property panel, and ships without further engineering involvement.
When to Use Code Components
Reach for a code component when one of these conditions is true. You need to render data from an external API. You need an animation or interaction not expressible through Framer built-in tools. You need to wrap a third-party JavaScript library like a chart engine, map, or video player. You need server-side calculations rendered in the client. You need a custom form behavior beyond what built-in forms allow.
For everything else, stay in the visual editor. Code components are powerful but they add a maintenance dimension. Each one is a piece of code that needs to be understood, tested, and updated by someone with React skills. Keep the surface area minimal.
Setting Up Your First Code Component
Inside a Framer project, open the assets panel and create a new code component. Framer opens a file editor with a TypeScript template. The default template renders a div with a configurable label, which is enough to show you the property panel binding system.
The component is a React functional component. It receives props through a typed interface. Each prop becomes editable in the Framer property panel when a designer places the component on a page. Property types (string, number, boolean, color, image, link, enum) are declared through Framer Property Controls, which is the bridge between TypeScript types and the visual property editor.
Property Controls
Property Controls are how you tell Framer to expose a prop in the property panel. They look like this in code:
The Framer addPropertyControls function takes the component and a configuration object. Each key in the object matches a prop name in the component interface. The value describes the type of editor to render in the property panel. A string prop with a text editor. A number prop with a slider. A color prop with the color picker. An enum prop with a dropdown.
Property Controls keep the design experience clean. Designers see a familiar property panel for your custom component with all the expected widgets, without ever needing to read the underlying code. For more on how components fit into the larger system, see our framer components guide.
Importing npm Packages
Framer supports importing from npm directly inside the code editor. Type the import statement at the top of your file, and Framer resolves the package from the npm registry. Common imports include React for hooks and JSX, framer-motion for advanced animations, date-fns for date formatting, and any small library that does one thing well.
Be mindful of bundle size. Each import adds to the published page weight. Large libraries like lodash, moment, or full chart frameworks can balloon your page size. Prefer small, single-purpose libraries or implement utility logic inline. For more on page weight, see our website speed optimization guide.
Working With Framer Motion
Framer Motion is the animation library that powers built-in Framer animations. It ships with code components by default, so you can use it directly. Motion components like motion.div, motion.button, and motion.span accept animate, transition, and initial props that handle complex animation choreography.
Combine Motion with React state for interactive animations. Use the useState hook to track interaction states, then drive Motion animate props from that state. The result is fully custom motion design with the same primitives Framer uses internally. For broader animation context, see our framer animations complete guide.
Fetching External Data
Code components can fetch data from any public API using the standard fetch API or a wrapped client. Wrap the fetch in a useEffect hook so it runs once when the component mounts, and store the result in useState to trigger re-renders when data arrives.
Handle loading and error states explicitly. Show a skeleton or placeholder while data loads. Show a friendly error message if the fetch fails. Code components without proper loading states feel broken when the network is slow.
For data that does not change often, cache the response in localStorage or use a stale-while-revalidate pattern. This keeps the page fast on repeat visits without sacrificing freshness.
TypeScript Tips
Framer code components support TypeScript natively. Use it. Strong types catch bugs early, make property controls self-documenting, and give designers better autocomplete in the property panel.
Define a strict interface for component props. Use union types for enums. Mark optional props with the question mark. Use sensible defaults inside the component body so missing props do not crash the canvas.
Server-Side Rendering Considerations
Framer pages render statically at publish time, then hydrate in the browser. Code components run during both phases. Code that touches the window, document, or other browser-only globals will fail at build time unless wrapped in a window check or a useEffect hook.
The pattern is to gate browser-only code behind useEffect, which only runs after hydration. For code that must run on the server side, use the typeof window check to skip browser-only logic during static generation.
Testing Code Components
Framer does not ship a built-in unit test framework, but you can test code components by extracting business logic into pure functions and testing those independently in a Node.js environment. For visual regression, use the Framer preview and walk through the component states by hand.
For complex components, build a dedicated test page in the project with the component in every notable state: empty, loading, populated, error, edge cases. Use this page as your QA checklist before publishing changes.
Common Patterns
The most common code component patterns include data display (fetch from API, render in styled markup), embed wrappers (encapsulate a third-party widget like a chat or scheduler), interactive calculations (mortgage calculators, ROI estimators, currency converters), and animated visualizations (custom charts, infographics, scroll-driven illustrations).
For embeds, the typical pattern is to render an empty div with a specific ID in the component, then load the third-party script in a useEffect and let it inject content into that div. This isolates the third-party logic and keeps your component declarative.
Performance and Bundle Size
Each code component adds JavaScript to the published page. Keep components lean. Avoid pulling in large dependencies for one small feature. Lazy-load components that appear below the fold using React lazy and Suspense. Profile the published page in browser dev tools to see how much JavaScript ships and from where.
For more on performance, see our website speed optimization guide.
Common Mistakes to Avoid
Building visual UI in code when the Framer canvas could do it visually is the most common mistake. Designers cannot edit code component layouts. Keep code components focused on logic and let the canvas handle layout where possible.
Pulling in massive npm dependencies for small features bloats the bundle. Vet every import for size before committing to it.
Ignoring TypeScript leads to runtime errors that propagate to design time. Define proper types from the start.
Frequently Asked Questions
Can code components access the Framer CMS?
Yes. Use the Framer CMS API or the React hooks Framer exposes for CMS data. Code components can render dynamic content from CMS collections and respond to CMS updates at publish time.
Do code components work on mobile?
Yes. Code components render in any modern browser including mobile. Pay attention to touch interaction patterns and performance, especially for components with heavy animations or large dependencies.
Can I use external CSS frameworks like Tailwind?
Yes, but with caveats. Framer styles components via inline styles or className strings, so Tailwind utility classes work if you include the Tailwind CSS bundle in the project. For most cases, write inline styles or styled-components inside the code component for better isolation.
Are code components SEO-friendly?
Yes. Framer renders the static HTML at build time, including content from code components. Search engines crawl the rendered HTML normally. Avoid client-only rendering for critical content.
How do I share code components across projects?
Framer does not have a built-in package registry. Copy the code between projects or publish to npm and import as a regular dependency, which is the cleanest approach for teams maintaining multiple sites.