= Role Category Keys
:description: Asciidoctor PDF provides built-in roles and the ability to define custom roles that can be applied to paragraphs and inline phrases.
:navtitle: Role
:source-language: yaml

[#role]
== role

The keys in the `role` category define custom roles for formatting.
The name of the role is the subkey.
The keys under the role are the theming properties.
The role name may contain a hyphen, but *a role name cannot contain an underscore*.

IMPORTANT: Custom roles only apply to paragraphs and inline phrases (text).
In the table below, the *p* indicates keys which are recognized when the role is applied to a paragraph and the *i* indicates keys which are recognized when the role is applied to an inline phrase.

[cols="3,4,5a"]
|===
|Key |Value Type |Example

|background-color +
(i)
|xref:color.adoc[Color] +
(default: _not set_)
|[source]
role:
  high-contrast:
    background-color: #121212

|border-color +
(i)
|xref:color.adoc[Color] +
(default: _not set_)
|[source]
role:
  found:
    border-color: #CCCCCC

|border-offset +
(i)
|xref:language.adoc#values[Number] +
(default: `0`)
|[source]
role:
  found:
    border-offset: 2

|border-radius +
(i)
|xref:measurement-units.adoc[Measurement] +
(default: _not set_)
|[source]
role:
  found:
    border-radius: 3

|border-width +
(i)
|xref:measurement-units.adoc[Measurement] +
(default: _not set_)
|[source]
role:
  found:
    border-width: 0.5

|font-color +
(i, p)
|xref:color.adoc[Color] +
(default: _inherit_)
|[source]
role:
  red:
    font-color: #FF0000

|font-family +
(i, p)
|xref:font-support.adoc[Font family name] +
(default: _inherit_)
|[source]
role:
  label:
    font-family: M+ 1mn

|font-size +
(i, p)
|xref:text.adoc#font-size[Font size] +
(default: _inherit_)
|[source]
role:
  large:
    font-size: 12

|font-style +
(i, p)
|xref:text.adoc#font-style[Font style] +
(default: _inherit_)
|[source]
role:
  heavy:
    font-style: bold

|text-align +
(p)
|xref:text.adoc#text-align[Text alignment] +
(default: _inherit_)
|[source]
role:
  declare:
    text-align: center

|text-decoration +
(i)
|xref:text.adoc#decoration[Text decoration] +
(default: `none`)
|[source]
role:
  deleted:
    text-decoration: line-through

|text-decoration-color +
(i)
|xref:color.adoc[Color] +
(default: `$role-<name>-font-color`)
|[source]
role:
  deleted:
    text-decoration-color: #FF0000

|text-decoration-width +
(i)
|xref:language.adoc#values[Number] +
(default: `$base-text-decoration-width`)
|[source]
role:
  underline:
    text-decoration-width: 0.5

|text-transform +
(i, p)
|xref:text.adoc#transform[Text transform] +
(default: _inherit_)
|[source]
role:
  heavy:
    text-transform: uppercase
|===

To learn more about defining a custom role, see xref:custom-role.adoc[].

[#built-in]
== Built-in roles

Asciidoctor PDF provides several predefined roles.
You can xref:ROOT:roles.adoc[use these roles] when using a built-in theme or a custom theme that extends a built-in theme.
You can also redefine the built-in roles in your theme configuration file.

// tag::user-formatting[]
lead:: The `lead` role defines the font properties for a lead paragraph or phrase.
The built-in themes configure this role to set the font size to the `$base-font-size-large` value.
This role is automatically assigned to the first paragraph of the preamble if a role is not already declared.
big:: The `big` role maps the font size to the `$base-font-size-large` value.
small:: The `small` role maps the font size to the `$base-font-size-small` value.
underline:: The `underline` role adds the underline decoration.
line-through:: The `line-through` role adds the strikethrough decoration.
subtitle:: The `subtitle` role is used to configure the font properties of the subtitle of a section title.
// end::user-formatting[]
// tag::para-roles[]
text-justify:: Aligns the text to the left margin with justification.
text-left:: Aligns the text to the left margin (without justification).
text-right:: Aligns the text to the right margin.
text-center:: Aligns the text to the center of the page.
// end::para-roles[]
unresolved:: The `unresolved` role is applied automatically to the text of an unresolved footnote reference.
(Only recognizes the `font-color` theme key).
noborder:: Only applies to block images.
If this role is present on the block image, the border will not be drawn even if configured on the `image` category in the theme.
This role cannot be redefined.

NOTE: The color roles (e.g., `blue`), which you may be familiar with from the HTML converter, are not mapped by default.
You'll need to define these color roles as xref:custom-role.adoc[custom roles] in your theme if you'd like to make use of them when converting to PDF.