FlutterFlow Docs
Search…
⌃K

Custom Widgets

While developing your app, you may want to use a widget that is not available in a standard FlutterFlow widgets collection. This could be a widget from pub.dev or a special widget you built yourself.
Using our custom widget editor, you can add any widget to your project. You can write/modify the widget code or upload it directly in the UI editor. It allows you to define parameters that can be used to customize the widget. You can compile and preview the custom widget right inside the code editor.
  • 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.
Custom widget example

Adding custom widget

Let's build a simple example and add a custom widget that draws the dotted border around the FlutterLogo. Here is how it looks:
Custom widget
The steps to add a custom widget are as follows:

1. Choosing a package

You can add a custom widget as a package from pub.dev, an official package repository for Dart and Flutter apps. You will find varieties of widgets for a specific requirement, and choosing the best one can be challenging. This section helps you identify the right package by examining its score.
When you search for any package in pub.dev, you will get a list of packages. You can filter out the result based on which package is more inclined towards your needs. You can do so by opening and checking each package.
Once you have a handful of packages for final selection, you can consider the following factors while choosing the final one.
  1. 1.
    WEB: It must support Web, to be able to see, modify and run it in FlutterFlow Run/Test Mode.
  2. 2.
    Likes: This shows how many developers have liked a package.
  3. 3.
    Pub Points: Tells the quality of the package (out of 130) based on code style, platform support, and maintainability
  4. 4.
    Popularity: This shows how many developers are using the package (out of 100%).
Package score

2. What you need from pub.dev

Before you add the custom widget, you need to get the following details from the package page.

2.1 Getting dependency/package

To use the custom widget code, you need to specify the dependency name and its version inside the custom widget editor. This will download that dependency for your project.
Getting dependency/package
A package might depend on other dependencies to work. So make sure to get the name and version of all the additional dependencies as well to specify in the custom widget editor.
You can check if the package container has any additional dependencies inside the Dependencies section at the bottom right side. To get its name and version, click on its name.
Additional dependency

2.2 Getting Import statement

A package import statement is usually a path where the code for the custom widget resides. While creating the custom widget, you will need the package import statement to be written at the top, inside the code editor.
Getting Import statement

3. Creating A Custom Widget In FlutterFlow

There are two ways you can create a custom widget:
Here is the link to the pub.dev Dotted Border package we will be using for this example: https://pub.dev/packages/dotted_border

3.1 Adding code directly in the FlutterFlow Widget Editor

In this approach, you copy the custom widget code from pub.dev and add it directly into the code editor.
Adding code directly in code editor comprises the following steps in order:
  1. 1.
    Define custom widget
  2. 2.
    Define widget parameters + copy code to editor
  3. 3.
    Add the dependencies
  4. 4.
    Check if there are additional dependencies
  5. 5.
    Add the import statement + widget code
  6. 6.
    Replace the hard coded parameter values
  7. 7.
    Compile your widget
  8. 8.
    Add the widget to your project
3.1.1 Define custom widget
To add code directly in the code editor:
  • Click on the Custom Function (
    ) from the Navigation Menu (left side of your screen).
  • Select the Custom Widgets tab and click on the + Create button. This will open a custom widget code editor.
    • Under Widget Name, input a name (e.g. DottedBorder).
    • In case you want to run a project, even if this widget has an error, checkmark the Exclude from compilation.
If Exclude A Widget From Compilation, we won’t check this widget for errors. This may cause errors when running your project in Run Mode or Test Mode, building APKs, publishing to web.
Define custom widget
3.1.2 Define widget parameters + copy code to editor
To pass any data to a custom widget, you can add a parameter. For example, if your custom widget has something to do with the image, you can pass the URL of the image. If it is a watch widget, you could pass the time using Timestamp DataType.
  • Under Define Parameters, you will see that width and height parameters are automatically added. This is required to size the custom widget.
  • Click on the + Add Parameter.
  • Inside the Parameter 2 section, enter the Parameter Name.
  • Select the suitable Data Type. You can find more about the Data Type in a custom widget here.
  • If your custom widget needs a list of data, such as a list of numbers to display on a chart, set the Is List to True otherwise, keep it as False.
  • If this parameter is mandatory for the widget to work, 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.
  • Click on the </> View Boilerplate Code to see the generated code with all parameters.
    • Click on the </> Copy to Editor to start modifying the generated code. This will add a boilerplate code into the editor.
