Styling

In NativeScript you style the UI similar to how you would in a web application using Cascading Style Sheets (CSS), or by changing the style property of the views in JavaScript/Typescript. For CSS styling, NativeScript supports tools such as Tailwind or SASS.

Similar to the DOM Style Object, each View instance exposes a style property, which holds all the style properties for the view. When the view is displayed, all its style properties are applied to the underlying native component.

Applying CSS styles ​

In NativeScript the CSS styles can be set on 4 different levels:

• Application-wide CSS: Applies to every application page
• Page-specific CSS: Applies to the page's UI views

• Inline CSS: Applies directly to a UI view
• Platform-specific CSS

Like with web development, if there is CSS declared on different levels—all will be applied. The inline CSS will have the highest priority and the application CSS will have the lowest priority.

Application Wide CSS ​

When the application starts, NativeScript checks if the file app.css exists. If it does, any CSS styles that it contains are loaded and used across all application pages. This file is a convenient place to store styles that will be used on multiple pages.

To change the name of the file from which the application-wide CSS is loaded, use Application.setCssFileName('style.css'). You need to do the change before the application is started, usually in the app.(js|ts) file as shown below:

You could also check the name of the application-wide CSS file by using getCssFileName() method as shown below:

import { Application } from '@nativescript/core'
const fileName = Application.getCssFileName()
console.log(`fileName ${fileName}`)

Page Specific CSS ​

When the page's XML declaration file is loaded, NativeScript looks for a CSS file with the same name (if such exists), reads any CSS styles that it finds, and automatically loads and applies them to the page. For example, a page named mypage.xml will automatically load any CSS in mypage.css. The CSS file must exist in the same folder as the XML file to be automatically applied.

If you import any custom components on your page, the CSS from those components will be applied to the page, too. As a best practice, scope the CSS of custom components so that component styles do not "leak" on to pages. /// flavor plain

<StackLayout class="my-component">
  <Label text="Custom component layout" class="label" />
</StackLayout>

/* GOOD: This will ONLY apply to the custom component */
.my-component .label {
  color: blue;
}

/* BAD: This will apply to the custom component AND potentially to the page where the component is used */
.label {
  color: blue;
}

You can also override CSS styles specified in the file by using the page's css property:

page.css = 'button { color: red }'

///

/// flavor angular

In an Angular application everything is a component, therefore, it is a very common task to add some CSS code that should only apply to one component. Adding component-specific CSS in a NativeScript-Angular app involves using a component’s styles or styleUrls property.

