Theming options for API docs

Note

Redoc doesn't load any fonts by default, so you have to take care of it yourself.

To customize the style of your API documentation, specify the theming options in the features.openapi.theme object. This applies regardless of your preferred docs deployment method.

If you're using our Workflows (cloud hosted service) or our CLI for on-premise deployments, we recommend specifying the theming options in the Redocly configuration file.

Expand the theme schema below to show all available theming options. Options supported in Redoc Community Edition (the free and open source version of the product) are marked to distinguish them from options supported only in the premium version of the product.

features.openapi.theme schema

object

Breakpoints for switching three/two and mobile view layouts. Supported in Redoc CE.

large
string

Supported in Redoc CE.

medium
string

Supported in Redoc CE.

small
string

Supported in Redoc CE.

object

Controls the appearance of code snippets used in OpenAPI definition fields that support Markdown formatting, and in external Markdown files referenced in the API definition.

backgroundColor
string

Sets the background color for code snippets.

borderRadius
string

Sets the border radius for the code snippet block.

maxHeight
string

Sets the max height value for code block.

object

Controls the appearance of code highlighted with Prism.js. Supported tokens: comment, prolog, doctype, cdata, punctuation, property, tag, number, constant, symbol, boolean, selector, string, char, builtin, inserted, operator, entity, url, variable, atrule, keyword, regex, important, bold, italic, entity, deleted`.

color
string

Sets the text color for highlighted code matching the specified token.

fontFamily
string

Sets the font family for highlighted code matching the specified token.

fontSize
string

Sets the font size for highlighted code matching the specified token.

lineHeight
string

Sets the line height for highlighted code matching the specified token.

object

Supported in Redoc CE.

object

Sets the accent color used throughout the Reference docs interface to highlight active items (for example, the selected tab in the code samples panel).

main
string
Default: "#59C3FF"
light
string
Default: "#b3dcf3"
dark
string
Default: "#033B73"
contrastText
string
Default: "#ffffff"
object
dark
string
Default: "#616E7C"
light
string
Default: "#E4E7EB"
object
contrastText
string
Default: "#ffffff"
dark
string
light
string
main
string
Default: "#FF6161"
object
basic
string
Default: "#707070"
delete
string
Default: "#C83637"
get
string
Default: "#3A9601"
head
string
Default: "#A23DAD"
link
string
Default: "#07818F"
options
string
Default: "#947014"
patch
string
Default: "#bf581d"
post
string
Default: "#0065FB"
put
string
Default: "#93527B"
object
contrastText
string
dark
string
light
string
main
string
Default: "#0065FB"
object
object
backgroundColor
string
Default: "#FFF4F4"
borderColor
string
Default: "#FFC9C9"
color
string
tabTextColor
string
Default: null
object
backgroundColor
string
borderColor
string
color
string
tabTextColor
string
object
backgroundColor
string
borderColor
string
color
string
tabTextColor
string
object
backgroundColor
string
Default: "#F6FFF4"
borderColor
string
Default: "#B1E996"
color
string
tabTextColor
string
object
main
string
Default: "#E4E7EB"
light
string
Default: "#F5F7FA"
contrastText
string
Default: "#3E4C59"
object
contrastText
string
dark
string
light
string
main
string
object
primary
string
Default: "#1F2933"
secondary
string
Default: "#7b8794"
light
string
Default: "#F5F7FA"
tonalOffset
number
Default: 0.2

Sets the default tonal offset used in color computations. Supported in Redoc CE.

object
contrastText
string
dark
string
light
string
main
string
object
object

Controls the appearance of buttons in Reference docs.

borderRadius
string
hoverStyle
string
fontWeight
string
boxShadow
string
hoverBoxShadow
string
fontFamily
string
object
object
object
object
object
object

Controls the appearance of HTTP method badges (GET, POST, PUT...) in Reference docs.

borderRadius
string
Default: "16px"

Sets the border radius for all HTTP badges. Can be used to achieve the rounded corner effect on the badge.

color
string

Specifies the color of the text in all HTTP badges. If not configured, the colors.text.light value is used as the default.

fontFamily
string

Specifies the font family to use for the text in all HTTP badges. If not configured, the typography.code.fontFamily value is used as the default.

fontWeight˙
string

Specifies the font weight of the text in all HTTP badges. If not configured, the typography.fontWeightBold value is used as the default.

object
object

Controls the font size and line height for medium-sized HTTP badges. These values apply only to badges in middle and right panels of the API documentation.

object

Controls the font size and line height for small-sized HTTP badges. These values apply only to badges in the navigation sidebar of the API documentation.

object

Controls the appearance of buttons for layout switching in the top right corner of the Reference docs page.

top
string
Default: "20px"

Specifies the offset between the top of the page and Hide Samples/Change View buttons.

width
string
Default: "36px"

Specifies width of Hide Samples/Change View buttons

height
string
Default: "36px"

Specifies height of Hide Samples/Change View buttons

object

Controls the appearance of the operation+path section and request/response samples section in the right panel, and the schema section in the middle panel.

borderRadius
string
Default: "8px"
backgroundColor
string
Default: "#fff"
object
color
string
fontFamily
string
fontSize
string
fontWeight
string
lineHeight
string
transform
string

Specifies how to capitalize a heading's text.

object
color
string
fontFamily
string
fontSize
string
fontWeight
string
lineHeight
string
transform
string

Specifies how to capitalize a heading's text.

iconColor
string
object

Controls the appearance of the Try it button in the right panel that opens the console.

fullWidth
boolean
Default: false

Specifies whether the width of the Try it button will be set to its maximum supported value.

object

Controls the appearance of the Send button in the Try it console that sends the request.

fullWidth
boolean
Default: false

Specifies whether the width of the Send button will be set to its maximum supported value.

object

Controls layout properties for Reference docs.

showDarkRightPanel
boolean
Default: false

When set to true, changes the background color of the entire right panel to dark-mode color. By default, this option is disabled, and only the API console and code samples elements have a dark background, while the rest of the right panel matches the background color of the middle panel.

object

Controls the maximum width of the middle panel in stacked view (right panel contents inside the middle panel) depending on current screen size (small, medium, large). You can specify screen size values as percentages or pixels.

object
small
string
Default: "90%"
medium
string
Default: "75%"
large
string
Default: "1200px"
object

Controls the maximum width of the middle panel in three-panel view depending on current screen size (small, medium, large). You can specify screen size values as percentages or pixels.

object

Specifies the maximum width of the whole middle panel area.

small
string
Default: "100%"
medium
string
Default: "100%"
large
string
Default: "1800px"
object

Specifies the maximum width of the content in the middle panel area.

small
string
medium
string
large
string
object

Supported in Redoc CE.

gutter
string
Default: "2px"

Logo image padding. Supported in Redoc CE.

maxHeight
string

Supported in Redoc CE.

maxWidth
string

Supported in Redoc CE.

object

Supported in Redoc CE.

backgroundColor
string
Default: "#f2f2f2"

Controls the background color of the floating action button (FAB), which is visible on the reference documentation page in the mobile view.

color
string
Default: "#0065FB"

Controls the SVG icon color for the floating action button (FAB), which is visible on the reference documentation page in the mobile view.

object

Allows overriding default styling of specific elements with custom CSS.

object

To override the default styling for the Download button, provide custom CSS as the value. The Download button must be enabled in the Reference docs settings.

custom
string

Custom CSS for styling the Download button.

object

To override the default styling for the Next button (navigates to the next section of the API documentation), provide custom CSS as the value. Pagination and the Next button must be enabled in the Reference docs settings.

custom
string

Custom CSS for styling the Next Section button.

object

Supported in Redoc CE.

backgroundColor
string
Default: "#1F2933"

Supported in Redoc CE.

panelBackgroundColor
string
Default: "#52606D"
panelControlsBackgroundColor
string
Default: "#323F4B"
showAtBreakpoint
string
Default: "medium"
textColor
string
Default: "#ffffff"

Supported in Redoc CE.

width
string
Default: "50%"

Supported in Redoc CE.

object
breakFieldNames
boolean
caretColor
string
caretSize
string
object
backgroundColor
string
border
string
defaultDetailsWidth
string
Default: "70%"
object
backgroundColor
string
border
string
labelsTextSize
string
Default: "0.9em"
linesColor
string
nestedBackground
string
nestedAlternativeBackground
string
nestingSpacing
string
Default: "1em"
requireLabelColor
string
Default: "#FF0000"
typeNameColor
string
typeTitleColor
string
object
borderRadius
string
Default: "4px"

Controls the border radius value to create the rounded corners effect on elements across whole Reference docs. Setting this value to 0 overrides all border radius values in the theme.

object

Some of the sidebar theming options are supported in Redoc CE.

activeBgColor
string
Default: "#E4E7EB"

Sets the background color for the active (selected) item in the sidebar.

activeTextColor
string

Supported in Redoc CE.

backgroundColor
string
Default: "#fff"

Supported in Redoc CE.

borderRadius
string
Default: "4px"
breakPath
boolean
caretColor
string
caretSize
string
fontFamily
string
fontSize
string
object

Supported in Redoc CE.

subItemsColor
string
Default: "#3E4C59"

Specifies the text color of subitems in a sidebar group.

textTransform
string

Supported in Redoc CE.

fontWeight
string
object

Supported in Redoc CE.

textTransform
string

Supported in Redoc CE.

rightLineColor
string
Default: "#CBD2D9"

Sets the color of the vertical divider line between the sidebar and the middle panel.

separatorLabelColor
string
showAtBreakpoint
string
Default: "small"
object
unit
number
Default: 8
paddingHorizontal
string
paddingVertical
string
offsetTop
string
offsetLeft
string
offsetNesting
string
textColor
string

Supported in Redoc CE.

width
string
Default: "285px"

Supported in Redoc CE.

object

Controls the spacing of items and sections in the generated API documentation. The numbers set here are used to calculate the final positioning values. Supported in Redoc CE.

sectionHorizontal
number

Horizontal section padding. Calculated as spacing.unit * 8. Supported in Redoc CE.

sectionVertical
number

Vertical section padding. Calculated as spacing.unit * 8. Supported in Redoc CE.

unit
number

Main spacing unit used in auto-computed theme values. Supported in Redoc CE.

object

Supported in Redoc CE.

object

Controls inline code styling. Supported in Redoc CE.

backgroundColor
string
Default: "rgba(38, 50, 56, 0.05)"

Supported in Redoc CE.

color
string
Default: "#e53935"

Supported in Redoc CE.

fontFamily
string
Default: "Source Code Pro, monospace"

Supported in Redoc CE.

fontSize
string
Default: "13px"

Supported in Redoc CE.

fontWeight
string

Supported in Redoc CE.

lineHeight
string

Supported in Redoc CE.

wordBreak
string

Specifies how to break words in code blocks to make the content more responsive at different screen sizes (breakpoints).

Enum: "break-all" "break-word" "keep-all" "normal" "revert" "unset" "inherit" "initial"
wrap
boolean
Default: false

Specifies whether to break words in inline code elements to prevent content overflow. Supported in Redoc CE.

object
fontFamily
string
Default: "Source Code Pro, sans-serif"
fontSize
string
Default: "13px"
fontWeight
string
Default: "400"
lineHeight
string
fontFamily
string

Supported in Redoc CE.

fontSize
string
Default: "14px"

Supported in Redoc CE.

fontWeightBold
string
Default: "600"

Supported in Redoc CE.

fontWeightLight
string
Default: "300"

Supported in Redoc CE.

fontWeightRegular
string
Default: "400"

Supported in Redoc CE.

object
color
string
fontFamily
string
fontSize
string
fontWeight
string
lineHeight
string
transform
string

Specifies how to capitalize a heading's text.

object
color
string
fontFamily
string
fontSize
string
fontWeight
string
lineHeight
string
transform
string

Specifies how to capitalize a heading's text.

object
color
string
fontFamily
string
fontSize
string
fontWeight
string
lineHeight
string
transform
string

Specifies how to capitalize a heading's text.

object

Supported in Redoc CE.

fontFamily
string
Default: "Source Sans Pro, sans-serif"

Supported in Redoc CE.

fontWeight
string
Default: "700"

Supported in Redoc CE.

lineHeight
string
Default: "1.6em"

Supported in Redoc CE.

lineHeight
string
Default: "1.5em"

Supported in Redoc CE.

object

Supported in Redoc CE.

color
string

Supported in Redoc CE.

hover
string

Supported in Redoc CE.

textDecoration
string
Default: "auto"

Supported in Redoc CE.

hoverTextDecoration
string
Default: "auto"

Supported in Redoc CE.

visited
string

Supported in Redoc CE.

optimizeSpeed
boolean
Default: true

Supported in Redoc CE.

object
color
string
fontFamily
string
fontSize
string
fontWeight
string
lineHeight
string
transform
string

Specifies how to capitalize a heading's text.

smoothing
string
Default: "antialiased"

Controls font optimization that applies when viewing documentation in browsers with support for font smoothing. Supported in Redoc CE.

Enum: "auto" "none" "antialiased" "subpixel-antialiased" "grayscale"

Example theme

Add your custom theme settings to the features.openapi > theme object in the Redocly configuration file.

When using Redocly CLI, you can pass one or more theming options to the CLI tool with the --options parameter. To make it more practical, you can also save your custom theme as a JSON file and pass it to the CLI tool with the same parameter, like in the following example:

reference-docs build example-openapi.yaml --options=theme.json

Example theme.json file

Copy
Copied
{
  "theme": {
    "breakpoints": {
      "small": "10rem",
      "medium": "40rem",
      "large": "85rem"
    },
    "colors": {
      "primary": {
        "main": "rgba(246, 20, 63, 1)",
        "light": "rgba(246, 20, 63, 0.42)"
      },
      "success": {
        "main": "rgba(28, 184, 65, 1)",
        "light": "#81ec9a",
        "dark": "#083312",
        "contrastText": "#000"
      },
      "text": {
        "primary": "rgba(0, 0, 0, 1)",
        "secondary": "#4d4d4d"
      },
      "http": {
        "get": "rgba(0, 200, 219, 1)",
        "post": "rgba(28, 184, 65, 1)",
        "put": "rgba(255, 187, 0, 1)",
        "delete": "rgba(254, 39, 35, 1)"
      }
    },
    "typography": {
      "fontSize": "16px",
      "fontFamily": "Fira Sans, Roboto, sans-serif",
      "optimizeSpeed": true,
      "smoothing": "antialiased",
      "headings": {
        "fontWeight": "bold",
        "lineHeight": "1em"
      },
      "code": {
        "fontWeight": "600",
        "color": "rgba(92, 62, 189, 1)",
        "wrap": true
      },
      "links": {
        "color": "rgba(246, 20, 63, 1)",
        "visited": "rgba(246, 20, 63, 1)",
        "hover": "#fa768f"
      }
    },
    "sidebar": {
      "width": "300px",
      "textColor": "#000000"
    },
    "rightPanel": {
      "backgroundColor": "rgba(55, 53, 71, 1)",
      "textColor": "#ffffff"
    }
  }
}