Documentation Archive

Developer

Apple TV Markup Language Reference

On This Page

TVML Styles

You can customize TVML elements using the TVML styles provided by Apple. Usage of these styles is optional, and you can create great client-server apps without ever changing the default look of an element. (The examples in the template chapters use the defaults.)

background-color

Use the background-color style to customize the background of an element. background-color can be used with the following elements:

Table 30-1 shows the valid values for the background-color style.

Table 30-1background-color values

Value

Description

rgb(r,g,b)

The background color of an element, where r,g,b are the red, green, and blue color components, and have a value range from 0-255.

rgba(r,g,b,a)

The background color of an element, where r,g,b are the red, green, and blue color components, and have a value range from 0-255. a is the alpha applied to the color ranging from 0.0-1.0.

transparent

The background color of the element is transparent.

border-radius

Use the border-radius style to apply rounded corners to elements. border-radius can be used with the following elements:

Table 30-2 shows the valid values for the border-radius style.

Table 30-2border-radius values

Value

Description

4-tuple

The corners of the image are cropped to the specified radius.

circle

The image is cropped to fit inside of circle.

large

The corners of the image are cropped to create rounded corners with a large radius.

medium

The corners of the image are cropped to create rounded corners with a medium radius.

small

The corners of the image are cropped to create rounded corners with a small radius.

There are four ways to designate the border-radius style as a 4-tuple.

  • border-radius: X1 X2 X3 X4—Where X1 is applied to the top-left corner, X2 is applied to the top-right corner, X3 is applied to the bottom-right corner, and X4 is applied to the bottom-left corner.

  • border-radius: X1 X2 X3—Where X1 is applied to the top-left corner, X2 is applied to the top-right and bottom-left corners, and X3 is applied to the bottom-right corner.

  • border-radius: X1 X2—Where X1 is applied to the top-left and bottom-right corners, and X2 is applied to the top-right and bottom-left corners.

  • border-radius: X1—Where X1 is applied to each corner.

color

Use the color style to change the color of an element. color can be used with the following elements:

Table 30-3 shows the valid values for the color style.

Table 30-3color values

Value

Description

rgb(r,g,b)

The color of an element ,where r,g,b are the red, green, and blue color components, and have a value range from 0-255.

rgba(r,g,b,a)

The color of an element, where r,g,b are the red, green, and blue color components, and have a value range from 0-255. a is the alpha applied to the color ranging from 0.0-1.0.

transparent

The color of the element is transparent.

font-family

Use the font-family style to specify the font for an element. font-family can be used with the following elements:

Only use font families defined in tvOS. Table 30-4 shows the valid values for the font-family style.

Table 30-4font-family values

Value

Description

font family name

The tvOS name for a font family. For example, style="font-family:'Times New Roman'.

font name

The tvOS name for a specific font in a font family. For example, style="font-family:'Times New RomanPS-BoldMT'.

font-size

Use the font-size style to change the size of a displayed font. font-size can be used with the following elements:

Table 30-5 shows the valid values for the font-size style.

Table 30-5font-size values

Value

Description

integer

The font size is set to the specified point value.

font-weight

Use the font-weight style to change how thick or thin a font looks. font-weight can be used with the following elements:

Table 30-6 shows the valid values for the font-weight style.

Table 30-6font-weight values

Value

Description

black

The weight of the font is thicker than heavy.

bold

The weight of the font is thicker than the default.

heavy

The weight of the font is thicker than bold.

light

The weight of the font is slightly thinner than the default.

medium

The weight of the font is slightly thicker than default.

regular

The weight of the font is not changed. This is the default value.

semibold

The weight of the font is slightly thicker than medium.

thin

The weight of the font is thinner than the default.

ultralight

The weight of the font is thinner and lighter in color than the default.

height

Use the height style to change height of an element. height can be used with the following elements:

Table 30-7 shows the valid values for the height style.

Table 30-7height values

Value

Description

float

The height of the element, in points. For example, height:200 sets the height of the element to 200 points.

margin

Use the margin style to change the amount of space around an element. margin can be used with the following elements:

Table 30-8 shows the valid values for the margin style.

Table 30-8margin values

Value

Description

integer

The margin of the element is set to the specified point value.

max-height

Use the max-height style to set the maximum height for an element. max-height can be used with the following elements:

