Getting Started

This guide provides a step-by-step walkthrough to install the @blocklet/ui-react library and render your first components. The objective is to have a functional Header and Footer within your application in a minimal amount of time.

Prerequisites#

Before proceeding, ensure you have the following installed in your development environment:

  • A functional React project.
  • Node.js and a package manager (npm or yarn).

Installation#

To begin, add the @blocklet/ui-react package to your project using your preferred package manager.

With npm:

npm

npm install @blocklet/ui-react

With yarn:

yarn

yarn add @blocklet/ui-react

The Header and Footer components are designed for simplicity and can be rendered without any initial configuration. They automatically source their data from the blocklet's metadata.

  1. Import the Header and Footer components into your main application file (e.g., App.js).
  2. Place them at the top and bottom of your application's layout, respectively.

App.js

import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';
import Footer from '@blocklet/ui-react/lib/Footer';

function App() {
  return (
    <div>
      <Header />
      <main style={{ padding: '20px', minHeight: 'calc(100vh - 128px)' }}>
        {/* Your application content goes here */}
        <h1>Welcome to My Blocklet</h1>
      </main>
      <Footer />
    </div>
  );
}

export default App;

The components automatically retrieve configuration details—such as the application name, logo, and navigation links—from the window.blocklet metadata object, which is injected by the Blocklet Server environment.

Furthermore, the Header component will intelligently render additional controls:

  • A user session manager is displayed if a SessionContext is available.
  • A language selector is displayed if a LocaleContext is available.

Manual Configuration#

For development, testing, or cases where you need to override the default metadata, you can pass a configuration object directly to the components using the blockletMeta prop.

App.js

import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';

const customBlockletMeta = {
  appName: 'My Custom App',
  appLogo: 'https://path.to/your/logo.png',
  navigation: [
    {
      title: 'Home',
      link: '/',
    },
    {
      title: 'Documentation',
      link: '/docs',
    },
  ],
};

function App() {
  return (
    <div>
      <Header blockletMeta={customBlockletMeta} />
      {/* ... rest of your app */}
    </div>
  );

See all 1 lines

This approach gives you precise control over the component's appearance and behavior by overriding any data provided by the global window.blocklet object.

Customizing the Header#

The Header component includes an addons area on the right side, which you can customize to include your own components, such as action buttons or custom links.

The addons prop accepts a function that receives the default addon components as an argument. This allows you to prepend, append, or completely replace them.

CustomHeader.js

import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';
import Button from '@mui/material/Button'; // Example using Material-UI

function CustomHeader() {
  return (
    <Header
      addons={existingAddons => {
        return [
          <Button
            key="custom-action"
            variant="contained"
            color="primary"
            size="small"
            style={{ marginRight: 8 }}>
            Custom Action
          </Button>,
          ...existingAddons, // Important: preserves default session/locale addons
        ];
      }}
    />
  );
}

In this example, a custom button is prepended to the existing addons. By including ...existingAddons, you ensure that the default session and locale controls remain visible.

Summary#

You have successfully installed the @blocklet/ui-react library, rendered default Header and Footer components, and learned how to provide custom configurations and addons.

With these fundamentals in place, you are now prepared to explore the full range of components available in the library. For detailed documentation on layout, user management, and utility components, please proceed to the Components section.

Overview
Core Concepts