Introduction to Flutter: Building iOS and Android Apps from a Single Codebase

Welcome to my first tutorial on Flutter. I have never written any post on cross-platform or hybrid app framework but Flutter has changed this mindset of mine. 

Previously, I have developed on React Native, Cordova, Phone Gap, Ionic and now of these really work out for me until I found Flutter along with its huge community of developers and its showcase apps.

What is Flutter?

In a nutshell, it is a multi-layered system, such that higher layers are easier to use and allow you to express a lot with little code and lower layers give you more control at the expense of having to deal with some complexity.

Flutter Framework is written entirely in Dart. Most of the engine is written in C++, with Android-specific parts written in Java, and iOS-specific parts written in Objective-C. Like React Native, Flutter also provides reactive-style views, but Flutter takes a different approach to avoid performance problems caused by the need for a JavaScript bridge by using a compiled programming language, namely Dart.

Dart is compiled “ahead of time” (AOT) into native code for multiple platforms. This allows Flutter to communicate with the platform without going through a JavaScript bridge that does a context switch. It also compiles to native code which in turn improves app startup times.

In Flutter, it is all about Widgets. Widgets are the elements that affect and control the view and interface to an app.


Flutter renders the widget tree and paints it to a platform canvas. This is nice and simple (and fast). It’s Hot-Reload capability allows real-time development experience.

You can read more about Flutter and learn about its goodness here.

Getting Started

Today, we will be building a very simple Flutter app that can be deployed on both iOS & Android called Contactly as we go through this tutorial. This is a very simple Contacts List app which will demonstrate the capabilities of Flutter. Capabilities include:

  1. TextField & Validations
  2. Button Clicks
  3. Navigations
  4. Image Rendering (Local & Online)
  5. Error Alert Dialog
  6. Scrollable List View
  7. List View Search
  8. JSON File Parsing
  9. JSON to Objects Mapping
  10. Opening External Web Browser

The final product of this app should look something like this:


It includes these features:

  1. Login via a Pin Code.
  2. Load a list of contacts from JSON.
  3. Search for a particular contact.
  4. Tap to view contact details.
  5. Tap to view contact info in an external browser.

The Flutter’s Project Structure

While you haven’t built any apps using Flutter, let me give you a quick overview of its project structure. Later when you create a Flutter project, you should see a project structure as such:

  1. android – for generating the Android app. And, in case you need to add an Android platform-specific implementation, you will implement it here.
  2. assets – for storing images, data file, etc
  3. ios – for generating the iOS app. And, in case you need to add an iOS platform-specific implementation, you will implement it here.
  4. lib – contains the main code of your application. Later, you will see we create all the code files here.
  5. test – for unit testing. However, we will not go into it in this tutorial.

I know you can’t wait to try out Flutter. Let’s dive in and set up all the required tools on your machine.

Installing Flutter

At the time of this writing, I’m using the following machine configuration and software version:

  1. Macbook Pro running macOS High Sierra
  2. Android Studio 3.2.1
  3. Xcode 10.1
  4. Flutter 1.0

I cannot guarantee that my tutorial will work for every configuration and platform, hence, I will not include configuration troubleshooting here to keep this tutorial short and objective-oriented.

First up, head over to Flutter Installation page to install Flutter. I will skip the steps here as the steps in the document is detailed enough.

Once you run flutter doctor and you got (1~4 checked), you are good to go! It’s not necessary to have Connected Devices checked.

If you have encountered any errors like below, follow the suggested solutions to fix it. For example, if your Mac has not installed with Android Studio, head over to this website to download the software. Just make sure you have the first 4 items checked before moving on.


Creating a new Flutter Project

With Flutter installed, now let’s start to build your first Flutter project.

First, fire up Android Studio and click Start a new Flutter Project.


Next, select Flutter Application and click Next.


Then fill in Project name as contactly, or anything you like. By default, it should show your default path of the Flutter path. In case it doesn’t work for you, navigate and specify your own Flutter SDK path. Optionally, you can change your project location and give a simple description. Then, click Next.


Finally, fill in a Company domain. This will be replicated in your Bundle Identifier (iOS) & Package Name (Android). For my case, I checked both Kotlin & Swift support. Then, click Finish.


Trying out an App on iOS Simulator