Table 30-9 shows the valid values for the max-height style.

Table 30-9max-height values

Value

Description

float

The maximum height for an element, in points. For example, max-height:200 restricts the height of the element to 200 points, even if the contents of the element are larger than 200 points.

max-width

Use the max-width style to set the maximum width for an element.

Table 30-10 shows the valid values for the max-width style.

Table 30-10max-width values

Value

Description

float

The maximum width for an element, in points. For example, max-width:200 restricts the width of the element to 200 points, even if the contents of the element are larger than 200 points.

min-height

Use the min-height style to set the minimum height for an element. min-height can used with the following elements:

Table 30-11 shows the valid values for the min-height style.

Table 30-11min-height values

Value

Description

float

The minimum height for an element, in points. For example, min-height:200 forces the height of an element to be at least 200 points tall, even if the contents of the element are smaller than 200 points.

min-width

Use the min-width style to set the minimum width for an element. min-width can be used with the following elements:

Table 30-12 shows the valid values for the min-width style.

Table 30-12min-width values

Value

Description

float

The minimum height for an element, in points. For example, min-width:200 forces the width of an element to be at least 200 points wide, even if the contents of the element are smaller than 200 points.

padding

Use the padding style to change the amount of space between the border and the contents of an element. padding can be used with the following elements:

Table 30-13 shows the valid values for the padding style.

Table 30-13padding values

Value

Description

integer

The padding of the element is set to the specified point value.

text-align

Use the text-align style to horizontally align the text in an element. text-align can be used with the following elements:

Table 30-14 shows the valid values for the text-align style.

Table 30-14text-align values

Value

Definition

center

The text is aligned with the center of the element.

justified

Each line of text has the same length. This is accomplished by adjusting the spacing between characters.

left

The text is aligned along the left edge of the element.

natural

The text is aligned based on the natural reading style for the system default language. For example, if the system language is set to Arabic, then the text is aligned along the right edge of the element and reads right-to-left.

right

The text is aligned along the right edge of the element.

text-shadow

Use the text-shadow style to add a shadow effect to your text element. text-shadow can be used with the following elements:

shows the valid values for the text-shadow style.

Table 30-15text-shadow values

Values

Description

