= 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 first subkey level.
The role name may contain a hyphen, but *a role name cannot contain an underscore*.
The keys under the role are the theming properties.

IMPORTANT: Custom roles only apply to paragraphs and inline phrases.

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

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

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

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

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

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

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

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

|font-size
|xref:language.adoc#values[Number] +
(default: _inherit_)
|[source]
role:
  large:
    font-size: 12

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

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

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

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

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

|text-transform
|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.
The lead role is automatically assigned to the first paragraph of the preamble if a role is not already declared.
The built-in themes configure this role to set the font size to the `$base-font-size-large` value.
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[]
unresolved:: The `unresolved` role is applied automatically to the text of an unresolved footnote reference.

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.