Creating Stateful Modals in AngularJS with Angular UI Router

There are a number of ways to approach implementing modals in an AngularJS application, including the popular angular-dialog-service and the official Angular-UI Bootstrap modal. In this article I’ll share how I like to handle modals in Angular, using another Angular-UI service, the ui-router.

Thinking in States

The core idea behind this approach is that modals are in fact unique states of your application. Consider an e-commerce site. When you click the “Add to cart” button, a modal pops up asking you to log in. You enter your details and click “Continue”, which show’s you another modal with the details of your cart.

You’ve just traversed a number of states that just happened to be in modals. If we think of modals as states, then it makes sense to use a state management tool to go to and from different modal states.

Getting Started with the UI Router

Let’s keep it simple to start with. First, we’ll install the ui-router and add it to our Angular app.

1. Create a Simple HTML Page

We’ll start by creating an index.html file with the following contents:

<!doctype html>
<html ng-app="modalApp">
  <head>
    <title>Modals with Angular and Ui-Router</title>
    <link rel="stylesheet" href="css/app.css" />
    <script type="text/javascript" src="js/jquery.min.js"></script>
    <script type="text/javascript" src="js/angular.min.js"></script>
    <script type="text/javascript" src="js/angular-ui-router.min.js"></script>
    <script type="text/javascript" src="js/app.js"></script>
  </head>
  <body>
  </body>
</html>

jQuery has been included for some DOM work later on.

In addition to including the latest version of Angular itself, I’ve included the Angular UI Router, a CSS file (currently empty), and of course our app’s main JavaScript file. Let’s take a look at that next.

2. Create Your Angular App

The app.js file is incredibly simple at this point. We just create a module for our modalApp and then add the ui.router as a dependency:

angular.module("modalApp", ["ui.router"])

3. Fleshing Out the Interface

Before we can open a modal, we need a UI for the user to interact with. In this instance I’ve kept things simple with an “Add to cart button” in index.html:

<!doctype html>
<html ng-app="modalApp">
  <head>
    <title>Modals with Angular and Ui-Router</title>
    <link rel="stylesheet" href="css/app.css" />
    <script type="text/javascript" src="js/jquery.min.js"></script>
    <script type="text/javascript" src="js/angular.min.js"></script>
    <script type="text/javascript" src="js/angular-ui-router.min.js"></script>
    <script type="text/javascript" src="js/app.js"></script>
  </head>
  <body>
    <h3>Pusheen Hoodie</h3>
    <p>Now you too can look like Pusheen!</p>
    <button>Add to cart</button>
  </body>
</html>

4. Configure the Initial States

We’re going to be defining a number of states for each of our modals, but there’s a bit of setup we need to do first. Since it’s likely that we’ll want to share behavior between our different modals, let’s create a parent Modal state that our individual modals can then inherit from. The following code belongs in js/app.js:

angular.module("modalApp", ["ui.router"]).config(function($stateProvider) {
  $stateProvider.state("Modal", {
    views:{
      "modal": {
        templateUrl: "modal.html"
      }
    },
    abstract: true
  });
});

We have defined a state called “Modal”. It’s an abstract state meaning it can’t be directly transitioned to. It only serves as a parent to it’s child states to offer shared functionality. We also defined a template for a named view (also called modal). Naming your views is a good idea to avoid the wrong states loading into the wrong places in your app, especially if you’re using the ui-router for other states in your app.

The ui-router uses a directive called ui-view to determine where a state’s template should be loaded. We’ll include a ui-view directive on our index.html page:

<!doctype html>
<html ng-app="modalApp">
  <head>
    <title>Modals with Angular and Ui-Router</title>
    <link rel="stylesheet" href="css/app.css" />
    <script type="text/javascript" src="js/jquery.min.js"></script>
    <script type="text/javascript" src="js/angular.min.js"></script>
    <script type="text/javascript" src="js/angular-ui-router.min.js"></script>
    <script type="text/javascript" src="js/app.js"></script>
  </head>
  <body>
    <h3>Pusheen Hoodie</h3>
    <p>Now you too can look like Pusheen!</p>
    <button>Add to cart</button>

    <div ui-view="modal" autoscroll="false"></div>
  </body>
</html>

Since we named our view “modal”, we need to pass this to the directive as well. The autoscroll="false" setting prevents the ui-router from attempting to scroll the modal into view.

Let’s go about defining our first actual modal. We’ll create a popup that asks the user if they’re sure they want to add the product to their cart.

angular.module("modalApp", ["ui.router"]).config(function($stateProvider) {
  $stateProvider.state("Modal", {
    views:{
      "modal": {
        templateUrl: "modal.html"
      }
    },
    abstract: true
  });

  $stateProvider.state("Modal.confirmAddToCart", {
    views:{
      "modal": {
        templateUrl: "modals/confirm.html"
      }
    }
  });
});