(Integer, Integer, Integer, rgb(r,g,b)

Creates a shadow effect for the text. The value consists of four parts:

  • Integer (Required): An integer value indicating the horizontal start position for the shadow.

  • Integer (Required): An integer value indicating the vertical start position for the shadow.

  • Integer (Optional): An integer value indicating the amount of blur applied to the shadow.

  • rgb(r,g,b) (Optional): The color of the shadow, where r,g,b are the red, green, and blue color components, and have a value range from 0-255.

tv-align

Use the tv-align style to horizontally align an element inside of its parent element. tv-align can be used on the children of the following elements:

Table 30-16 shows the valid values for the tv-align style.

Table 30-16tv-align values

Value

Definition

center

The element is aligned in the center of its parent element.

leading

The element is aligned along the leading edge of its parent element.

left

The element is aligned along the left edge of its parent element.

right

The element is aligned along the right edge of its parent element.

trailing

The element is aligned along the trailing edge of its parent element.

tv-content-align

Use the tv-content-align style to vertically align an element inside of its parent element. tv-content-align can be used with the following elements:

Table 30-17 shows the valid values for the tv-content-align style.

Table 30-17tv-content-align values

Value

Definition

bottom

The element is aligned with the bottom of its parent element.

center

The element is aligned in the center of its parent element.

top

The element is aligned along the top of its parent element.

tv-focus-margin

Use the tv-focus-margin style to indicate the amount of space required for a custom cell elements when it comes into focus. tv-focus-margin can only be used with custom cell elements created in your binary.

Table 30-18 shows the valid values for the tv-focus-margin style.

Table 30-18tv-focus-margin values

Value

Definition

integer

The amount of space, in points, around each side of the cell indicating the room needed for a focusable, custom cell element.

integer, integer

The amount of space, in points, around each side of the cell indicating the room needed for a focusable, custom cell element. The first integer controls the top and bottom. The second integer controls the left and right sides.

integer, integer, integer

The amount of space, in points, around each side of the cell indicating the room needed for a focusable, custom cell element. The first integer controls the top. The second integer controls the left and right sides. The third integer controls the bottom.

integer, integer, integer, integer

The amount of space, in points, around each side of the cell indicating the room needed for a focusable, custom cell element. The first integer controls the top. The second integer controls the right side. The third integer controls the bottom. The fourth integer controls the left side.

tv-highlight-color

Use the tv-highlight-color style to change the color of an element when it is highlighted. tv-highlight-color can be used with the following elements:

Table 30-19 shows the valid values for the tv-highlight-color style.

Table 30-19tv-highlight-color values

Value

Description

rgb(r,g,b)

The highlight color of an element ,where r,g,b are the red, green, and blue color components, and have a value range from 0-255.

rgba(r,g,b,a)

The highlight color of an element, where r,g,b are the red, green, and blue color components, and have a value range from 0-255. a is the alpha applied to the color ranging from 0.0-1.0.

transparent

The highlight color of the element is transparent.

tv-img-treatment

Use the tv-img-treatment style to change how an image is displayed. tv-img-treatment can be used with the following elements:

Table 30-20 shows the valid values for the tv-img-treatment style.

Table 30-20tv-img-treatment values

Value

Description

circle

The image is cropped to fit inside of circle.

corner-large

The corners of the image are cropped to create rounded corners with a large radius.

corner-medium

The corners of the image are cropped to create rounded corners with a medium radius.

corner-small

The corners of the image are cropped to create rounded corners with a small radius.

tv-interitem-spacing

Use the tv-interitem-spacing style to set the spacing between the child elements of an element. tv-interitem-spacing can be used with the following elements:

Table 30-21 shows the valid values for the tv-interitem-spacing style.

Table 30-21tv-interitem-spacing values

Value

Description

float

The amount of space, in points, between items inside of an element.

tv-line-spacing

Use the tv-line-spacing style to set the amount of space between lines of text. tv-line-spacing can be used with the following elements:

Table 30-22 shows the valid values for the tv-line-spacing style.

Table 30-22tv-line-spacing values

Value

Description

float

The amount of space, in points, between lines of text.

tv-minimum-scale-factor

Use the tv-minimum-scale-factor style to set a minimum size for text if it does not fit in the available space. tv-minimum-scale-factor can be used with the following elements:

Table 30-23 shows the valid values for the tv-minimum-scale-factor style.

Table 30-23tv-minimum-scale-factor values

Value

Description

float

The maximum amount, as a percentage, that a font can be minimized in order to fit in the available space. Valid values are from 0.0 to 1.0.

tv-placeholder

Use the tv-placeholder style to set a default image for an img or monogram element. tv-placeholder can be used with the following elements:

Table 30-24 shows the valid values for the tv-placeholder style.

Table 30-24tv-placeholder values

Value

Description

monogram

The placeholder image is appropriate for a monogram. The light themed placeholder image is image: ../Art/PreloadAsset-Monogram_2x.png.

movie

The placeholder image is appropriate for a movie. The light themed placeholder image is image: ../Art/PreloadAsset-Movie_2x.png.

music

The placeholder image is appropriate for music. The light themed placeholder image is image: ../Art/PreloadAsset-Music_2x.png.

podcast

The placeholder image is appropriate for a podcast. The light themed placeholder image is image: ../Art/PreloadAsset-Podcast_2x.png.

tv

The placeholder image is appropriate for TV. The light themed placeholder image is image: ../Art/PreloadAsset-TV_2x.png.

tv-position

Use the tv-position style to specify where an element is positioned in regard to its parent element. tv-position can be used on the children of the following elements:

Table 30-25 shows the valid values for the tv-position style.

Table 30-25tv-position values

Value

Description

bottom

The element is positioned at the bottom of the containing element.

bottom-leading

The element is positioned in the bottom corner and leading edge of the containing element.

bottom-left

The element is positioned in the bottom-left corner of the containing element.

bottom-right

The element is positioned in the bottom-right corner of the containing element.

bottom-trailing

The element is positioned in the bottom corner and trailing edge of the containing element.

center

The element is centered horizontally and vertically in the containing element.

footer

The element is positioned in the footer section of the containing element.

header

The element is positioned in the header section of the containing element.

leading

The element is positioned along the leading edge of the containing element.

left

The element is positioned to the left of the containing element.

right

The element is positioned to the right of the containing element.

top

The element is positioned at the top of the containing element.

top-leading

The element is positioned in the top corner and leading edge of the containing element.

top-left

The element is positioned in the top-left corner of the containing element.

top-right

The element is positioned in the top-right corner of the containing element.

top-trailing

The element is positioned in the top corner and trailing edge of the containing element.

trailing

The element is positioned along the trailing edge of the containing element.

tv-rating-style

Use the tv-rating-style style to designate what image is used for rating a product. tv-rating-style can be used with the following elements:

Table 30-26 shows the valid values for the tv-rating-style style.

Table 30-26tv-rating-style values

Value

Description

circle

The rating image is a circle.

star-hollow-l

The rating image is a large, hollow star-shaped image.

star-l

The rating image is a large star-shaped image.

star-m

The rating image is a medium star-shaped image.

star-s

The rating image is a small star-shaped image.

tv-text-highlight-style

Use the tv-text-highlight-style style to specify how a label reacts when it comes into focus. tv-text-highlight-style can be used with the following elements:

Table 30-27 shows the valid values for the tv-labels-state style.

Table 30-27tv-text-highlight-style values

Value

Description

marquee-and-show-on-highlight

The text element associated with the lockup element is only shown when the item is in focus. The text will scroll across the screen if the text is longer than the available space.

marquee-on-highlight

The text element associated with the lockup element only shows the text that fits within the width of the element. Text longer than the available space is truncated. When the element is in focus, text longer than the available space is shown through scrolling.

show-on-highlight

The text element associated with the lockup element is only shown when the item is in focus. Text longer than the available space is truncated.

tv-text-max-lines

Use the tv-text-max-lines style to set the maximum lines of text that will appear in an element. tv-text-max-lines can be used with the following elements:

Table 30-28 shows the valid values for the tv-text-max-lines style.

Table 30-28tv-text-max-lines values

Value

Description

integer

The maximum number of lines that will be displayed in an element. For example, tv-text-max-lines: 2 will display two lines of text inside of an element.

tv-text-style

Use the tv-text-style style to set the text for an element to a predefined size and style. tv-text-style can be used with the following elements:

Table 30-29 shows the valid values for the tv-text-style style.

Table 30-29tv-text-style values

Value

Description

body

The text font and weight are set to the body style.

callout

The text font and weight are set to the callout style.

caption1

The text font and weight are set to the caption1 style.

caption2

The text font and weight are set to the caption2 style.

footnote

The text font and weight are set to the footnote style.

headline

The text font and weight are set to the headline style.

subhead

The text font and weight are set to the subhead style.

subtitle1

The text font and weight are set to the subtitle1 style.

subtitle2

The text font and weight are set to the subtitle2 style.

subtitle3

The text font and weight are set to the subtitle3 style.

title1

The text font and weight are set to the title1 style.

title2

The text font and weight are set to the title2 style.

title3

The text font and weight are set to the title3 style.

tv-tint-color

Use the tv-tint-color style to change the tint color applied to an element. tv-tint-color can be used with the following elements:

Table 30-30 shows the valid values for the tv-tint-color style.

Table 30-30tv-tint-color values

Value

Description

rgb(r,g,b)

The tint color of an element ,where r,g,b are the red, green, and blue color components, and have a value range from 0-255.

rgba(r,g,b,a)

The tint color of an element, where r,g,b are the red, green, and blue color components, and have a value range from 0-255. a is the alpha applied to the color ranging from 0.0-1.0.

transparent

The tint color of the element is transparent.

tv-transition

Use the tv-transition style to apply a transition effect to an element. tv-transition can be used with the following elements:

Table 30-31 shows the valid values for the tv-transition style.

Table 30-31tv-transition values

Value

Description

dissolve

The element stays in place and uses a dissolve effect.

magicMove

The element uses the magic move transition. When the user swipes to the left, the current image shrinks slightly, and a new image is brought on top of it from the right. When the user swipes to the right, the image slides off screen to the right. This action reveals the next image, which then grows to file the screen.

none

No transition effect is applied to the element.

push

The element is pushed onto the screen.

wipe

The element is wiped from the screen.

width

Use the width style to change width of an element. width can be used with the following elements:

Table 30-32 shows the valid values for the width style.

Table 30-32width values

Value

Description

float

The width of an element, in points. For example, width:200 sets the width of the element to 200 points.