Terra Application Utility

2.60.1 · active · verified Sun Apr 19

The Terra Application Utility library, currently at version 2.60.1, provides React components specifically designed for disclosing utility menus within applications built using the Cerner Terra design system. It offers two distinct versions: a 'header' variant for integration with `terra-application-header-layout` and a 'menu' variant for use with `terra-application-menu-layout`. This structured approach ensures consistent UI patterns and behaviors for common application functionalities such as user settings, help, notifications, or profile management. While a specific release cadence is not detailed in the provided documentation, the package's versioning indicates active development and maintenance within the broader Terra framework. Its key differentiator is its tight integration into the Terra ecosystem, providing pre-styled and functional components that adhere to Cerner's established design language and accessibility standards, reducing development overhead for Terra-based applications.

Common errors

```
Module not found: Can't resolve 'terra-application-utility'
```
cause The package `terra-application-utility` has not been installed or is misspelled.

fix Run `npm install terra-application-utility` or `yarn add terra-application-utility` to install the package.
```
TypeError: Cannot read properties of undefined (reading 'Header')
```
cause The default import for `terra-application-utility` is undefined, likely due to an incorrect import statement, or the package failed to load.

fix Ensure you are importing `ApplicationUtility` as a default import: `import ApplicationUtility from 'terra-application-utility';` and that the package is correctly installed.
```
Invariant Violation: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined.
```
cause This often occurs in React if a component is imported incorrectly or is undefined at runtime. For `terra-application-utility`, it could mean `ApplicationUtility` itself or its sub-components (`.Header`, `.Menu`) are not correctly resolved.

fix Verify that `terra-application-utility` is installed, and your import statement for `ApplicationUtility` is correct. Also, ensure you are accessing `.Header` or `.Menu` as properties of the default `ApplicationUtility` import, not as named exports.

Warnings

gotcha Terra components, including Application Utility, are designed to work within the broader Terra Framework. Using them in isolation without the correct layout components (e.g., `terra-application-header-layout` or `terra-application-menu-layout`) may lead to unexpected styling or functional issues.
Fix: Ensure you are using `terra-application-utility` within a compatible Terra layout component as intended by the framework's design.
breaking As a component within the Terra Framework, major version updates of `terra-application-utility` or its peer dependencies (like React or `react-intl`) may introduce breaking changes. Always review the release notes for the Terra Framework and individual component packages when upgrading major versions.
Fix: Consult the official Terra Framework migration guides and release notes for each major version upgrade to identify and address breaking changes in props, APIs, or required peer dependency versions.

Install

npm install terra-application-utility npm
yarn add terra-application-utility yarn
pnpm add terra-application-utility pnpm

Imports

ApplicationUtility
wrong:
```
const ApplicationUtility = require('terra-application-utility');
```
correct:
```
import ApplicationUtility from 'terra-application-utility';
```
The primary default export for the utility component. Generally used as a namespace for Header and Menu variants.
ApplicationUtility.Header
wrong:
```
import { Header } from 'terra-application-utility';
```
correct:
```
import ApplicationUtility from 'terra-application-utility';
// ... inside JSX: <ApplicationUtility.Header />
```
The Header version of the utility, used within `terra-application-header-layout` components. It's a property of the default export, not a named export.
ApplicationUtility.Menu
wrong:
```
import { Menu } from 'terra-application-utility';
```
correct:
```
import ApplicationUtility from 'terra-application-utility';
// ... inside JSX: <ApplicationUtility.Menu />
```
The Menu version of the utility, typically used within `terra-application-menu-layout` components. Similar to Header, it's accessed via the default export.

Quickstart

Demonstrates a basic implementation of `ApplicationUtility.Menu` with state management for opening and closing, including placeholder content.

import React, { useState } from 'react';
import ApplicationUtility from 'terra-application-utility';
import Button from 'terra-button'; // Assuming terra-button for demonstration

const MyUtilityMenu = () => {
  const [isOpen, setIsOpen] = useState(false);

  const handleToggle = () => {
    setIsOpen(!isOpen);
  };

  const handleClose = () => {
    setIsOpen(false);
  };

  return (
    <ApplicationUtility.Menu
      id="my-app-utility-menu"
      variant="menu"
      isOpen={isOpen}
      title="User Menu"
      onChange={handleToggle}
      onClose={handleClose}
      button={(<Button onClick={handleToggle} text="Open User Menu" />)}
    >
      {/* Example utility items */}
      <div style={{ padding: '15px' }}>
        <div>Settings</div>
        <div>Help</div>
        <div onClick={() => alert('Logged out!')}>Logout</div>
      </div>
    </ApplicationUtility.Menu>
  );
};

export default MyUtilityMenu;

view raw JSON →