Once you started your Flutter Application, some boilerplate code is automatically generated with a sample app that allows you to hit a button and perform some text updates. Before we make any code changes, it is a good checkpoint to try running it on your iOS simulator.

To run the app, find the dropdown list somewhere at the top right that says <no devices>, click on it and select Open iOS Simulator.


Your last selected simulator hardware will be chosen, which is iPhone XR for my case.


Click Run, which is the green triangle, and the app should open in your simulator. You should be able to interact with the Demo app and push a few buttons!


Building the Main Page

With the demo app running successfully, we are now ready to start building our first Flutter App!

Let’s start by deleting all the code in main.dart. Yes! Press command-a to select the whole code snippet and hit Delete.

Now we will begin to write the code from scratch. First, insert the following line of code to import the material package:

This package is essential for building the UI of the app. To ensure that the app knows what to run after it finishes launching, add the main() method like this:

It’s always a good practice to organize files into separate packages and put the constants in a separate. So, let’s create the helper package and the Constants.dart file to place some of our constant values we will be using in this app.

Right-click on the lib folder and then select New > Package. Name the package helpers.


Now we have a separate folder to store our helper classes. To create a new dart file, right-click on helpers and then select New > File. Name it Constants.dart.

In Constants.dart, insert the following code:

Here we import the same material package, so we can use the Color declaration and declare an appTitle to be used app-wide.

Now head back to main.dart and add this import statement after the first import line.

Let’s start building our Main Page by adding these lines of codes:

MaterialApp is one of the convenience widgets which allows customisations like adding navigation routes, appBar etc. Setting debugShowCheckedModeBanner to false will get rid of the Red Debug label at the top right. We use our declared appTitle in our constant file here to give it a title. Then, we set the primaryColor.

All the code looks good here and you might be eager to try running it. If you really did, you will get a huge red-colored error screen!

This is because we are not yet ready to paint the canvas. Be Patient!

In most tutorials, they will guide you on building everything into main.dart. But I find that we could make it cleaner by separating each page into separate files, which you will be eventually doing so when building production-ready apps.

Meanwhile, Android Studio should indicate an error in the widget_test.dart file. Since we change the class name from MyApp to ContactlyApp, you should change the following line of code from:


Building the Login Page

Now let’s go ahead to create a new page called LoginPage.dart and place it under lib. Perform the same ritual of importing material package.

Here we will be creating a Stateless Widget since we don’t need to store any form of data. You can find more details about Stateless VS Stateful here.

Before we go into the code, let’s look at how the login screen should look like:


As you can see, the screen has the following components:

  1. An Image Logo.
  2. A TextField with Placeholder.
  3. A Login Button.

To implement the screen component, insert the following code. Just copy & paste it first, we will go through them in awhile!

And, for the Constants.dart file, please update it like this to add a number of constants that we use in the build method:

OMG! That’s a huge chunk of code! Yes, but no worries. This is the first time we are really going deep into huge piles of the Dart code. Trust me, after going through these, you will get more familiar with how Flutter works 🙂

I have broken down this large piece of code into 3 major parts so that we can digest them easier:

  1. As mentioned earlier, we will be creating a stateless widget for our LoginPage here. This is why we extend the class from StatelessWidget.
  2. Since the app has a text file for user input, we will instantiate an instance of TextEditingController here, which has a main responsibility of handling all text editing logic.
  3. For the build method, it is required to be implemented when we extend StatelessWidget to draw the UI canvas of the page. If we don’t implement the method, an error will be thrown. Furthermore, there are 4 other variables created here:
    • First, we have our logo. It is embedded in a Circular Frame by using the CircularAvatar class. It also has an appLogo image.

      If you run the app now, you will probably end up with an error saying that the image asset cannot be loaded. We know the path is given to load the Image but there are 2 missing pieces: the image itself and the path that we need to include in pubspec.yaml.

      First, you can get the logo image I use from here. Then, create a new directory called assets in the root directory, and create a sub-directory called images.


      Your image should be placed in root/assets/images.


      Then, go to pubspec.yaml and add the following code to inform the app what assets to bundle together during runtime so it can be loaded.

      Please note that you must add the configuration above to the flutter: section like this:

    • Now that we have our logo loaded properly, let’s move to the next UI item, pinCode. It is a TextFormField. We set our _pinCodeController under this TextFormField with a prefix _ which tells the compiler that this variable is private. You can read the settings as most are self-explanatory like keyboardType is phone, maxLength is 4 characters, maxLines is 1, autoFocus set to true to straightaway trigger keyboard when page is displayed. We also give the textfield a simple styling using decoration and style.
    • Next, our loginButton. We create a padding on all sides (left, right, top, bottom) using symmetric. We also use RaisedButton which automatically comes with the elevation UI effect when user interacts with it.
    • Lastly, we return the main UI structural class called Scaffold which sticks all our newly created UI components together in a ListView.

