MAF Configuration Practices – Add Tooltips to Buttons

Overview

Most buttons in Maximo Mobile are displayed as icon-only to minimize scrolling and maximize screen space. While this creates a clean interface, it can be challenging for new users who are unfamiliar with the icons. Tooltips provide contextual help by displaying descriptive text when users interact with buttons.

Use Cases:

Icon-only buttons that need clarification
Improving accessibility for screen readers
Helping new users learn the interface
Meeting WCAG accessibility standards

Prerequisites:

Access to MAF Configuration application
Basic understanding of XML button elements

Implementation

Step 1: Identify buttons that need tooltips

Review your application and identify icon-only buttons that would benefit from tooltips. Focus on:

Frequently used actions (Save, Delete, Edit)
Non-obvious icons
Critical functions

Step 2: Add the icon-aria-label attribute

Add the icon-aria-label attribute to your button element with descriptive text:

XML Configuration:

<!-- Button with tooltip -->
<button icon-aria-label="Report Work" 
        icon="carbon:report" 
        on-click="navigateToReportWork" 
        on-click-arg="{woDetailResource.item}" 
        kind="secondary" 
        id="m5kg3"/>

Attribute Explanation:

icon-aria-label - The text displayed in the tooltip and read by screen readers
icon - The icon to display (Carbon icon library)
on-click - The method to call when clicked
kind - Button style (primary, secondary, ghost, etc.)

On Web/Desktop:

Hover your mouse over the button
Tooltip should appear after a brief delay
Tooltip should disappear when mouse moves away

On Mobile (iOS/Android):

Long-press the button (press and hold)
Tooltip should appear
Release to dismiss or continue holding to see tooltip

Validation & Testing

How to verify:

Visual Test:
- Open the application in a browser
- Hover over the button
- Confirm tooltip text appears and is readable
Mobile Test:
- Open the application on a mobile device
- Long-press the button
- Verify tooltip displays correctly
Accessibility Test:
- Use a screen reader (NVDA, JAWS, VoiceOver)
- Navigate to the button
- Confirm the aria-label is announced

Common Issues:

Issue: Tooltip doesn’t appear on hover
- Cause: Missing or misspelled icon-aria-label attribute
- Solution: Verify attribute name is exactly icon-aria-label
Issue: Tooltip text is cut off
- Cause: Text is too long for the tooltip container
- Solution: Keep tooltip text concise (under 50 characters)
Issue: Tooltip doesn’t work on mobile
- Cause: Long-press gesture not recognized
- Solution: Ensure you’re holding for at least 500ms

Best Practices

✅ Do:

Use action verbs (“Report Work”, “Delete Item”, “Edit Details”)
Keep text concise and descriptive (under 50 characters)
Use sentence case (“Report work” not “REPORT WORK”)
Be consistent with terminology across the app
Test on both web and mobile platforms
Consider internationalization (i18n) for multi-language support

❌ Don’t:

Duplicate visible button labels in tooltips
Use vague text (“Click here”, “Button”)
Include special characters that might not render properly
Make tooltips too long or verbose
Forget to test with screen readers

Accessibility Considerations:

Tooltips improve accessibility for visually impaired users
Screen readers announce the icon-aria-label text
Ensure tooltip text is meaningful without visual context
Follow WCAG 2.1 Level AA guidelines

Performance Considerations:

Tooltips have minimal performance impact
No additional API calls or data loading required
Rendered client-side only when needed

Examples

Common Button Patterns

<!-- Save button -->
<button icon-aria-label="Save changes" 
        icon="carbon:save" 
        on-click="saveRecord" 
        kind="primary" 
        id="btn_save"/>

<!-- Delete button -->
<button icon-aria-label="Delete work order"

Context-Specific Tooltips

<!-- Status-dependent tooltip -->
<button icon-aria-label="{item.status === 'COMP' ? 'Reopen work order' : 'Complete work order'}" 
        icon="carbon:checkmark" 
        on-click="toggleStatus" 
        id="btn_status"/>

<!-- Conditional tooltip based on permissions -->
<button icon-aria-label="Approve work order" 
        icon="carbon:checkmark--outline"

Prerequisites:

Basic Concepts - Understanding MAF fundamentals

Related Practices:

Making Fields Read-Only - Field configuration patterns
Marking Required Fields - Form validation

External Documentation:

Additional Notes

Internationalization (i18n):

For multi-language applications, use message keys instead of hardcoded text:

<button icon-aria-label="{app.getLocalizedLabel('button.report.work')}" 
        icon="carbon:report" 
        on-click="navigateToReportWork" 
        id="btn_report"/>

Carbon Icon Library:

MAF uses the Carbon Design System icon library. Browse available icons at: https://carbondesignsystem.com/guidelines/icons/library/

Mobile-Specific Considerations:

Long-press duration: ~500ms minimum
Tooltip positioning may vary by device
Test on both iOS and Android platforms
Consider touch target size (minimum 44x44 pixels)

Browser Compatibility:

Modern browsers: Full support
IE11: Limited support (consider polyfills)
Mobile browsers: Full support with long-press gesture

Edit this page on GitHub

Page last updated: 13 January 2026

Basic concepts: Data Sources

Simple configurations: Replace work order’s Schedule Finish Date with Target Complete Date attribute

Add Tooltips to Buttons