# Font

> An abstract datatype for specifying a text font.

- Source: https://titaniumsdk.com/docs/sdk/12.8.0/Font
- Titanium SDK version: 12.8.0
- Kind: pseudo
- Platforms: Android, iPhone, iPad, macOS

Available fonts vary by platform and device. On iOS, font support depends on the OS
version. On Android, font support depends on the OS version **and** device manufacturer.

Note that to update the font used by a UI component, you must set the object's `font`
property, like this:

``` js
myLabel.font = {
    fontSize: 24,
    fontFamily: myFontName
}
```

Changing the `font` object after assigning it does not reliably affect the underlying UI
component:

``` js
// This may not work as expected
myLabel.font.fontSize = 24;
```

#### Custom Fonts

Custom TrueType (.ttf) or OpenType (.otf) fonts may be embedded in an application on iOS and
Android. (Note that you must have redistribution rights on the fonts you ship.)


In Alloy applications, custom fonts must be placed in a "fonts" folder in the platform-specific assets folder (<strong>app/assets/android/fonts</strong>, for example).
In classic Titanium applications, custom fonts must be placed in the **Resources/fonts** directory.

For an example of using custom fonts, see [Custom Fonts](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_How-tos/User_Interface_Deep_Dives/Custom_Fonts.html).

## Properties

### fontFamily

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Default: `Uses the default system font.`

Specifies the font family or specific font to use.

This can be the name of a font family (for example, "Helvetica" or "DroidSans") the base
name of the font file (for example, "Droid_sans.ttf"), or the font's PostScript name. The
value you specify also depends on the platform you are targeting.

* On Android specify the font file name without its file extension (.otf or .ttf).
For example, if you were using the "Burnstown Dam" font whose file name is
named `burnstown_dam.ttf`, then you specify `fontFamily: 'burnstown_dam'`.

* On iOS you use the font's [PostScript name](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_How-tos/User_Interface_Deep_Dives/Custom_Fonts.html#finding-a-font-s-postscript-name).
For example, the PostScript name for Burnstown Dam is "BurnstownDam-Regular so you'd specify: `fontFamily: 'BurnstownDam-Regular'`.

For an example of using a custom font, see [Custom Fonts](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_How-tos/User_Interface_Deep_Dives/Custom_Fonts.html).

Notes:

  * Available fonts differ by platform.
  * If the requested family name does not match an existing font, the default font family is used.
  * On Android, the generic names "sans-serif," "serif," and "monospace" (or "monospaced")
    are mapped to system fonts. On iOS, only "monospace" is supported.

### fontSize

- Type: Number | String
- Platforms: Android, iPhone, iPad, macOS
- Default: `15px`

Font size, in platform-dependent units.

On iOS, font sizes are always specified in typographical points
(not to be confused with the Apple "points" used for other measurements on iOS).

On Android the default font sizing is in pixels, but the size can also
include a unit specifier. Supported units and their specifiers are:

* pixels (px)
* typographical points (pt)
* density-independent pixels (dp or dip)
* millimeters (mm)
* inches (in)

For example, "16dp" specifies a size of 16 density-independent pixels.

iOS ignores any unit specifier after the size value.

On Windows, font sizing is in effective pixels, not actual physical pixels so you don't have to alter font sizes for different screens sizes or resolutions.
For more information about font sizing on Windows, see [Typography Size and Scaling](https://docs.microsoft.com/en-us/windows/uwp/design/style/typography#size-and-scaling).

### fontStyle

- Type: String
- Platforms: iPhone, iPad, macOS
- Default: `normal`

Font style. Valid values are "italic" or "normal".

### fontWeight

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Default: `normal`

Font weight. Valid values are "bold", "semibold", "normal", "thin",
"light" and "ultralight".

The "semibold", "thin", "light" and "ultralight" weights are recognized
on iOS only. "thin", "light" and "ultralight" are only available on iOS 8.2
and later.

### textStyle

- Type: String
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.2.0

The text style for the font.

Use one of the TEXT_STYLE constants from [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md) to set the font to a predefined system font.
When this property is set to a valid value, all other font properties are ignored.

Notes:
 Since SDK 9.0.0 property [Font.fontFamily](https://titaniumsdk.com/docs/sdk/Font.md#fontFamily) will not be ignored for iOS 11+.
 Custom fonts can be used with this property for dynamic font management.

Accepts: `Titanium.UI.TEXT_STYLE_BODY`, `Titanium.UI.TEXT_STYLE_CALLOUT`, `Titanium.UI.TEXT_STYLE_CAPTION1`, `Titanium.UI.TEXT_STYLE_CAPTION2`, `Titanium.UI.TEXT_STYLE_FOOTNOTE`, `Titanium.UI.TEXT_STYLE_HEADLINE`, `Titanium.UI.TEXT_STYLE_LARGE_TITLE`, `Titanium.UI.TEXT_STYLE_SUBHEADLINE`, `Titanium.UI.TEXT_STYLE_TITLE1`, `Titanium.UI.TEXT_STYLE_TITLE2`, `Titanium.UI.TEXT_STYLE_TITLE3`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.