That was like an Effiel Tower of Codes! UI codes are tough 😭

Before we run the app, we also need to tell our main() to run LoginPage as the home page. So, head back to main.dart and add home: LoginPage() after theme. Your build code should look like this:

Also, you will need to import LoginPage.dart at the very beginning of the file:

Now run the app! You should see the Login Screen like this:


Cool, right? Let’s continue to build the rest of the screens.

Building Contacts List Page

Now we are warmed up a little, we can go a bit faster. We will now build the main feature of this app, the Contact List page. We will create a new file called HomePage.dart. Once you created the file, make sure you import material package:

Contacts List Page will be a Stateful widget since we need to maintain the state of our contacts data. So add these first few lines of boilerplate codes:

The first class HomePage will be called and used when navigating/presenting the page, while the private class _HomePageState will be called everytime the HomePage is called. This is also the mutable state object which we will maintain as the page get called.

Before we dive into coding again, let’s look at how our contact list screen looks like:


There are many things that we will need to do here:

  1. Allowing navigation from LoginPage to HomePage (Routing).
  2. Populating JSON data and map to ListView.
  3. Displaying the list of contacts
  4. Adding Search feature

Setting up the Routing

Let’s hook up our navigation route between LoginPage & HomePage. Head over to Constants.dart and add these tags:

Then, go to main.dart and add these just before our build function:

You will also need to import the HomePage.dart file:

The code above allows us to use tags to associate each individual page. 🙂 Finally, let’s add the routes to our build function just after home.

We can’t really test this out yet as we have not implemented the UI for our ListView. So, let’s do that first.

Populate JSON data and map to ListView

For this demo, I store all the contact data in a JSON file. You can download the sample JSON file here and create a data folder under assets. Put the records.json file into the folder. Then, update pubspec.yaml with the below asset configuration:

Now that we have prepared the JSON data, we will need to create:

  • The Record class to hold the data of each item.
  • The RecordList class to hold the list of data.
  • The RecordService class to perform the loading task.

Record Class to hold a Contact

First, let’s create a new models package under lib and create a new file named Record.dart. You can insert these lines of code into the file:

Dart provides factory constructors to support the factory pattern. The factory constructor is able to return values (objects). Here it parses the given JSON string and returns a Record instance, which represents a contact.

RecordList Class to hold the list of Contacts

In the same models package, create another file called RecordList.dart. Then, put in these lines of code:

RecordService Class to perform the loading task

Lastly, create another file named RecordService.dart in the same package and insert the following code:

Here, the loadRecords() function parses the records.json file and map it into a RecordList object, holding a list of Record objects. The keyword Future should be new to you if you are unfamiliar with Dart. To perform asynchronous operation in Dart, we use futures. Future objects (futures) represent the results of asynchronous operations.

Implementing the Home Page to list the Contacts

Now let’s use what we have implemented in our HomePage. Open the HomePage.dart and add these import statements at the very beginning:

Other than listing the contact records, the home page has a search feature that lets users search the contacts. So, first, declare the following variables in the _HomePageState class of the HomePage.dart file:

Here is the purpose of each variable:

  • We declared _filter so we can implement a listener for our searches.
  • We declared records to keep the state of our raw data, as well as filteredRecords to keep the state of searched data.
  • We use _searchText to validate our searches.
  • The _searchIcon is an Icon representation.
  • The _appBarTitle is really just a text widget which we will use widely.

Since it’s a Stateful widget, we can add some small settings when the state is initialized:

In the init state of the home page, we empty our records data and get fresh data from the JSON file. Here we don’t need to really use an Async Call, but it is to introduce its concept and how you could call it if you were to perform a data fetch from a server.

Remember that in our previous section, we return a Scaffold in the build function as the main UI structure. So, continue to insert the following code to create the UI structure:

