Skip to main content

​
Text

The Text primitive is a low-level component for rendering text with extensive styling capabilities. It serves as the foundation for higher-level typography components like Heading and Paragraph.

​
Installation

yarn add @twilio-paste/text

​
Usage

import { Text } from '@twilio-paste/text';

const MyComponent = () => (
  <Text as="p" fontSize="fontSize30" color="colorText">
    Some text
  </Text>
);

​
Props

​
Text Props

The Text component accepts a wide range of styling props:

​
Required Props

PropTypeDescription
askeyof JSX.IntrinsicElementsRequired. Controls the HTML element that will be rendered in the DOM.

​
Common Props

PropTypeDefaultDescription
colorTextColor'colorText'Text color from the design tokens.
fontSizeFontSize'fontSize30'Font size from the design tokens.
lineHeightLineHeight'lineHeight30'Line height from the design tokens.
elementstring'TEXT'Used to set a custom element name for customization.
variantstring-Used to style custom variants via customization.

​
Typography Props

PropTypeDescription
fontFamilyFontFamilyFont family from design tokens (e.g., fontFamilyText, fontFamilyCode, fontFamilyDisplay).
fontSizeFontSizeFont size from design tokens.
fontStyleFontStyleCSS font-style value.
fontWeightFontWeightFont weight from design tokens.
letterSpacingLetterSpacingLetter spacing value.
lineHeightLineHeightLine height from design tokens.
textAlignTextAlignText alignment (responsive).
textDecorationTextDecorationText decoration value.
textOverflowTextOverflowText overflow behavior.
whiteSpaceWhiteSpaceWhite space handling.
fontVariantNumericstringCSS font-variant-numeric value.

​
Layout Props

PropTypeDescription
displayDisplayCSS display value (responsive).
overflowOverflowOverflow behavior.
overflowXOverflowXHorizontal overflow.
overflowYOverflowYVertical overflow.
verticalAlignVerticalAlignVertical alignment (responsive).

​
Spacing Props

PropTypeDescription
marginMarginMargin on all sides.
marginTopMarginTop margin.
marginRightMarginRight margin.
marginBottomMarginBottom margin.
marginLeftMarginLeft margin.
paddingPaddingPadding on all sides.
paddingTopPaddingTop padding.
paddingRightPaddingRight padding.
paddingBottomPaddingBottom padding.
paddingLeftPaddingLeft padding.

​
Other Props

PropTypeDescription
contentstringCSS content property.
cursorCursorPropertyCSS cursor value.
outlineOutlinePropertyCSS outline value.
transitionTransitionPropertyCSS transition value.
transitionDelayTransitionDelayPropertyCSS transition-delay value.
hrefstringSame as HTML (when using anchor tag).
relstringSame as HTML (when using anchor tag).
targetstringSame as HTML (when using anchor tag).
dateTimestringSame as HTML (when using time tag).

​
Pseudo Props

The Text component supports pseudo-class styling through special props:
  • _hover: Styles applied on hover
  • _focus: Styles applied on focus
  • _active: Styles applied when active
  • _before: Styles for ::before pseudo-element
  • _after: Styles for ::after pseudo-element
Each pseudo prop accepts the same style props as the main component.

​
Examples

​
Basic Text

<Text as="p" fontSize="fontSize30" color="colorText">
  Some text
</Text>

​
Font Families

<Text as="div">
  Default text font
</Text>

<Text as="div" fontFamily="fontFamilyCode">
  Monospace code font
</Text>

<Text as="div" fontWeight="fontWeightMedium">
  Medium weight text
</Text>

<Text as="div" fontWeight="fontWeightBold">
  Bold text
</Text>

​
Responsive Styling

<Text
  as="p"
  fontSize={['fontSize40', 'fontSize50', 'fontSize60', 'fontSize70']}
  padding={['space0', 'space10', 'space130', 'space70']}
  textAlign={['center', 'right', 'left']}
  color={['colorTextBrandHighlight', 'colorTextLink', 'colorTextSuccess', 'colorText']}
>
  Some text with responsive styling.
</Text>

​
Pseudo-Classes

<Text
  as="p"
  color="colorText"
  _hover={{ color: 'colorTextWarningStrong' }}
  _before={{ 
    content: '"Before text"', 
    position: 'absolute', 
    bottom: 0, 
    left: 0, 
    color: 'colorTextErrorStrong' 
  }}
  _after={{ 
    content: '"After text"', 
    position: 'absolute', 
    bottom: 0, 
    right: 0, 
    color: 'colorTextLinkStronger' 
  }}
>
  Hover this text
</Text>

​
Customization

The Text component supports extensive customization: 
<CustomizationProvider
  theme={currentTheme}
  elements={{
    RECTANGLE: {
      borderRadius: 'borderRadius20',
      variants: {
        primary: {
          backgroundColor: 'colorBackgroundPrimaryWeakest',
          padding: 'space30',
          textDecoration: 'underline',
        },
        secondary: {
          backgroundColor: 'colorBackgroundSuccessWeakest',
          margin: 'space30',
        },
      },
    },
  }}
>
  <Text as="div" element="RECTANGLE">Base</Text>
  <Text as="div" element="RECTANGLE" variant="primary">Primary</Text>
  <Text as="div" element="RECTANGLE" variant="secondary">Secondary</Text>
</CustomizationProvider>

​
Customizing Pseudo-Classes

<CustomizationProvider
  theme={currentTheme}
  elements={{
    SQUARE: {
      padding: 'space20',
      ':hover': {
        backgroundColor: 'colorBackgroundSuccess',
        cursor: 'pointer',
      },
      variants: {
        primary: {
          color: 'colorTextNew',
          ':hover': {
            backgroundColor: 'colorBackgroundWarning',
          },
        },
      },
    },
  }}
>
  <Text as="div" element="SQUARE" variant="primary">
    Hover me
  </Text>
</CustomizationProvider>

​
When to Use

  • Use Text when you need fine-grained control over text styling
  • Use Heading for semantic headings with predefined styles
  • Use Paragraph for body text in paragraphs
  • Use DisplayHeading for large, prominent headings
The Text component is a primitive that other typography components build upon. Use it directly when you need custom text styling that doesn’t fit the predefined components.

​
Accessibility

  • Always use the appropriate semantic HTML element via the as prop
  • Ensure sufficient color contrast between text and background
  • Use relative units (design tokens) for font sizes to respect user preferences
  • Don’t rely solely on color to convey information

Build docs developers (and LLMs) love

Get started for freeTalk to us