The Data Component allows you to seamlessly integrate data into your prototypes. By connecting a Smart Component you've built in Framer, you can render a list of components in your prototype that are populated by a real data source.
First, you need to decide your data source.
| Source | |
|---|---|
| API | Connect to an API. Need authentication? Use the HTTP Headers property control. |
| File | Upload a JSON/CSV/TSV file. We'll convert it into machine-speak. |
| Airtable | Connect to Airtable. Make sure an api_key query parameter appears in your URL. |
If you're prototyping for a very specific use case, you may find the out of the box features with this component insufficient. Whilst we do our best to solve a wide array of use cases, you may find it easier to write your own adapter. This will give you more control over how data is formatted/searched/sorted whilst still relying on the functionality that comes with the component itself.
Dealing with a deeply nested data structure and wondering how to map those values to the fields in your components? Maybe you want more control over how sorting/searching is handled? You probably want a custom adapter that gives you full control over this. Don't worry, it's pretty easy to build! Click here to open the example project in Framer Web and check out Example 6.
Once you've decided on your data source, you're ready to start populating your prototype with real data. You'll first need to grab the component you want to use as your list item—this will be the component that's repeated for each item in the list of data you provide. The component you connect can be a Code Component from a package/within your project, or one of Framer's Smart Components.
Smart Components use Variables and Code Components use Property Controls. These are both ways to configure how your component looks and functions, allowing you to create a generic component that can be configured wherever it's used. The naming of your Variables/Property Controls is important—these names need to match fields in your data for them to be populated correctly. Framer always uses camelCase, meaning a Variable called First Name will be referenced as firstName. The same goes for the fields in your data, if your response contains a field called first_name, it will be automatically transformed into firstName. You can use the Help mode in this component to determine what you should name your Variables/Property Controls.
The layout controls at your disposal vary depending on which direction you choose to lay elements out.
Lays the items out horizontally from left to right. Preserves the original width of the connected component.
| Horizontal | |
|---|---|
| Gap | Sets the horizontal gap in pixels between elements |
| Wrap | Items will wrap. The Reverse option makes elements flow from right to left. |
Lays the items out vertically from top to bottom. The width of the connected component will be resized to fill the available horizontal space or number of columns selected.
| Vertical | (Single Column) |
|---|---|
| Gap | Sets the vertical gap in pixels between elements |
| Distribute | Controls the vertical distribution of elements |
| Vertical | (Multiple Columns) |
|---|---|
| Gap (↔) | Sets the horizontal gap in pixels between elements |
| Gap (↕) | Sets the vertical gap in pixels between elements |
Using Framer's Scroll component, you can easily add a native feeling scroll interface to your prototype.
| Scrolling | |
|---|---|
| Scrollable | Whether the component is scrollable. The scrolling direction is inherited from the layout direction |
| Drag scroll | Enables/disables drag scrolling with built-in momentum and overdrag |
| Wheel scroll | Enables/disables scrolling with the mouse wheel |
In the same fashion as connecting a component on the canvas, you can also connect other layers to be used as empty/loading states within your component. As your prototype is now fetching data for real, depending on the user's internet connection you may want to show a helpful loading state. If your data source returns nothing, or perhaps the user is performing a search and doesn't get any results, you can connect an empty state.
The minimum amount of time to wait before displaying data. Useful for user testing scenarios with slow internet connections
By default, this component will not sort your data. This means the order in which your data source returns data is preserved. If you'd like more control over how it's sorted, you can enable Manual sorting. This component will take care of sorting alphabetically or numerically.
| Sorting | (Manual) |
|---|---|
| Property | The field in your data to sort on |
| Direction | The direction to order elements by. Defaults to ascending (lowest first) |
This component has fuzzy searching built in, allowing you to build complex searching interfaces that allow the user to approximately search for what they want. It uses the Fuse.js library to do this.
Once search is enabled, you can set a Search Query via the properties panel. In most cases, you'll probably want to leave this field blank and set your search query using Code Overrides. This example project illustrates how to build a basic search interaction using Framer's built-in Input component.
This component has 3 separate modes which can be used for guidance & troubleshooting.
| Mode | |
|---|---|
| Default | The default behavior of this component |
| Help | Instructions for how to connect this component to your data source |
| Debug | Displays the raw JSON of your data. Useful during troubleshooting |
Working with an API that requires authentication? This component allows you to attach custom HTTP Headers which will be included in the request to your chosen data source.
| HTTP Headers | (Custom) |
|---|---|
| Authorization | The HTTP Authorization header included in the request |
| HTTP Headers | A list of HTTP headers in the format Key: Value |
Feel free to leave questions/bugs on the GitHub repository for this package. You can also contact me directly on Twitter @iKettles
- The default Fuse.js search configuration is now merged with the custom configuration
- Second attempt at fixing a bug where Smart Components could disappear when being re-sorted
- Fixed a bug where Smart Components could disappear when being re-sorted
- Fixed a bug where sorting/filtering the results would create strange layout issues.
- Allow passing a custom Fuse.js configuration using the property
searchConfig
- Fixed an issue that would cause the component to disappear when used inside a hover state in a Smart Component.
- A loading state will no longer be shown when overriding the
dataproperty unless aloadingDelayproperty has been provided.
- You can now provide the property
datavia a Code Override or a Code Component. This allows you to connect the Data Component to arrays of data within your project, rather than needing to connect to an API/a file.
- The Distribute property now defaults to Start
- Remove Hover List Item functionality
- Fixed a variety of layout issues with Smart Components in different circumstances
- Fix width of list item not being set correctly
- Improved search ranking in Framer's Insert Menu
- Add support for targeting nested keys in the response
- Add support for Framer Smart Components
- Fixed objects/array types from Airtable being omitted from the response
- Fixed IDs from Airtable records being overwritten by an auto-generated ID
- Removed an unnecessary console.log
- Added support for applying padding to the container that wraps list items
- Fixed a bug that caused multiple columns to not render correctly when a hover state was being used
- Fixed a duplicate key error when using a hover state
- Added a small performance improvement when calculating the width of a list item
- Added a Hover List Item property control, allowing you to attach a hover state to your prototype.
- Improved documentation and guidance on the canvas
- The Material loading indicator from Framer's Default Components is now used as the default loading state.
- Fixes the component not having a fluid width when used with the responsive preview mode in Framer
- Added support for a custom adapter that allows you to override the behavior of searching, sorting and formatting your data.
- The index of the result in the list is now automatically passed to the rendered component
- Ensure nested objects in a connected data source does not get converted to a string
- Fix an error that could be thrown when using a nested data struecture
- Add alphabetical sorting
- Add support for custom HTTP headers
- Initial release