Like most ListView pages we have seen in mobile apps, there is a navigation bar at the top. In the code above, the appBar is the navigation bar. We specify to call _buildBar(context) to generate the bar, however, we haven’t implemented the function yet. So, continue to insert the following code:

Next, it’s the body. Again, we haven’t implemented the _buildList(context) function. Continue to add these lines of code:

Here, we handle the mapping of our RecordList data into our ListVew, and also handle any searches performed.

The final piece of our ListView is the UI for each ListViewItem. Let’s create the _buildListItem function:

This is a long chunky piece of code. We can again break down and digest this in a simpler way:

  1. We used a given material design class called Card to create our Card-Like UI.
  2. In each Card, we have a ListTile. And in each ListTile we have:
    • leading: CircleAvatar Image wrapped in Hero which will allow us to do some cool animation as we navigate to the detail page later. (Record’s Photo)
    • title: It holds the name of the contact.
    • subtitle: It is wrapped in Flexible to allow growing texts.
    • trailing: It is a right arrow icon to signify interactivity.

After implementing all these, it’s almost ready to run the app and test it out! One last thing to make it work is to handle the onPressed event of the login button. Previously, we haven’t specified anything in the implementation. Now go to LoginPage.dart and change the onPressed event of the loginButton variable to the following:

That’s it! Hit the run button and try to navigate the app from the login page to the home page!


Adding Search Feature

To allow search capability, we have to enable the text editor’s listener. Insert the code below after the _buildListItem method of the HomePage.dart file:

The search process starts by tapping the search icon. When the search is triggered, we will perform some UI changes:

  1. The search icon will change to the close icon.
  2. The appTitle will become a search field.
  3. As we input search the text, the list will reload and re-render with the filtered results.

So here is the code you need. Continue to add the following method to handle the search:

In order to trigger _searchPressed(), add this method in onPressed to _buildBar:

Now you’re ready to go! Try running the app now and perform some searches! like “Mark”.


Building Contact Details Page

To finish up our Contactly App, let’s build our final Details Page to allow the app to show some more info about a contact. Let’s look at how the final screen looks like first:


It shows the contact’s profile image, its name, address, and phone number. One hidden feature not shown here is to allow user to navigate to an external web browser to view the technology’s website. So let’s get started!

In lib, create a new file called DetailsPage.dart and paste in the following code:

Here is what this above code does:

  1. We create a StatelessWidget for our DetailsPage.
  2. We create a constructor to take in a Record object (i.e. the selected contact) from HomePage.
  3. Based on the Record object, we build the UI and populate the following fields:
    • Photo
    • Name
    • Address
    • Phone Number
    • URL

You should notice a new UI component called GestureDetector. As its name suggests, this widget class is designed to detect touches. When a user touches one of the fields, the app will call URLLauncher().launchURL(record.url) to load the URL in a web browser. This URLLauncher class is not ready yet.

Let’s create a new file called URLLauncher.dart in the helpers directory.

To perform a url launch, we need to install a new package called url-launcher. To do this, we need to update our pubspec.yaml like this:


Here we add a line of configuration to load the url_launcher. After editing, run flutter packages get by hitting the Packages Get button. This is how we install extra packages to increase the capabilities of our app 🙂 Great! You have just gained another skill!

Now go back to URLLauncher.dart, insert the following code to implement the launchURL method:

Head back to the DetailsPage.dart file and import the file we just implemented:

Great! The last step is to enable the navigation from HomePage to DetailsPage. Head back to HomePage.dart and edit the onTap: event of the _buildListItem method like this:

Also, don’t forget to import the following file in HomePage.dart:

Viola! You are done with the app (not just iOS but Android too)! Run it and enjoy your great work 🙂



You have just gone through a very basic tutorial to get you started in developing on Flutter. In my own opinion, Flutter is developed based on the knowledge of popular mobile apps around where we can easily build UI components in just a few lines of codes. While its scalability is still questionable, we can see that Google and it’s community is investing a lot in this framework, and we could possibly forsee a bright future ahead for Flutter, striving past React Native.

You can download the finished project here.

New in iOS 12: Adding a Custom UI and Interactivity in Local and Push Notifications
Creating a Custom Keyboard Using iOS 8 App Extension
How to Integrate Your App with Files App in iOS 11