Custom Widgets

While building your app, you may come across a scenario where you need to use a widget that is not available in our standard widget collection. It could be a widget from pub.dev, like a unique button design, or complex, like a full chat widget with message bubbles and input fields.

Our custom widget editor enables you to add any widget to your project. It also allows you to define parameters that can be used to customize the widget. You can easily compile and preview the custom widget right inside the code editor, making the whole process of creating and integrating custom widgets much smoother and more efficient.

  • Make sure your pub.dev widget has WEB support. This is required for Run/Test mode within FlutterFlow.

  • Make sure your pub.dev widget has Null Safety support. This is required to use the Custom Widget in FlutterFlow.

Adding custom widget

Let's build a simple example and add a custom widget that draws the dotted border around the FlutterLogo using a dart package. Here is how it looks:

The steps to add a custom widget are as follows:

1. Prerequisites for adding a dependency

To use a dependency from pub.dev, you must obtain its name and import statement. See how to do it here.

2. Create custom widget

To create a custom widget:

  1. Select Custom Functions from the Navigation Menu (left side of your screen).

  2. Click + Add and select Widget. This will add the default NewCustomWidget.

  3. Set the Widget Name.

  4. In case you want to run a project, even if this widget has an error, checkmark the Exclude from compilation (see on the right).

  5. Click the [</>] icon to view the boilerplate code; a popup will open showing the starter code, and then click </> Copy to Editor.

  6. Save the progress.

Important: If 'Exclude from compilation' option is selected, we won’t check this widget for errors. This may cause errors when running your project in Run Mode or Test Mode, building APKs, and publishing to web.

3. Add widget parameters

When creating a custom widget, you can define parameters to pass data to the widget. For example, if your custom widget deals with images, you can pass the image URL as a parameter. Similarly, if it's a watch widget, you could pass the time using the Timestamp data type. Adding parameter make your custom widget more flexible.

Here's how you add widget parameters:

  1. Under Define Parameters, you will see that width and height parameters are automatically added. This is required to size the custom widget.

  2. Click on the + Add Parameter.

  3. Inside the Parameter 2 section, enter the Name (e.g., strokeWidth, customColor).

  4. Set the Type of the incoming value to a suitable type.

  5. If your custom widget needs a list of data, such as a list of numbers to display on a chart, tick the List option.

  6. When you are sure this argument will always have a value and will not be null, you can uncheck the Nullable option. For the older project (created before we rolled out the null safety feature) you need to enable null safety (from Settings and Integrations ->App Details -> Null Safety) on your project to get this option.

  7. Click the [</>] icon to view the boilerplate code; a popup will open showing the updated code, and then click </> Copy to Editor.

  8. Save the progress.

4. Add dependencies

To use the custom widget code, you need to specify the dependency name in our code editor. To do so, click on + Add Dependency and paste the dependency name obtained in this step, click the refresh button, and Save the progress.

A package might depend on other dependencies to work. So, make sure to add all the other dependencies as well. Note that Flutter and rxDart are added by default in your project, so you do not need to add these.

To add an additional dependency, click on + Add Dependency button again, paste its name, click the refresh, and Save the progress.

5. Add import statement + widget code

A package import statement is usually a path where the code for the custom widget resides. Adding an import statement makes the custom widget code accessible for use.

To do so:

  1. Inside the code editor, add the import statement at the begining (obtained in this step).

  2. Add the code snippet of your custom widget. Most dependencies on pub.dev will have a sample code in Readme or Example section. You can copy-paste the code snippet and keep the required parameters.

  3. Replace the hard-coded parameter values in the code with the ones you defined in this step. For example, strokeWidth: 1 to strokeWidth: myStrokeWidth.

  4. Save the progress.

Optional: notice that we wrapped the custom widget code inside the Container and provided the height and width properties. This is useful in controlling the custom widget size.

For the older project (created before we rolled out the null safety feature), if you get any error related to null safety like below:

6. Compile code

When you are done adding the code, you can compile it to ensure there are no errors. To do so, click Compile Code button. If everything is ok, you'll see the No Errors! button; otherwise, you'll see the Has Errors button (click on it to see errors; also, see how to fix errors using ChatGPT).

Once compiled, you can click Save button.

Compilation of a custom widget might take around 2-3 minutes.

Tip: Use this link to open the final version of our project in this example. This can be helpful in finding errors if your widget won't compile.

7. Use custom widget on page

The newly created custom widget will be available inside the Components tab.

To use a custom widget on your page.

  1. Select a page on which you would like to add a custom widget.

  2. Under Custom Code Widgets, identify your custom widget and add it to your page.

  3. Now select Custom Widget > move to the Properties Panel > Custom Widget Properties > set the appropriate values for the parameters.

  4. To change the height and width as added here, keep the Enforce Width and Heigh property enabled. This helps you in control the custom widget size from here.

Adding parameters to custom widget

Using parameters, you can pass the customization value into the widget. For example, changing its style and color or any other customization option that it supports.

  • For adding parameters, you must modify your custom widget code as well.

  • Before you add a new parameter, ensure your custom widget supports it. For example, if your custom widget doesn't allow changing color, you shouldn't add it. Otherwise, it won't have any effect.