Define widget parameters + copy code to the editor
3.1.3 Add the dependencies
To use the custom widget code, you need to specify the dependency name and its version inside the custom widget editor. This will download that dependency for your project.
  • Open the package and click on the copy icon(
    ) on the right side of the package name.
  • Click on + Add Dependency and paste the dependency name and its version obtained in the previous step. It should be something like packagename: ^version.
Add the dependencies
3.1.4 Check if there are additional dependencies
A package might depend on other dependencies to work. So make sure to add all the other dependencies as well.
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, and paste its name and its version as shown below:
Adding additional dependency
3.1.5 Add the import statement + widget code
A package import statement is usually a path where the code for the custom widget resides. While creating the custom widget, you will need the package import statement to be written at the top, inside the code editor.
  • Open the package page and select the installing tab; under the Import it section, you'll find the import statement. Click on the copy icon(
    ).
  • Inside the code editor on the right, add the import statement obtained in the previous step.
    • Add the code snippet of your custom widget. Most packages on pub.dev will have a sample code in Readme or Example section. You can copy the code snippet and only keep the required parameters.
Add the import statement + widget code
For the older project (created before we rolled out the null safety feature), if you get any error related to null-safety like below:
, you should enable the null safety feature on your project by navigating to Settings and Integrations ->App Details -> Null Safety.
3.1.6 Replace the hard coded parameter values
You will need to replace the hard-coded parameter values of the custom widget with the widget.parametername.
For example, strokeWidth:1 -> strokeWidth: widget.parameterName.
Replace the hard coded parameter values
3.1.7 Compile your widget
  • Click on Compile & Preview. If everything goes fine, you'll see the preview of your custom widget after a couple of minutes, and then you can play with the parameter values.
  • Click on Save.
Tip: compilation of custom widget takes around 2 minutes on FlutterFlow.
Compile your widget
3.1.7 Add Your Custom Widget To Your Project
After your widget is done compiling, it will be ready to add to your project.
To add the custom widget to your project:
  • Open the UI Builder Tab and then click the Components Icon.
  • Under Custom Code Widgets, find your widget and drag it onto the screen.
  • Under Custom Widget Properties you will be able to modify the parameters that you defined for your custom widget.
Add your custom widget to your project
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 wont compile.

3.2 Uploading code

In this approach, you add the custom widget code to your local Flutter project, customize it, make sure it works the way you want, and upload it to the custom widget code editor.
This option requires some knowledge of Flutter development.
To upload the code in the code editor:
  • Set up Flutter on your local machine.
  • Click on the Custom Function (
    ) from the Navigation Menu (left side of your screen).
  • Select the Custom Widgets tab and click on the + Create button. This will open a custom widget code editor.
    • Give the widget a name inside the Widget Name input box. Note: Make sure the name is exactly the class name in the code.
    • Click on the Upload Code button and select the custom code file from your system.
      • If you see any null-safety related errors, you can enable the null safety on your FlutterFlow project by navigating to Settings and Integrations ->App Details -> Null Safety.
      • If your file contains the material.dart import statement, remove it. This line is not required because FlutterFlow automatically imports this package.
    • Add the parameters you have used in the code by clicking on the + Add Parameter button. Enter the Parameter Name (exactly as written in the code) and choose its Data Type. Repeat this step for adding the other parameters as well.
    • Click on Compile & Preview. If everything goes fine, you'll see the preview of your custom widget after a couple of minutes, and then you can play with the parameter values.
    • Click on Save.
