# Titanium.UI.Label

> A text label, with an optional background image.

- Source: https://titaniumsdk.com/docs/sdk/12.5.1/Titanium.UI.Label
- Titanium SDK version: 12.5.1
- Kind: view
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 0.8
- Extends: Titanium.UI.View
- Inheritance: Titanium.UI.View > Titanium.Proxy

| Android | iOS |
| ------- | --- |
| ![Android](./label_android.png) |  |

Use the [Titanium.UI.createLabel](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#createLabel) method or **`<Label>`** Alloy element to create a label.

## Example: Simple Alloy XML Example

Simple label in a Window

``` xml
<Alloy>
    <Window>
        <Label text="Just a label with text"/>
    </Window>
</Alloy>
```

## Example: Basic Label

Create a center-aligned label with a text shadow and specified-size font, and another
containing forced line breaks and Unicode symbols.

``` js
var win = Ti.UI.createWindow({
  backgroundColor: 'white',
  exitOnClose: true,
  fullscreen: false,
  layout: 'vertical',
  title: 'Label Demo'
});

var label1 = Ti.UI.createLabel({
  color: '#900',
  font: { fontSize:48 },
  shadowColor: '#aaa',
  shadowOffset: {x:5, y:5},
  shadowRadius: 3,
  text: 'A simple label',
  textAlign: Ti.UI.TEXT_ALIGNMENT_CENTER,
  top: 30,
  width: Ti.UI.SIZE, height: Ti.UI.SIZE
});

var label2 = Ti.UI.createLabel({
  color:'blue',
  text: 'A long label with\na few line breaks\nand Unicode (UTF8)\nsymbols such as\na white chess piece \u2655\nand the euro symbol \u20ac\nlooks like this!\n',
  textAlign: Ti.UI.TEXT_ALIGNMENT_LEFT,
  top: 30,
  width: 300, height: 200
});

win.add(label1);
win.add(label2);
win.open();
```

## Example: Alloy XML Markup

Previous example as an Alloy view.

The font and shadowOffset properties need to be defined in the TSS or controller file.
These property values are dictionaries, rather than single values,
so they cannot be included in the markup.

``` xml
<Alloy>
    <Window id="win" backgroundColor="white" exitOnClose="true" fullscreen="false" layout="vertical" title="Label Demo">

        <!-- The text property can either be defined as an attribute or as node text. -->
        <Label id="label1" color="#900" shadowColor="#aaa" text="A simple label" textAlign="Ti.UI.TEXT_ALIGNMENT_CENTER"
            top="30" width="Ti.UI.SIZE" height="Ti.UI.SIZE" />
        <Label id="label2" color="blue" textAlign="Ti.UI.TEXT_ALIGNMENT_LEFT" top="30" width="300" height="200">
            A long label with\na few line breaks\nand Unicode (UTF8)\nsymbols such as\na white chess piece \u2655\nand the euro symbol \u20ac\nlooks like this!\n
        </Label>
    </Window>
</Alloy>
```

## Properties

### attributedString

- Type: Titanium.UI.AttributedString
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 3.6.0, iPhone 3.2.0, iPad 3.2.0

Specify an attributed string for the label.

The underlying attributed string drawn by the label. If set, avoid setting common attributes
in the label, such as `color` and `font`, as unexpected behaviors may result.

Prior to Release 3.6.0, assign this property an object from the
<Titanium.UI.iOS.AttributedString> class.

Since Appcelerator CLI 4.1.0 (Alloy 1.7.0), for Alloy, you can use an `<AttributedString>`
element inside a `<Label>` element and set the text property as node text:

``` xml
<Alloy>
  <Window>
      <Label>
        <AttributedString>
            Alloy is great!
        </AttributedString>
      </Label>
  </Window>
</Alloy>
```

Then set attributes in the TSS file:

``` js
"AttributedString" : {
  attributes: [
    {
      type: Ti.UI.ATTRIBUTE_FOREGROUND_COLOR,
      value: 'red',
      range: [0, 5]
    },
    {
      type: Ti.UI.ATTRIBUTE_UNDERLINES_STYLE,
      value: Ti.UI.ATTRIBUTE_UNDERLINE_STYLE_SINGLE,
      range: [9, 5]
    }
  ]
}
```

### autoLink

- Type: Number
- Platforms: Android

Automatically convert certain text items in the label to clickable links.

Multiple autolink values can be combined with a bitwise OR. For example:

``` js
label.autoLink = Ti.UI.AUTOLINK_MAP_ADDRESSES|Ti.UI.AUTOLINK_PHONE_NUMBERS;
```

Prior to Release 3.0, this field used platform-specific constants. These are now
deprecated in favor of the `AUTOLINK` constants.

The Android-specific `LINKIFY` legacy constants are defined in [Titanium.UI.Android](https://titaniumsdk.com/docs/sdk/Titanium.UI.Android.md).

Accepts: `Titanium.UI.AUTOLINK_ALL`, `Titanium.UI.AUTOLINK_CALENDAR`, `Titanium.UI.AUTOLINK_EMAIL_ADDRESSES`, `Titanium.UI.AUTOLINK_FLIGHT_NUMBER`, `Titanium.UI.AUTOLINK_LOOKUP_SUGGESTION`, `Titanium.UI.AUTOLINK_MAP_ADDRESSES`, `Titanium.UI.AUTOLINK_MONEY`, `Titanium.UI.AUTOLINK_NONE`, `Titanium.UI.AUTOLINK_PHONE_NUMBERS`, `Titanium.UI.AUTOLINK_PHYSICAL_VALUE`, `Titanium.UI.AUTOLINK_SHIPMENT_TRACKING_NUMBER`, `Titanium.UI.AUTOLINK_URLS`

### autoSize

- Type: Boolean
- Platforms: Android
- Since: Titanium SDK 11.1.0
- Default: `false,`

Automatically scales the label into its size.

To use `autoSize` you have to set a `width` and `height` to the label and it will
automatically increase the font size to fill up the space. The actual `fontSize`
value stays the same.

### backgroundPaddingBottom

- Type: Number
- Platforms: iPhone, iPad, macOS

Number of pixels to extend the background image past the label on the bottom.

### backgroundPaddingLeft

- Type: Number
- Platforms: iPhone, iPad, macOS

Number of pixels to extend the background image past the label on the left.

### backgroundPaddingRight

- Type: Number
- Platforms: iPhone, iPad, macOS

Number of pixels to extend the background image past the label on the right.

### backgroundPaddingTop

- Type: Number
- Platforms: iPhone, iPad, macOS

Number of pixels to extend the background image past the label on the top.

### breakStrategy

- Type: Number
- Platforms: Android
- Since: Titanium SDK 12.3.0

Break strategy (control over paragraph layout). Check [Android breakStrategy](https://developer.android.com/reference/android/widget/TextView#attr_android:breakStrategy) for more infos.

Accepts: `Titanium.UI.BREAK_BALANCED`, `Titanium.UI.BREAK_HIGH_QUALITY`, `Titanium.UI.BREAK_SIMPLE`

### color

- Type: String | Titanium.UI.Color
- Platforms: Android, iPhone, iPad, macOS

Color of the label text, as a color name or hex triplet.

For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

### ellipsize

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Default: `Titanium.UI.TEXT_ELLIPSIZE_TRUNCATE_END`

Causes words in the text that are longer than the view is wide to be ellipsized instead of broken in the middle.

Accepts: `Titanium.UI.TEXT_ELLIPSIZE_TRUNCATE_CHAR_WRAP`, `Titanium.UI.TEXT_ELLIPSIZE_TRUNCATE_CLIP`, `Titanium.UI.TEXT_ELLIPSIZE_TRUNCATE_END`, `Titanium.UI.TEXT_ELLIPSIZE_TRUNCATE_MARQUEE`, `Titanium.UI.TEXT_ELLIPSIZE_TRUNCATE_MIDDLE`, `Titanium.UI.TEXT_ELLIPSIZE_TRUNCATE_NONE`, `Titanium.UI.TEXT_ELLIPSIZE_TRUNCATE_START`, `Titanium.UI.TEXT_ELLIPSIZE_TRUNCATE_WORD_WRAP`

### font

- Type: Font
- Platforms: Android, iPhone, iPad, macOS

Font to use for the label text.

### highlightedColor

- Type: String | Titanium.UI.Color
- Platforms: Android, iPhone, iPad, macOS

Color of the label when in the highlighted state, as a color name or hex triplet.

For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

Used when the label is part of a view that can be highlighted, such as a
[Titanium.UI.TableViewRow](https://titaniumsdk.com/docs/sdk/Titanium.UI.TableViewRow.md).

### html

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 0.8.0, iPhone 12.3.0, iPad 12.3.0, macOS 12.3.0

Pass a HTML-based string and it will be formatted accordingly.

Note that complex html structures like images are not supported.
Use a [Titanium.UI.WebView](https://titaniumsdk.com/docs/sdk/Titanium.UI.WebView.md) for those cases.

### hyphenationFrequency

- Type: Number
- Platforms: Android
- Since: Titanium SDK 12.3.0

Frequency of automatic hyphenation. Check [Android hyphenationFrequency](https://developer.android.com/reference/android/widget/TextView#attr_android:hyphenationFrequency) for more infos.

Accepts: `Titanium.UI.HYPHEN_FULL`, `Titanium.UI.HYPHEN_FULL_FAST`, `Titanium.UI.HYPHEN_NONE`, `Titanium.UI.HYPHEN_NORMAL`, `Titanium.UI.HYPHEN_NORMAL_FAST`

### includeFontPadding

- Type: Boolean
- Platforms: Android
- Since: Titanium SDK 3.3.0
- Default: `undefined but behaves as true`

Includes extra top and bottom padding to make room for accents that go above normal ascent and descent.

### lineCount

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 12.3.0
- Permission: read-only

Returns the amount of lines the content is acually using. Is equal or lower than `maxLines`.

### lines

- Type: Number
- Platforms: Android
- Since: Titanium SDK 4.1.0

Makes the label be exactly this many lines tall.

### lineSpacing

- Type: LabelLineSpacing
- Platforms: Android
- Since: Titanium SDK 5.4.0

Line spacing of the [text](https://titaniumsdk.com/docs/sdk/Titanium.UI.Label.md#text), as a dictionary with the properties `add` and `multiply`.

### maxLines

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 4.1.0, iPhone 6.1.0, iPad 6.1.0

Makes the label at most this many lines tall.

### minimumFontSize

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK iPhone 0.8.0, iPad 0.8.0, Android 6.1.0

Minimum font size when the font is sized based on the contents.

When set to a valid font size, this property enables single-line mode and the font
will be auto-downscaled so that its text will fit the label's width if necessary.
Will not downscale the font lower than the assigned minimum font size.

When set to less than or equal to zero, the font auto-downscaling feature will be disabled.

### shadowColor

- Type: String | Titanium.UI.Color
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.2.0

Shadow color of the [text](https://titaniumsdk.com/docs/sdk/Titanium.UI.Label.md#text), as a color name or hex triplet.

Use in conjunction with [shadowOffset](https://titaniumsdk.com/docs/sdk/Titanium.UI.Label.md#shadowOffset) and [shadowRadius](https://titaniumsdk.com/docs/sdk/Titanium.UI.Label.md#shadowRadius).
For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

### shadowOffset

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

Shadow offset of the [text](https://titaniumsdk.com/docs/sdk/Titanium.UI.Label.md#text), as a dictionary with the properties `x` and `y`.

Use in conjunction with [shadowColor](https://titaniumsdk.com/docs/sdk/Titanium.UI.Label.md#shadowColor) and [shadowRadius](https://titaniumsdk.com/docs/sdk/Titanium.UI.Label.md#shadowRadius).

### shadowRadius

- Type: Number
- Platforms: Android
- Since: Titanium SDK 3.2.0

Shadow radius of the [text](https://titaniumsdk.com/docs/sdk/Titanium.UI.Label.md#text).

Use in conjunction with [shadowColor](https://titaniumsdk.com/docs/sdk/Titanium.UI.Label.md#shadowColor) and [shadowOffset](https://titaniumsdk.com/docs/sdk/Titanium.UI.Label.md#shadowOffset).

### text

- Type: String
- Platforms: Android, iPhone, iPad, macOS

Label text.

Use the backslash and letter `n` line feed character combination, ie `\n`, to force a new
line.

Use Unicode characters, such as those included in (but not limited to) the
[Unicode List of Useful Symbols](http://en.wikibooks.org/w/index.php?title=Unicode/List_of_useful_symbols)
section of wikipedia, to insert special characters and symbols.

See the example in [label](https://titaniumsdk.com/docs/sdk/Titanium.UI.Label.md) for a demonstration.

### textAlign

- Type: String | Number
- Platforms: Android, iPhone, iPad, macOS

Text alignment.

Accepts: `Titanium.UI.TEXT_ALIGNMENT_CENTER`, `Titanium.UI.TEXT_ALIGNMENT_JUSTIFY`, `Titanium.UI.TEXT_ALIGNMENT_LEFT`, `Titanium.UI.TEXT_ALIGNMENT_RIGHT`

### textid

- Type: String
- Platforms: Android, iPhone, iPad, macOS

Key identifying a string from the locale file to use for the label text.

Only one of `text` or `textid` should be specified.

### verticalAlign

- Type: Number | String
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.0.0
- Default: `undefined`

Vertical text alignment, specified using one of the  vertical alignment constants
from [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

On iPhone and iPad the default value of the property is undefined. The behavior of the label
depends on the actual content height. If the actual content height is larger than the available
height the text is truncated at the end and the content is center aligned.

On Android, the default value of the property is undefined, and the default
behavior when the property is undefined is to center the text vertically.

Accepts: `Titanium.UI.TEXT_VERTICAL_ALIGNMENT_BOTTOM`, `Titanium.UI.TEXT_VERTICAL_ALIGNMENT_CENTER`, `Titanium.UI.TEXT_VERTICAL_ALIGNMENT_TOP`

### visibleText

- Type: String
- Platforms: Android
- Since: Titanium SDK 12.3.0
- Permission: read-only

Returns the actual text seen on the screen. If the text is ellipsized it will be different to the normal `text`.

### wordWrap

- Type: Boolean
- Platforms: Android
- Default: `true`
- DEPRECATED since 8.0.0. If you want to disable wrapping, then set [Titanium.UI.Label.maxLines](Titanium.UI.Label.maxLines) to 1 instead.

Enable or disable word wrapping in the label.

## Events

### link

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK iPhone 3.2.0, iPad 3.2.0, Android 4.0.0

Fired when user interacts with a URL in the Label.

The URL is set using the [ATTRIBUTE_LINK](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#ATTRIBUTE_LINK) property on the [attributedString](https://titaniumsdk.com/docs/sdk/Titanium.UI.Label.md#attributedString).

On Android, this event also fires if the `html` property is used instead of the `attributedString` property. This event will
also override the default behavior of openning the link in its default application.

On iOS, this is only valid on version 7 and above. In previous versions of the the Titanium SDK this event required a `longpress`
gesture to be performed. Beginning with Titanium SDK 4.0.0, only a `singletap` gesture is required to invoke this event.

Event properties:

- `url` (String): The URL that is associated with this event.
- `range` (Array): An array of two numbers [location, length] describing the character range of the text associated with this URL.
- `bubbles` (Boolean): This is false. This event does not bubble

## Inherited members

99 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.5.1/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`
- [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/12.5.1/Titanium.UI.View.md): `accessibilityDisableLongPress`, `accessibilityHidden`, `accessibilityHint`, `accessibilityLabel`, `accessibilityValue`, `anchorPoint`, `animate`, `animatedCenter`, `backgroundColor`, `backgroundDisabledColor`, `backgroundDisabledImage`, `backgroundFocusedColor`, `backgroundFocusedImage`, `backgroundGradient`, `backgroundImage`, `backgroundLeftCap`, `backgroundRepeat`, `backgroundSelectedColor`, `backgroundSelectedImage`, `backgroundTopCap`, `borderColor`, `borderRadius`, `borderWidth`, `bottom`, `center`, `clearMotionEffects`, `click`, `clipMode`, `convertPointToView`, `dblclick`, `doubletap`, `elevation`, `filterTouchesWhenObscured`, `focus`, `focusable`, `getViewById`, `height`, `hiddenBehavior`, `hide`, `horizontalMotionEffect`, `horizontalWrap`, `id`, `insertAt`, `keepScreenOn`, `keypressed`, `layout`, `left`, `longclick`, `longpress`, `opacity`, `overrideCurrentAnimation`, `pinch`, `postlayout`, `previewContext`, `pullBackgroundColor`, `rect`, `right`, `rotation`, `rotationX`, `rotationY`, `scaleX`, `scaleY`, `show`, `singletap`, `size`, `softKeyboardOnFocus`, `stopAnimation`, `swipe`, `tintColor`, `toImage`, `tooltip`, `top`, `touchEnabled`, `touchFeedback`, `touchFeedbackColor`, `touchcancel`, `touchend`, `touchmove`, `touchstart`, `transform`, `transitionName`, `translationX`, `translationY`, `translationZ`, `twofingertap`, `verticalMotionEffect`, `viewShadowColor`, `viewShadowOffset`, `viewShadowRadius`, `visible`, `width`, `zIndex`

---

- 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`.