Here's an example of how you can add more parameters to your custom widget:

  1. Click on the Custom Function from the Navigation Menu (left side of your screen).

  2. Select Custom Functions from the Navigation Menu (left side of your screen) > Custom Widgets tab > your custom widget.

  3. Click on the + Add Parameter and define the new parameter.

  4. Now, click on the [</>] icon to view the boilerplate code. This will open a new popup window.

    1. Copy the code for the new parameter. i.e., this.parametername and final datatype parametername.

    2. Click Cancel to exit the popup.

  5. Paste the code for the new parameter.

  6. Replace the hard-coded parameter values of the custom widget with the widget.parametername. For example, color: Colors.black-> color: widget.customColor.

  7. Click Compile and test the custom widget with a new parameter added.

  8. Save the progress.

  • Whenever you add a new parameter, make sure you compile the Custom Widget.

  • The name of the parameter on the right side must match the name in the code.

Adding callback action

A callback action is an action that is passed as a parameter to a custom widget and is triggered at some point in the future when a certain event occurs.

A callback action can be used to communicate back to the page which contains the custom widget. For example, when a button or icon (within the custom widget) is pressed, a callback action can be triggered to perform some action, update the state of the application, or simply refresh the page UI.

We don't support sending data back to the page (that contains the custom widget) yet, but you can utilize the App State variable to save the data processed/emitted by the custom widget and use it on your page. See how to do it in the example below.

Let's see an example of a number picker custom widget that allows you to select a number from the specified range and display the selected number on a page. Here's how it looks:

Here are the steps to build such an example:

1. Add action as a parameter

Adding a parameter of type Action helps you trigger any supported action from within the custom widget.

First, ensure you have all prerequisites for dependency, create a custom widget and then add a parameter of Type Action.

For this example, we'll add an action to refresh the page (which contains this widget) to reflect the selected number on a page.

2. Modify code

Before you proceed, make sure you add the dependency and basic code for the custom widget.

Here are steps you can take to modify your code:

2.1 Optional: create a new variable

If your custom widget depends on input from a page and uses it to update the state of a custom widget, you must create a new variable at the custom widget level and initialize it with the value passed via the parameter. Otherwise, you will get an error like the one shown below:

In this example, to show the default selected value when the custom widget is loaded, the value is passed from a page to a custom widget via the parameter called currentValue. Also, it is used to update the selection when a user changes the value. Because it is marked as final (we can't update it), we need to create a new variable and assign it with the currentValue parameter.

We can do this inside the initState method to properly initialize the currentValue variable when the widget is first created.

Now, in the custom widget code, use this new variable to provide a value and update the new value when a user changes the selection.

This example uses the value property to show the currently selected value and onChanged property that receives the notification when the selection changes. Let's use the new variable (i.e., _selectedValue) in both properties. Here's how it looks after updation.

2.2 Update selection in App State variable

When you receive a callback (aka notification) from the custom widget regarding the change in value, you can use the App State variable to capture the new value.

To do so:

  1. First, make sure you create an App State variable.

  1. In custom widget code (where you get the callback e.g., onChange, onNewValue, onDateChange, etc.), assign the new value to App State variable like this:

    FFAppState().currentNumberPickerValue = _selectedValue;

2.3 Trigger the action

After updating the value, you can trigger the action that was added as a parameter. Here's how you do it:

 widget.refreshPageUI();

Compile and Save the progress.

Tip: Use this link to open the final version of this example. This can be helpful in finding errors if your widget won't compile.

3. Adding callback action

At this point, we are done with modifying the custom widget. Now add and select the custom widget on your page, move to the properties panel, and add an action to refresh the UI (using update App State action).

The trick here is that you don't need to set any variable; just add an action and keep the Update Type to Rebuild Current Page. So when this action is triggered, it will refresh the UI, and the App State variable value (which was set inside the custom widget code) will be reflected in a Text widget on a page.

Here's how you do it:

Adding multiple actions as callbacks

By adding multiple actions as callbacks, you can increase the functionality of your custom widget. Each callback action can be responsible for a specific task, making your widget more versatile and useful.

Let's say you're adding a customizable dialog widget that allows users to approve or delete comments on their posts. The dialog widget has two buttons. One to approve the comment and another to delete the comment.

To implement this functionality, you can add two action callbacks to the dialog widget:

  1. A "positiveAction" callback is triggered when the user clicks the "Approve" button.

  2. A "negativeAction" callback is triggered when the user clicks the "Delete" button.

By adding these two action callbacks to the dialog widget, you can provide a more user-friendly experience for approving and deleting comments.

Here's how it looks:

Here's how you do it:

  1. First, ensure you have all prerequisites for dependency, create a custom widget and then add multiple parameters of Type Action.

  2. Now, modify the custom widget code as per your requirement and trigger actions from the appropriate places in your code.

  1. Now, open the page, add the custom widget, and pass the actions you want to perform when they are triggered from inside the custom widget.

Tip: Use this link to open the final version of this example. This can be helpful in finding errors if your widget won't compile.

Accessing app state variable

If you are looking to pass an app state variable to your custom widget, check out here.

Additional Resources

Detailed step-by-step instructions on how to create a QR code-generating widget.


Last Updated Date: September 1, 2023

Last updated