Using symbols to create custom input UIs

This guide will show you how to use symbols to create custom UIs that you can use as inputs to other components or pages.

We'll hook up an external API to pull data into builder, and then allow users to select data from the API that they want to use as an input to their component or page.

Creating the input Symbol

Basic setup

For this example, I'm going to use an API from NASA that returns some images taken by the Mars Rover. The API request I'm using is: https://api.nasa.gov/mars-photos/api/v1/rovers/curiosity/photos?sol=1000&api_key=API_KEY&page=1

To bind the response data to your symbol state, click on the + DATA SOURCE button in the Data tab of the Builder Editor. A popup will appear where you can add the API request and the state property you want to bind the results to, in this case we use roverImages.

For more information on using external data in Builder, check out our guide on advanced data fetching: https://builder.io/c/docs/guides/advanced-data. Using these techniques, you could set up an input that has a search bar and fetches data from an API based on the input then displays the some output for the user to select from.

Now that we have the results on our state object, we can repeat over the image results and bind the image values to an image that will show up in the editor.

You'll notice a few important pieces to the screenshot above:

• First we're adding state.roverImages.photos to the Repeat for Each field of the Builder editor. Make sure you have selected the image layer or whatever layer you want to repeat.
• Second, add a new binding to the image and for the left-side value select image, and on the right you can use the dropdown to select the Img Src property that the NASA API return for each photo we're iterating over.

note: if you want to manually enter a value or the dropdown isn't working, the syntax to access an individual item inside a list that you're iterating over is to add Item to the name of the list. In this example, you'll see that it's photosItem

Sometimes you need to modify the property that you're binding to, in this case the API is returning images with http instead of the secure https we need to display the images properly. Thankfully the url is the same, we just need to add s string replacement on the property:

Next we need to add a new input to save the results of the user choice, we'll call this "Value". It's not being used in this symbol, but it will be used by the parent page/component.

We'll also need a click handler to listen to user interactions with the symbol:

Inside the action, we have access to the click event, and we can pull the image src attribute and save it to the "Value" state we created above.

Now our symbol is done and we're ready to use the symbol in a new page.

Adding the symbol as an input

Our page is going to be very simple, just some text and then an image that's bound to the image the user chooses from the symbol input UI.

To add the symbol to the page, navigate to the data tab and add a new field. We'll call it Custom:

Click the "type" dropdown and select Custom, then add the id of the symbol you previously created:

You can get form the url of the page, if the symbol you're editing is on builder.io/content/123456789 then the id of the symbol is 123456789

Now add a new binding on the image: use the dropdown to choose Image on the left and the Custom field you just created on the right:

That's it, now you can choose an image in the input area on the left and it'll bind the result to the image on the page.

Here is a screencast of the final product: https://cdn.builder.io/api/v1/file/assets%2F920a1a1d699d49c2994859ebc647fc8f%2Fcad907aa4f044439991f1c4682b0ce9a `