Simple as that. We defined a new confirmAddToCart state as a child of Modal using the router’s dot notation. We also specified a template for our new modal.

Since the confirmAddToCart modal is a child of the Modal state, the ui-router will look for a ui-view directive in the Modal state’s template (modal.html) in order to render the confirm template. Let’s create both of these templates next.

The Modal state’s template is responsible for creating a transparent backdrop to cover the app, as well as a holder of sorts, where we’ll load our different child state’s templates.

<div class="Modal-backdrop"></div>
<div class="Modal-holder" ui-view="modal" autoscroll="false"></div>

Here’s a few basic styles that belong in css/app.css:

*
{
  box-sizing: border-box;
}

.Modal-backdrop
{
 position: fixed;
 top: 0px;
 left: 0px;
 height:100%;
 width:100%;
 background: #000;
 z-index: 1;
 opacity: 0.5;
}

.Modal-holder
{
  position: fixed;
  top: 0px;
  left: 0px;
  height:100%;
  width:100%;
  background: transparent;
  z-index: 2;
  padding: 30px 15px;
}

8. Create the Confirm Modal’s Template

This template is for the actual modal box with the confirm message in it. The following code goes in modals/confirm.html:

<div class="Modal-box">
  Are you sure you want to do that?
  <button>Yes</button>
</div>

Styling for the Modal-box:

.Modal-box
{
  margin: 0 auto;
  width: 100%;
  background: #fff;
  padding: 15px;
  border-radius: 4px;
  box-shadow: 1px 2px 5px rgba(0,0,0,0.3);
  position: relative;
}

@media screen and (min-width: 992px)
{
  .Modal-box
  {
    width: 50%;
    padding: 30px;
  }
}

9. Wire It All Up

Now that we have a parent modal state with a child state, and both of their templates, all that’s left to do is actually trigger the modal. The ui-router provides us with a directive called ui-sref which behaves similarly to the href attribute of an anchor tag. It will essentially link us to the state name we provide.

<!doctype html>
<html ng-app="modalApp">
  <head>
    <title>Modals with Angular and Ui-Router</title>
    <link rel="stylesheet" href="css/app.css" />
    <script type="text/javascript" src="js/jquery.min.js"></script>
    <script type="text/javascript" src="js/angular.min.js"></script>
    <script type="text/javascript" src="js/angular-ui-router.min.js"></script>
    <script type="text/javascript" src="js/app.js"></script>
  </head>
  <body>
    <h3>Pusheen Hoodie</h3>
    <p>Now you too can look like Pusheen!</p>
    <button ui-sref="Modal.confirmAddToCart">Add to cart</button>

    <div ui-view="modal" autoscroll="false"></div>
  </body>
</html>

Now, when we click the button, the router will navigate us to the Modal.confirmAddToCart state. The Modal state’s template will load first into the ui-view directive in index.html. This will show our backdrop and prepare the holder. Then, the white confirmation dialog will load into the ui-view directive in the parent modal template and hey presto! We have a modal!

The first thing you might notice, is that you can’t close the modal. Let’s fix that.

AngularUI Router provides us with onEnter and onExit callbacks that fire off when entering and leaving states. We’ll use the onEnter callback to set up some event listeners that will close the modal. But that begs the question: How do we actually close it? Closing the state based modal is simply a matter of transitioning to a different state. Whether that be the state the modal originated from or just some default, no-op state is up to you. For now, let’s create an empty Default state and use that to navigate away from our modal state.

angular.module("modalApp", ["ui.router"]).config(function($stateProvider) {
  $stateProvider.state("Default", {});

  $stateProvider.state("Modal", {
    views:{
      "modal": {
        templateUrl: "modal.html"
      }
    },
    onEnter: ["$state", function($state) {
      $(document).on("keyup", function(e) {
        if(e.keyCode == 27) {
          $(document).off("keyup");
          $state.go("Default");
        }
      });

      $(document).on("click", ".Modal-backdrop, .Modal-holder", function() {
        $state.go("Default");
      });

      $(document).on("click", ".Modal-box, .Modal-box *", function(e) {
        e.stopPropagation();
      });
    }],
    abstract: true
  });

  $stateProvider.state("Modal.confirmAddToCart", {
    views: {
      "modal": {
        templateUrl: "modals/confirm.html"
      }
    }
  });
});

The events we set up are fairly trivial. We just need to listen for the esc key, as well as for any clicks on the backdrop. Furthermore an e.stopPropagation() call has been added to prevent clicks inside the modal bubbling up to the backdrop and closing the modal unintentionally.

Go ahead and test it out.

