Skip to main content

Text Component in CXTMS

Introduction​

The Text Component is a fundamental element in CXTMS used for rendering various types of text content. It provides flexibility in displaying text with different styles and formats, making it essential for creating informative and well-structured user interfaces.

YAML Structure​

component: text
props:
  type: "p"
  value: "Your text here"
  label: "Optional label"
  labelPosition: "top"
  options:
    className: "custom-class"

Attribute Description​

  • component: (string) Must be set to "text" to use this component type.
  • props: (object) Contains the configuration properties for the text component.
    • type: (string) Specifies the HTML element type for the text. Options include:
      • h1, h2, h3, h4, h5, h6 for headings
      • p for paragraphs (default)
      • span for inline text
      • div for block-level text
    • value: (string or object) The content to be displayed. Supports localization and template variables.
    • label: (string or localized/template value) Optional label rendered with the text. The label uses the same store/form/row variable merge behavior as value.
    • labelPosition: (string) Optional label placement. Use top (default) or left.
    • labelColor: (string) Optional MUI color for the label. Defaults to text.secondary.
    • labelWidth: (string or number) Optional minimum label width when labelPosition is left. Defaults to auto.
    • options: (object) Additional configuration options.
      • className: (string) CSS class names to apply to the text element.

Examples​

Basic Text​

component: text
props:
  value: "This is a simple paragraph."

Heading with Custom Class​

component: text
props:
  type: "h2"
  value: "Important Section Title"
  options:
    className: "section-title highlight-text"

Localized Text​

component: text
props:
  type: "p"
  value:
    en-US: "Welcome to CXTMS"
    es-ES: "Bienvenido a CXTMS"
    fr-FR: "Bienvenue sur CXTMS"

Dynamic Text with Variables​

component: text
props:
  type: "span"
  value: "Current shipment status: {{ shipment.status }}"

Labeled Text​

component: text
props:
  label: "Terminal"
  labelPosition: left
  labelWidth: 10rem
  value: "{{ terminal.name }}"
  type: span

Labels can be placed above or to the left of the rendered value. Both label and value are localized and template-parsed, so labels can include variables when needed.

Variable Merge Precedence​

When resolving template variables in the value property, the Text Component merges data from multiple sources. If the same variable name exists in more than one source, the following precedence applies (highest priority first):

  1. Row data (variables) — data passed directly to the component, such as the current row in a data grid or repeater. This has the highest priority.
  2. Form values — values from the enclosing custom form context (if present).
  3. Store — global application state from the context store. This has the lowest priority.

This means row-level data always takes precedence over store or form values of the same name, ensuring that components rendered inside grids or repeating layouts display the correct per-row values rather than being overridden by global state.

# Example: In a data grid, each row provides its own "status" variable.
# Even if the store also contains a "status" value, the row data wins.
component: text
props:
  type: "span"
  value: "Status: {{ status }}"

Advanced Usage​

Conditional Styling​

component: text
props:
  type: "p"
  value: "Shipment #{{ shipment.id }} is {{ shipment.status }}"
  options:
    className: "{{ eval shipment.status === 'delayed' ? 'text-warning' : 'text-success' }}"

Rich Text Formatting​

When more complex formatting is needed, you can use HTML within the text value:

component: text
props:
  type: "div"
  value: "This text has <strong>bold</strong> and <em>italic</em> parts."

Note: Be cautious with HTML in text to avoid security risks. Ensure proper sanitization is in place.

Best Practices​

  1. Use appropriate heading levels (h1 through h6) to maintain a logical document structure.
  2. Leverage the className option for consistent styling across your application.
  3. Utilize localization features for multi-language support.
  4. Keep text concise and clear, especially for labels and headings.
  5. Use variables and conditional rendering to create dynamic, context-aware text.
  6. Avoid overusing custom styling options; maintain consistency with your application's design system.

Accessibility Considerations​

  • Ensure proper heading hierarchy for screen readers.
  • Use sufficient color contrast for text visibility.
  • Avoid relying solely on color to convey information.