Guides for working with Pixate Freestyle

Note: This implementation (and the related documentation) of Pixate Freestyle is preliminary and subject to change. For the original Pixate style reference, see Pixate style-reference.

Available guides


Steroids utilises Pixate to allow developers to style native iOS elements like any other part of their app. For Steroids apps this means control over the styling of native UI elements like the navigation and tab bars, which would be out of reach for regular CSS styling. Pixate Freestyle CSS is "full CSS" with the exception of not supporting pseudo-elements and a few minor differences which we will go over.

Application Structure

Let's begin with an overview of a Freestyle-based application. At application start-up, Freestyle looks for your application's CSS in a file named default.css, which is located in www/native-styles/. The default.css file can include other CSS files by using @import.

CSS rules are applied using a control's element name, class, id or other attributes. The element name is determined by the type of control. For example, the native navigation bar has the nav-bar element name. The Control descriptions lists the element name for each control.

class and id are determined by the styleClass and styleId properties respectively of individual control instances. By convention, styleClass is shared by all controls with a related function or layout in the application, perhaps members within the same view. styleId is expected to be unique across the application. These conventions are not enforced by the Freestyle, and setting of these properties is not required unless you want to select controls using these properties. These properties are typically set by the application developer.

CSS Media Queries

@media rules use CSS media queries to conditionally apply styles for different devices, screen resolutions, and orientations.

The following media expressions are allowed:

*   orientation: portrait | landscape
*   device: ipad | iphone | ipad-mini
*   device-width: <number> | <length>
*   min-device-width: <number> | <length>
*   max-device-width: <number> | <length>
*   device-height: <number> | <length>
*   min-device-height: <number> | <length>
*   max-device-height: <number> | <length>
*   scale: <number>
*   min-scale: <number>
*   max-scale: <number>

Media types (e.g., 'print') are not supported. Use 'and' to join multiple media expressions.

Below are example uses of the @media rule:

/* Rule sets apply only when the device is in portrait orientation */
@media (orientation:portrait) { }

/* Rule sets apply if the device's height (ignores orientation)
 is at least 1000 pixels and if the device has a retina display. */
@media (min-device-height:1000px) and (scale:2) { }

/* Apply rules to iPad Mini in landscape mode. */
@media (orientation:landscape) and (device:ipad-mini) { }

The iPad-Mini form factor is not supported in the simulator so it appears as an iPad in the simulator.

Finally, note that CSS does not support @import statements within @media rules.

Importing Style Sheets

The @import rule allows importing style rules from other style sheets. The @import statement must be followed by a URL that is relative to the /www folder.

@import url("style.css")
@import "style.css"

Note that the @import does not support the CSS3 @media rule for specifying conditional style sheets or alternative style sheets. Also @import is not supported within an @media statement. This restriction is silently enforced.

Media Assets

Media assets are accessed using the url function and must be contained within the Application's bundle or on the device filesystem. Resources in the application bundle can be accessed using bundle://, files on the device are acessessed using file://, and resources in the device documents folder can be accessed using documents://. If no protocol is specified, the resources will be searched for first in the documents folder then in the resource bundle.

/* search in documents folder and application bundle for resource */
background-image:    url(star.svg);

/* search for resource in a subfolder of Documents */
background-image:    url(documents://myResources/star.svg);

/* search for resource in a subfolder of  */
background-image:    url(file://images/star.svg);

/* search for resource in application bundle */
background-image:    url(bundle://star.svg);

Runtime Configuration

The Freestyle engine allows you to customize some of its behavior, using CSS and a custom configuration element. You can access the configuration element by referencing it with the freestyle-config selector. For example:

freestyle-config {
  parse-error-destination: console;
  cache-styles: auto;
  image-cache-count: 100;

In the example above, adding this snippet to default.css would send parse errors to the console, set up default cache settings, and bump the image cache count to 100 images.

Configuration Properties

  • parse-error-destination: none or console. Setting it to console displays any parse errors in your project's CSS in the XCode console during debugging. The default value is none.

  • cache-styles: auto, none, all, minimize-styling, and cache-images. Used to toggle caching and to set limits for those caches. This property accepts a comma-delimited list of the preceding values. Values are processed in order and are accumulated. auto is the same as minimize-styling, cache-images. minimize-styling tries to prevent styling of an element if its styling has not changed. cache-images caches images generated during styling to avoid unnecessary rendering on future stylings and to generally increase styling speeds. The default (and recommended) value is auto.

  • image-cache-count: number. Determines how many images we be retained in the image cache, assuming it has been turned on with cache-styles. If this is set to 0, then there will be no upper limit to how many images live in the cache. The default value is 10.

  • image-cache-size: number. Determines how many bytes of image data are retained in the image cache. A value of 0 indicates that there is no upper limit to how many bytes can live in the cache. Note that image-cache-count will still be honored. The default value is 0.

Navigation Bar

Styling the native navigation bar is very simple. Let's take a look at a few different methods for styling the navigation bar elements.

The Back Indicator

Let's begin with taking a standard navbar with the system back button and customizing the back button. For the default system button, there are just a few things you can customize. We'll start with changing the default back indicator icon. We'll use a file that's included in your project files by default. Normally, you can reference any icon in your project files by inserting an url relative to the www/ folder.

navigation-bar back-indicator {
    background-image: url(icons/telescope.png);
    background-size: 18;

Note that we used the back-indicator child for navigation-bar. iOS requires that a back-indicator-mask be also set, but we set it automatically to use the same image as the indicator. If you want to set an explicit indicator mask, then also specify it as follows:

navigation-bar back-indicator-mask { ... }

Button color

To set the tint color of the default system buttons, just use the color property of the navigation-bar, for example:

navigation-bar {
    color: #FF3B30;

Button font

You can also set the font and color of just the system back button using something like this:

navigation-bar back-bar-button {
    color: #34AADC;
    font-family : "Avenir";
    font-size: 16;

Custom Buttons

If you want complete control over your buttons, you can create a new button:

var myButton = new steroids.buttons.NavigationBarButton();

Then, give it a class:

myButton.styleClass = "awesome-nav-button";

Now, go crazy with the markup:

.awesome-nav-button {
    shape               : arrow-button-left;
    content-edge-inset  : 0 0 0 6;
    border-radius       : 5px;
    font-family         : "American Typewriter";
    font-weight         : bold;
    font-size           : 12px;
    font-weight         : normal;
    color               : #ffffff;
    background-color    : #008ed4;

Finally, to display your button, you need to attach it to your navigation bar, like this:

var myButton = new steroids.buttons.NavigationBarButton();
myButton.styleClass = "awesome-nav-button";

  buttons: {
    left: [myButton]

We can also set the icon of our custom buttons via the icon child, for example:

navigation-bar { color: white; }

.my-awesome-button icon {
    background-image: url(profile.svg);
    background-size: 20;

Note that you cannot have a label and an icon on a button at the same time, so you should not set both. Note that we set the navigation bar's color to white so the icon renders in white.

Navigation Bar Title and Fonts

Finally, let's review how you might set the navigation bar's title font and color as well as the title text of individual navigation items.

For the title of each item in your navigation bar, you can set all of its font properties and color via the navigation bar itself, but when it comes to changing item specific properties, like the text itself, you'll want to access the navigation-item.

Let's set the font and color of our title:

navigation-bar title {
    color: #4CD964;
    font-family : "Avenir";
    font-size: 26;