Now that we can open and close the modal, we can begin to see the true strength of this approach. Not only is it clean and meaningful to have each modal represented by a state, but it allows us to traverse states within those modals.

We started off asking users to confirm their purchase. Now, let’s show them a success message in another modal. Again, we’ll just define a new state and its associated template:

angular.module("modalApp", ["ui.router"]).config(function($stateProvider) {
  $stateProvider.state("Default", {});

  $stateProvider.state("Modal", {
    ...
  }

  $stateProvider.state("Modal.confirmAddToCart", {
    views:{
      "modal": {
        templateUrl: "modals/confirm.html"
      }
    }
  });

  $stateProvider.state("Modal.successfullyAdded", {
    views:{
      "modal": {
        templateUrl: "modals/success.html"
      }
    }
  });
});

<div class="Modal-box">
  Added! Yay, now you too can look like Pusheen :)
  <button ui-sref="Default">Awesome!</button>
</div>

Now, all that’s left to do is to link the “Yes” button from the confirm modal, to the new success state. While we’re there, we can add a “No” button that links to our default state to close the modal.

<div class="Modal-box">
  Are you sure you want to do that?
  <button ui-sref="Modal.successfullyAdded">Yes</button>
  <button ui-sref="Default">No</button>
</div>

And there you have it! State based, navigable modals. I find that treating modals as states is a sure fire way to ensuring your users have a smooth experience when using modals in your application.

Since the modals are just states, you get all the other added benefits of the Angular UI Router, including:

Nested states – You can render other states within your modals
Callbacks – Fire off events when your modal opens or closes to inform other parts of your application
State params and dependency injection – Pass data to your modals with state params or dependency inject data services into your state’s controllers
URLs – States are URI routable meaning you could have a URL that links to a modal, pretty nifty

All of the code from this article is available on GitHub. I’d love to hear your feedback on this approach to modals in AngularJS so please, leave a comment :)

Frequently Asked Questions (FAQs) about Creating Stateful Modals with AngularJS and Angular UI Router

How do I create a stateful modal using AngularJS and Angular UI Router?

Creating a stateful modal using AngularJS and Angular UI Router involves several steps. First, you need to install AngularJS and Angular UI Router in your project. Then, you need to define a state for your modal in your app’s configuration. This state should include a template or templateUrl that points to the HTML content of your modal. You can then use the $state service to open your modal. Remember to inject $state into your controller to use it.

What are the benefits of using stateful modals in AngularJS?

Stateful modals in AngularJS offer several benefits. They allow you to maintain the state of your application, even when a modal is open. This means that you can navigate away from a modal and return to it without losing any data. Stateful modals also allow you to use the browser’s back button to close the modal, which can improve the user experience.

How can I use the $state service to open a modal?

The $state service in AngularJS allows you to transition between states in your application. To open a modal, you can use the $state.go method, passing in the name of the state that represents your modal. This will cause AngularJS to load the template associated with that state and display it as a modal.

How do I define a state for a modal in AngularJS?

Defining a state for a modal in AngularJS involves using the $stateProvider service in your app’s configuration. You can use the $stateProvider.state method to define a new state, passing in an object that specifies the state’s name, url, and template or templateUrl. The template or templateUrl should point to the HTML content of your modal.

Can I use Angular UI Router to create modals without maintaining state?

Yes, you can use Angular UI Router to create modals without maintaining state. However, this would mean that you lose the benefits of stateful modals, such as the ability to navigate away from a modal and return to it without losing any data. If you don’t need these features, you can simply use the $uibModal service to create modals.

How do I close a stateful modal in AngularJS?

To close a stateful modal in AngularJS, you can use the $state service to transition to a different state. This will cause AngularJS to unload the modal’s template and close the modal. You can also use the browser’s back button to close the modal if you have configured your modal to be stateful.

Can I use stateful modals with other versions of Angular?

Yes, you can use stateful modals with other versions of Angular. However, the process for creating stateful modals may vary depending on the version of Angular you are using. Always refer to the official Angular documentation for the most accurate and up-to-date information.

How do I handle errors when creating stateful modals in AngularJS?

When creating stateful modals in AngularJS, errors can be handled using the $stateChangeError event. This event is broadcasted on the root scope when an error occurs during a state transition. You can listen for this event in your controller and take appropriate action when it occurs.

Can I pass data to a stateful modal in AngularJS?

Yes, you can pass data to a stateful modal in AngularJS. This can be done using the params option when defining your modal’s state. The params option allows you to specify any parameters that should be passed to the modal’s controller when the modal is opened.

How do I test a stateful modal in AngularJS?

Testing a stateful modal in AngularJS can be done using Angular’s built-in testing tools. You can use the $state service to transition to your modal’s state and then check that the modal’s template has been loaded correctly. You can also test any functionality in your modal’s controller using Angular’s $controller service.