New in Alloy 1.4 – Widget Themes

If you’ve worked with Alloy, you know that Themes is one amazing feature that allows you to apply custom branding to your apps by simply changing settings in a special theme folder, in which you define styling and graphical assets. You’ve probably also worked with Widgets, which allow you to create reusable objects that combine multiple UI elements and functionality, wrapped in a easy-to-use package. However, widgets have their own styling that comes pre-baked with the Widget, so your widgets could not react to changes in themes; that is until now.

Starting with Alloy 1.4, you can now create themes that will change the look and feel of your widgets. Here’s how it works. I’ve created a simple widget that contains a label aligned to the left and a textfield aligned to the right, both in the same row.

The typical structure of your app with themes looks like this.

And your widget folder typically looks like this.

So, to add a theme to your widget, simply go to your theme folder, add a widgets folder, and inside this folder create sub-folders with the name of the widgets you’d want to provide themes for. Inside this folder add an assets and styles folder just like any other theme.

Once you’ve done this, make sure you activate your theme and add your widget to config.json

    "global": {
        "theme": "theme1"
    "env:development": {},
    "env:test": {},
    "env:production": {},
    "os:android": {},
    "os:blackberry": {},
    "os:ios": {},
    "os:mobileweb": {},
    "dependencies": {
        "com.alcoapps.labeltext": "1.0"

Now when you run your app, you’ll see you can change the actual styling of your widget from these external files. In this case, the Widget’s default look spans the whole width, while the Widget theme changes the color, adds a rounded border and centers the fields across the screen.

Important note:
Just like working with regular Widgets, it is crucial you always use the WPATH function every time you’re referencing widgets assets from controllers and style sheets, otherwise the widget will look for assets at the root level of your project.

I’ve uploaded this project to Github. When you run it, do with and without the widget theme to see the effects shown in the image above.


  1. That’s better.
    Although, what happens in the case when you want to theme a widget in different ways in various places in the app.

    For instance, maybe I’ve created a pop-up widget and I want to change the theme depending on the type of pop-up?

    Of course, all this can be accomplished through JavaScript. I’m just speaking directly to the Alloy method keeping themes and views defined in XML and TSS.

    Currently my widgets rely heavily on loading up the TSS style associated with it when defined in it’s containing XML. This isn’t really the best Alloy solution as I am defining all sorts of state variables in the TSS as well.

    In my ideal world, a widget would be defined in the XML within the tags. Each child XML element could be styled by the TSS. But effectively all that data is just passed as a collection to the Widget constructor, where the widget then decides what to do with it all.

    Thus creating something like this:

    Clearly defined in the XML view that the widget will display. And configurable there. Thus dynamic widgets can be easily created, modified, and styled per instance and easily accessible in the containing XML.

    Very much like how one might use Angular directives and the DOM.

    • Brian,

      Thanks for the comments and suggestions. There are definitely limitations of the current widget design. We plan to improve widget flexibility in the future. But for now, you can’t theme a widget differently depending on where in your app you use it. Also, while styles from app.tss will cascade down to widget components, styles set elsewhere do not.

      However, you can apply styles and settings in the tag that are made available to the widget as properties of the arguments object. To use these values, you have to modify the widget’s main controller (widget.js) to apply those settings via JavaScript.

Comments are closed.