Uploading custom widget code
For the older project (created before we rolled out the null safety feature), if you get any error related to null-safety like below:
, you should enable the null safety feature on your project by navigating to Settings and Integrations ->App Details -> Null Safety.
The custom widget code in your sample Flutter project should look similar to the following:
//main.dart
import 'package:flutter/material.dart';
import 'dotted_border_widget_demo.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({Key? key}) : super(key: key);
// This widget is the root of your application.
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flutter Demo',
theme: ThemeData(
primarySwatch: Colors.blue,
),
home: MyHomePage(),
);
}
}
class MyHomePage extends StatefulWidget {
const MyHomePage({Key? key}) : super(key: key);
@override
State<MyHomePage> createState() => _MyHomePageState();
}
class _MyHomePageState extends State<MyHomePage> {
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: Text("Sample app"),
),
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
DottedBorderWidgetDemo(), // Custom widget class
],
),
),
// This trailing comma makes auto-formatting nicer for build methods.
);
}
}
// dotted_border_widget_demo.dart
// This is the file to be uploaded
import 'package:dotted_border/dotted_border.dart';
import 'package:flutter/material.dart';
class DottedBorderWidgetDemo extends StatefulWidget {
const DottedBorderWidgetDemo({
Key? key,
this.width = 100,
this.height = 100,
this.strokeWidth = 2,
}) : super(key: key);
final double width;
final double height;
final double strokeWidth;
@override
_DottedBorderWidgetDemo createState() => _DottedBorderWidgetDemo();
}
class _DottedBorderWidgetDemo extends State<DottedBorderWidgetDemo> {
@override
Widget build(BuildContext context) {
return DottedBorder(
color: Colors.black,
strokeWidth: widget.strokeWidth,
child: FlutterLogo(size: 148),
);
}
}
Your custom widget in preview mode looks like this:
Custom widget in preview mode

4. Using custom widget

The newly created custom widget will be available inside the Components tab.
To use a custom widget in your project.
  • Click Select Page Or Component from the Navigation Menu (left side of your screen).
  • Select a page on which you would like to add a custom widget.
  • Click UI Builder from the Navigation Menu
  • Select the Components (
    ) tab.
  • Under Custom Code Widgets, identify your custom widget and drag it onto the canvas.
  • Select Custom Widget from the widget tree or the canvas area.
  • Move to the properties panel and scroll down to the Custom Widget Properties section.
  • Set the appropriate values to the parameters.
Using custom widget

Customizing custom widget

You might want to customize the custom widget. You can do so by adding the parameters. 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. This is required to capture the value passed inside the parameter and further pass it to the custom widget.
  • 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:
  • Click on the Custom Function from the Navigation Menu (left side of your screen).
  • Select the Custom Widgets tab.
  • Identify your custom widget from the list and click on the edit icon (
    ).
  • Click on the + Add Parameter and define the new parameter.
  • Now, click on the </> View Boilerplate Code. This will open a new popup window.
    • Copy the code for the new parameter. i.e this.parametername and final datatype parametername.
    • Click Cancel to exit the popup.
  • Paste the code for the new parameter.
  • Replace the hard-coded parameter values of the custom widget with the widget.parametername. For example, color: Colors.black-> color: widget.customColor.
  • Click Compile & Preview and test the custom widget with a new parameter added.
  • Click Save.
  • Whenever you add a new parameter, make sure you compile the Custom Widget.
  • The name of the parameter on the left side must match the name in the code on the right side.
Adding new parameter
Here's how you can play with a new parameter:
Preview custom widget

Accessing local state variable

If you are looking to pass value from a local state variable to your custom widget, check out here.

Code formatting

While modifying the code in the code editor, you may find some code is not properly aligned. To format the code, click on the Format Code icon (
) on the top right side of the code editor.
Code formatting

Duplicating custom widget

To duplicate a Custom Widget:
  • Click on the Custom Function from the Navigation Menu (left side of your screen).
  • Select the Custom Widgets tab.
  • Identify the custom widget from the list and click on the edit icon (
    ).
  • Click Yes.
Duplicating custom widget

Deleting custom widget

To delete a Custom Widget:
  • Click on the Custom Function from the Navigation Menu (left side of your screen).
  • Select the Custom Widgets tab.
  • Identify the Custom Widget from the list and click on the edit icon (
    ).
  • Click Delete.
You won't be able to delete a Custom Widget if it is being used in the app. To successfully delete a Custom Widget, ensure you are not using it anywhere.
Deleting custom widget

Additional Resources