Elemental UI Framework

Common errors

• Error: Invariant Violation: Minified React error #XXX; visit https://reactjs.org/docs/error-decoder.html?invariant=XXX for the full message.

  cause This generic React error often indicates a mismatch between Elemental UI's expected React environment (very old versions) and the React version installed in your project, or a misuse of old React APIs.
  fix Verify that your `react` and `react-dom` peer dependencies exactly match the `^0.14.0 || ^15.0.0` range specified by Elemental. Downgrade your React versions if necessary, or use `npm install --legacy-peer-deps` (if applicable) to force install compatible versions.

• Module not found: Error: Can't resolve 'elemental/less/elemental.less' in 'your-app-path'

  cause The main LESS stylesheet for Elemental UI is not being correctly resolved or imported by your build system, or `less-loader` is not configured.
  fix Ensure `less-loader` is installed and properly configured in your Webpack (or equivalent) setup to handle `.less` files. Add `@import '~elemental/less/elemental.less';` to your main stylesheet. Verify `node_modules` is included in your loader paths.

• TypeError: Cannot read property 'propTypes' of undefined

  cause This often occurs when trying to use React components that rely on the `React.PropTypes` API, which was removed in React v15.5. Elemental UI predates this change.
  fix While `prop-types` package can polyfill this for *some* cases, the fundamental incompatibility with modern React due to other API changes remains. The only true fix is to use Elemental with `react@<15.5` or migrate to a new UI library.

Warnings

• breaking Elemental UI is built for React versions `^0.14.0 || ^15.0.0`. It is incompatible with modern React versions (16+), requiring significant polyfills or wrappers, and will likely break without extensive modifications due to changes in React's API and lifecycle methods.
  Fix: Use Elemental UI with a compatible React environment (React 0.14.x or 15.x) or consider migrating to a actively maintained UI library. Backporting to newer React versions is highly complex and not recommended.
• gotcha Elemental UI relies on LESS for its styling. You must configure your build process (e.g., Webpack with `less-loader`) to compile and include the `elemental.less` stylesheet, otherwise components will render unstyled.
  Fix: Ensure your project's build configuration includes a LESS compiler (e.g., `npm install less less-loader --save-dev` and configure Webpack to handle `.less` files). Then, import the main stylesheet: `@import '~elemental/less/elemental.less';` in your global CSS/LESS file.
• breaking The Elemental UI project is effectively abandoned, with its last npm publish and GitHub activity dating back approximately seven years (as of late 2017). This means no further bug fixes, security updates, or feature development will occur.
  Fix: For new projects, avoid Elemental UI. For existing projects, plan for migration to a currently maintained React UI library (e.g., Ant Design, Material UI, Elemental Plus - a separate project for Vue).
• gotcha The peer dependency `react-addons-css-transition-group` is deprecated in modern React. Using Elemental UI with newer React setups might lead to warnings or require manual integration of `react-transition-group` (its spiritual successor), if a compatible version can even be found for the old React versions Elemental requires.
  Fix: This issue is inherent to using an abandoned library with old dependencies. The most robust fix is migrating to a modern UI library. If strictly adhering to Elemental, ensure all specified peer dependencies are installed, even if deprecated.

Install

• npm install elemental npm
• yarn add elemental yarn
• pnpm add elemental pnpm

Imports

• Button
  wrong:

  const { Button } = require('elemental');

  correct:

  import { Button } from 'elemental';

  Elemental was developed during an era when ES Modules were becoming prevalent, but CommonJS was still common. While ESM `import` syntax is shown in examples, CJS `require` might have been used in older Node.js contexts. Ensure your build system (Webpack/Browserify) handles this appropriately.
• Alert
  wrong:

  import Alert from 'elemental/lib/Alert';

  correct:

  import { Alert } from 'elemental';

  Components are intended to be imported as named exports from the 'elemental' package. Direct deep imports from 'lib/' paths, while sometimes seen in older projects for tree-shaking, are not the officially documented approach and may not work as expected or break in patched versions.
• Spinner
  wrong:

  import * as Elemental from 'elemental';
  const MySpinner = Elemental.Spinner;

  correct:

  import { Spinner } from 'elemental';

  While importing all exports (`* as Elemental`) is syntactically valid, it can lead to larger bundle sizes if not properly tree-shaken by your bundler. Prefer named imports for specific components.

Quickstart

This quickstart demonstrates rendering a Button, an Alert, and a Spinner component from Elemental UI in a basic React application, including toggling the alert visibility. It highlights the need for LESS compilation for styles.

import React from 'react';
import ReactDOM from 'react-dom';
import { Button, Alert, Spinner } from 'elemental';

// Elemental's styles are written in LESS and need to be imported or compiled.
// For a modern setup, you would typically configure your build tool (e.g., Webpack)
// to process LESS files and import the main stylesheet.
// E.g., in your main JS/TS entry file or a global CSS file:
// @import './node_modules/elemental/less/elemental.less';
// Or compile it via CLI: lessc ./node_modules/elemental/less/elemental.less styles.min.css

function App() {
  const [showAlert, setShowAlert] = React.useState(false);

  return (
    <div>
      <h1>Elemental UI Demo</h1>
      <Button onClick={() => alert('Hello from Elemental!')} type="primary">
        Click Me
      </Button>
      <Button onClick={() => setShowAlert(!showAlert)} type="link">
        Toggle Alert
      </Button>
      {showAlert && (
        <Alert type="info">
          This is an Elemental Alert!
          <Button type="link" onClick={() => setShowAlert(false)}>Close</Button>
        </Alert>
      )}
      <div style={{ padding: '20px' }}>
        <Spinner size="lg" />
      </div>
    </div>
  );
}

ReactDOM.render(<App />, document.getElementById('root'));