@Component({
    selector: 'list-test',
    styleUrls: ['style.css'],
    template: ...

// Or

@Component({
    selector: 'list-test',
    styles: ['.third { background-color: lime; }'],
    template: ...

///

Adding CSS String ​

This snippet adds a new style to the current set of styles. This is quite useful when you need to add a small CSS chunk to an element (for example, for testing purposes):

page.addCss('button {background-color: blue}')

Adding CSS File ​

This snippet adds new CSS styles to the current set. However, this method reads them from a file. It is useful for organizing styles in files and reusing them across multiple pages.

page.addCssFile(cssFileName)

Inline CSS ​

Similarly to HTML, CSS can be defined inline for a UI view in the XML markup:

<button text="inline style" style="background-color: green;"></button>

Platform-specific CSS ​

NativeScript conventions make it easy to apply platform-specific CSS, either via separate stylesheets or via in-line declarations. For an overview of NativeScript's convention-based file name rules for targeting files at specific platforms and screen sizes, refer to this article in the docs.

There are 4 primary ways to target styles at iOS or Android:

/// flavor plain

1. Platform-specific stylesheets (<file-name>.ios.css, <file-name>.android.css)
2. Platform-specific markup blocks (<ios> ... </ios>, <android> ... </android>)
3. Platform-specific attributes (<Label ios:style="..." android:style="...")
4. Platform-specific CSS rules (.ns-ios .mystyle { ... }, .ns-android .mystyle { ... })

///

/// flavor angular

1. Platform-specific stylesheets (styles.component.ios.css, styles.component.android.css)
2. Platform-specific markup blocks (<ios> ... </ios>, <android> ... </android>)
3. Platform-specific attributes (<Label ios:style="..." android:style="...")
4. Platform-specific CSS rules (:host-content(.ns-ios) .mystyle { ... }, :host-context(.ns-android) .mystyle { ... })

///

The most common and maintainable pattern for managing platform-agnostic and platform-specific styles in NativeScript is with multiple stylesheets and CSS imports.

/// flavor plain With this pattern, a page has 3 separate stylesheets: common, iOS and Android. For example, for page myPage.xml you would have 3 stylesheets:

1. myPage-common.css
2. myPage.ios.css
3. myPage.android.css

In both myPage.ios.css and myPage.android.css you then import the shared common styles from myPage-common.css:

/* Import shared style rules */
@import './myPage-common.css';

/* Add iOS/Android specific rules (if any) */
.mystyle { ... }

///

/// flavor angular With this pattern, a page (or component) has 3 separate stylesheets: common, iOS and Android. For example, for page home.component.html you would have 3 stylesheets:

1. home-common.css
2. home.component.ios.css
3. home.component.android.css

In both home.component.ios.css and home.component.android.css you then import the shared common styles from home-common.css:

/* Import shared style rules */
@import './home-common.css';

/* Add iOS/Android specific rules (if any) */
.mystyle { ... }

///

At build time, NativeScript will automatically import the common styles and choose the correct iOS or Android stylesheet depending on the target build platform.

Supported CSS Properties ​

This list of properties can be set in CSS or through the style property of each view:

Accessing NativeScript View properties with CSS ​

You can also set NativeScript component properties value that are not part of the CSS specification. For example:

StackLayout {
   orientation: horizontal;
}

This feature is limited to properties with simple types like string, number and boolean, and will set a local property value similar to component markup declaration in your template markup via XML or HTML. CSS inheritance is not supported.

NativeScript Specific CSS Properties ​

In the context of mobile development, there are a number of properties that are mobile specific (and sometimes even platform specific e.g Android or iOS). In NativeScript, these featured properties are still accessible through both the code (inline, JavaScript, and TypeScript), and as CSS properties. Below is a list of those properties:

Adding a shadow to a View on Android ​

On Android, to add a shadow to a View instance use the androidElevation property.

<StackLayout class="home-panel">
  <TextView
    class="tvElevation"
    editable="false"
    textWrap="true"
    text="TextView"
  ></TextView>
  <Label androidElevation="5" class="sampleLabel" textWrap="true" text="Label"></Label>
  <Button androidElevation="7" class="sampleButton" text="Button"></Button>
</StackLayout>

.tvElevation {
  android-elevation: 5;
}

There is also the androidDynamicElevationOffset property which allows setting a shadow when an event such as tap or touch occurs.

Example:

<StackLayout class="home-panel">
  <Button
    androidElevation="7"
    androidDynamicElevationOffset="8"
    class="sampleButton"
    text="Button"
  ></Button>
  <Button class="sampleButton2" text="Button"></Button>
</StackLayout>

.sampleButton2 {
  background-color: lightcyan;
  android-elevation: 7;
  android-dynamic-elevation-offset: 7;
}

.btn-no-elevation {
  android-elevation: 0;
}

Supported CSS Selectors ​

Currently NativeScript supports the following subset of the CSS selector syntax.

• Type selector
• Class selector
• ID selector
• Hierarchical selector
• Attribute selector
• Pseudo selector

Type Selector ​

Like CSS element selectors, type selectors in NativeScript select all views of a given type. Type selectors are case insensitive, so you can use both button and Button.

button { background-color: gray }

Class Selector ​

Class selectors select all views with a given class. The class is set using the className property of the view.

<Label className="title"></Label>

.title {
  font-size: 32;
}

import { Label } from '@nativescript/core'
const label = new Label()
label.className = 'title'

ID Selector ​

Id selectors select all views with a given id. The id is set using the id property of the view.

<Button id="login-button"></Button>

#login-button {
  background-color: blue;
}

import { Button } from '@nativescript/core'
const btn = new Button()
btn.id = 'login-button'

Hierarchical Selector (CSS Combinators) ​

A CSS selector could contain more than one simple selector, and between selectors a combinator symbol could be included.

• (space) - Descendant selector. For example, the following code will select all buttons inside the StackLayout regardless their hierarchical level.

<StackLayout>
    <WrapLayout>
        <Button id="login-button" testAttr='flower' />
    </WrapLayout>
</StackLayout>

StackLayout Button {
  background-color: blue;
}

• (>) - A direct child selector. Using the previous example, if the CSS is changed to:

StackLayout > Button {
  background-color: blue;
}

The background-color rule will not be applied. In order to apply the selector, the WrapLayout element would need to be removed so that the Button is a direct child of the StackLayout.

• (+) - An adjacent sibling selector, allows to select all elements, which are siblings of a specified element.

Direct Sibling Test by Class ​

<StackLayout class="layout-class">
  <Label text="Direct sibling test by id"></Label>
  <Button class="test-child" text="First Button"></Button>
  <Button class="test-child-2" text="Second Button"></Button>
</StackLayout>

.layout-class .test-child + .test-child-2 {
  background-color: green;
}

Direct Sibling Test by ID ​

<StackLayout class="layout-class">
  <Label text="Direct sibling test by id"></Label>
  <Button id="test-child" text="First Button"></Button>
  <Button id="test-child-2" text="Second Button"></Button>
</StackLayout>

.layout-class #test-child + #test-child-2 {
  background-color: green;
}

Direct Sibling by Type ​

<StackLayout class="direct-sibling--type">
  <Label text="Direct sibling by type"></Label>
  <Button text="Test Button"></Button>
  <Label text="Test Label"></Label>
  <Button text="Test Button"></Button>
  <Label text="Test Label"></Label>
  <Button text="Test Button"></Button>
  <Label text="Test Label"></Label>
</StackLayout>

StackLayout Button + Label {
  background-color: green;
  color: white;
}

Attribute Selector ​

<Button testAttr="flower"></Button>

button[testAttr] {
  background-color: blue;
}

This selector will select all buttons that have the attribute testAttr with some value.

Also, some more advanced scenarios are supported:

• button[testAttr='flower'] {...} - Will apply CSS on every button that has the testAttr property set exactly to the value flower.
• button[testAttr~='flower'] {...} - Selects all buttons with a testAttr property that contains a space-separated list of words, one of which is "flower".
• button[testAttr|='flower'] {...} - Selects all buttons with a testAttr property value that begins with "flower". The value has to be a whole word, either alone like btn['testAttr'] = 'flower', or followed by hyphen (-), like btn['testAttr'] = 'flower-house'.
• button[testAttr^='flower'] {...} - Selects all buttons with a testAttr property value that begins with "flower". The value does not have to be a whole word.
• button[testAttr$='flower'] {...} - Selects all buttons with a testAttr property value that ends with "flower". The value does not have to be a whole word.
• button[testAttr*='flo'] {...} - Selects all buttons with a testAttr property value that contains "flo". The value does not have to be a whole word.

Attribute selectors could be used alone or could be combined with all type of CSS selectors.

<Button id="login-button" testAttr="flower"></Button>
<Label testAttr="some value"></Label>

#login-button[testAttr='flower'] {
  background-color: blue;
}
[testAttr] {
  color: white;
}

Pseudo Selector ​

A pseudo-selector or also pseudo-class is used to define a special state of an element. Currently, NativeScript supports only :highlighted pseudo-selector.

<Button testAttr="flower"></Button>

button:highlighted {
  background-color: red;
  color: gray;
}

Root Views CSS Classes ​

To allow for flexible styling and theming, NativeScript provides the following CSS classes that can be added to the root views in the application for specific states.

• .ns-root - a class assigned to the application root view
• .ns-modal - a class assigned to the modal root view
• .ns-android, .ns-ios - classes that specify the application platform
• .ns-phone, .ns-tablet - classes that specify the device type
• .ns-portrait, .ns-landscape, .ns-unknown - classes that specify the application orientation
• .ns-light, .ns-dark - classes that specify the system appearance.

Media Queries (8.8+) ​

Media queries will allow you to apply CSS styles conditionally depending on a device's features or characteristics such as screen orientation, theme, or viewport width and height.

NativeScript supports Media Queries Level 3 specification including the following features:

• orientation
• prefers-color-scheme (Even though this one is part of Media Queries Level 5, it was added along with current implementation to make theme styling possible)
• width
• height
• device-width (same as width)
• device-height (same as height)

Viewport features like width and height support ranged values by using the min- or max- prefix.

Here are few examples of how to declare media queries in NativeScript:

@media only screen and (orientation: landscape) {
  Label {
    color: yellow;
    font-size: 24;
  }
}

@media only screen and (prefers-color-scheme: dark) {
  Label {
    background-color: #fff;
    color: #000;
  }
}

@media only screen and (max-width: 400) {
  Label {
    font-size: 10;
  }
}

@media only screen and (min-height: 800) {
  Page {
    background-color: red;
  }
}

Just like style properties, length feature values (e.g. width) can also accept DIP or device pixel (px) units.

The not operator ​

The not operator is used to negate a media query, returning true if the query would otherwise return false.

@media screen and not (orientation: portrait) {
  Label {
    color: yellow;
    font-size: 24;
  }
}

Nested Media Queries ​

@media only screen and (orientation: landscape) {
  Label {
    color: yellow;
    font-size: 24;
  }

  @media only screen and (max-width: 400) {
    Label {
      font-size: 10;
    }
  }
}

Nesting Keyframes inside Media Queries ​

Apart from CSS selectors, keyframes can also be conditional using Media Queries.

@keyframes slidein {
  from {
    background-color: yellow;
  }

  to {
    background-color: pink;
  }
}

/** This one will apply if condition is truthy **/
@media only screen and (orientation: landscape) {
  @keyframes slidein {
    from {
      background-color: red;
    }

    to {
      background-color: green;
    }
  }
}

matchMedia and conditional Navigation with Media Queries ​

Sometimes, there's the need for an application to navigate to a completely different Page based on device screen size or orientation. Right now, that's possible using NativeScript's Screen Size Qualifiers API however it's limited to plain JS/TS apps and not available to the rest of JavaScript flavors.

For various flavors, you can instead use matchMedia() providing many possibilities.

The example below demonstrates how to navigate to an alternate Page if screen width is larger than 600 DIP:

const mql = matchMedia('only screen and (max-width: 600)')

Frame.topmost().navigate({
  // Navigate to another page if screen is too big
  moduleName: mql.matches ? './pages/phone' : './pages/tablet',
})

Using listeners to track Media Query changes ​

The matchMedia() method returns a NativeScript Observable instance, giving you the chance to track Media Query changes using event listeners.

const mql = matchMedia('only screen and (orientation: portrait)')
mql.addEventListener('change', (event) => {
  console.log('Is screen orientation still portrait? ' + event.matches)
})

Supported Measurement Units ​

NativeScript supports DIPs (Device Independent Pixels), pixels (via postfix px) and percentages (partial support for width, height and margin) as measurement units.

NativeScript's recommended measurement unit is DIP. All measurable properties like width, height, margin, paddings, border-width, etc.) support DIPs. The font sizes are always measured in DIPs.

.myLabel {
  font-size: 28;
  width: 200;
  height: 30;
}

The device independent pixels (DIPs) are equal to the device screen's pixels divided by the device screen scale (density).

Below is an example of how to get a device's screen size:

import { Screen } from '@nativescript/core'

const scale = Screen.mainScreen.scale
const widthPixels = Screen.mainScreen.widthPixels
const heightPixels = Screen.mainScreen.heightPixels
const widthDIPs = Screen.mainScreen.widthDIPs // DIPs === pixels/scale (e.g. 1024 pixels / 2x scale = 512 DIPs)
const heightDIPs = Screen.mainScreen.heightDIPs

NativeScript supports percentage values for width, height and margins.The percent values are calculated based on parent element size. This means that if you place two Buttons with height='50%' in StackLayout with the default orientation='vertical',they will fill the entire StackLayout vertically. A marginLeft = '5%' will be equal to parent's width.

Using CSS variables ​

NativeScript supports CSS variables (also known as custom properties or cascading variables) for reusable values through the CSS used in the app.

CSS variables cascades from parent to child views.

Declaring variables:

/* Define --my-custom-color as a global value */
.ns-root {
  --my-custom-color: black;
}

/* In landscape mode change the value to blue */
.ns-landscape {
  --my-custom-color: blue;
}

Overriding a variable from a child-element:

/* Change --my-custom-color to green for elements below */
.ns-root .override-color {
  --my-custom-color: green;
}

Using a variable:

.using-variable {
  color: var(--my-custom-color);
}

The default value of --my-undefined-value will be black. In landscape mode it will be blue. If a parent element have the class override-color the value will be green.

Using a fallback value:

.using-variable {
  color: var(--my-undefined-value, yellow);
}

The color of --my-undefined-value will fallback to yellow, because --my-undefined-value is not defined.

Using a nested fallback value:

.using-variable {
  color: var(--my-undefined-value, var(--my-custom-color, yellow));
}

Using CSS calc() ​

NativeScript supports CSS calc() function for performing simple calculations on CSS values.

Syntax:

element {
  width: calc(100% * 1.25); /* width: 125% */
}

Used with CSS variables:

element {
    --my-variable: 10:
    width: calc(100% * var(--my-variable)); /* width: 125% */
}

Importing CSS ​

The @import CSS rule allows you to import CSS from a local file. This rule must precede all other types of rules.

@import url('~/your-style.css');