@blocklet/ui-react/docs/components-layout-footer.md

Some useful front-end web components that can be used in Blocklets.

# Footer

The `Footer` component provides a standardized, responsive footer for your application. It automatically populates its content—including branding, navigation links, social media icons, and copyright information—by reading your blocklet's metadata. This data-driven approach ensures consistency and simplifies configuration.

The component is designed to be responsive, adapting its layout for different screen sizes. It also includes built-in logic to hide itself when the application is running in an embedded mode, ensuring a clean user interface in integrations.

## Basic Usage

To add a footer to your application, simply import and render the `Footer` component. It requires no props for basic use, as it automatically sources data from the global `window.blocklet` object.

```jsx Usage Example icon=logos:react
import React from 'react';
import { Footer } from '@blocklet/ui-react';

export default function App() {
  return (
    <div style={{ minHeight: '100vh', display: 'flex', flexDirection: 'column' }}>
      <main style={{ flex: 1 }}>
        {/* Your application content goes here */}
      </main>
      <Footer />
    </div>
  );
}
```

## Props

The `Footer` component can be customized through the following props.

<x-field-group>
  <x-field data-name="meta" data-type="object" data-required="false">
    <x-field-desc markdown>
      An object containing blocklet metadata. Use this prop to override the default `window.blocklet` configuration or to provide data in environments where the global object is not available. The structure should match the blocklet metadata format.
    </x-field-desc>
  </x-field>
  <x-field data-name="theme" data-type="object" data-required="false">
    <x-field-desc markdown>
      A theme object to customize the footer's appearance. This object is deeply merged with the application's default theme, allowing you to override specific styles like colors, fonts, and spacing.
    </x-field-desc>
  </x-field>
</x-field-group>

## Metadata Configuration

The content of the `Footer` is primarily configured through the blocklet's metadata file (`blocklet.yml`). The component reads specific fields from this file to render its different sections.

Below is an example of a `blocklet.yml` configuration that populates all sections of the footer.

```yaml blocklet.yml
name: my-app
title: My App
description: A detailed description of my application that appears in the footer.
copyright: 'My Company Inc.'

# Navigation links are structured into groups
navigation:
  # Main footer navigation, supports two levels for grouping
  footer:
    - title: 'Products'
      items:
        - title: 'Product A'
          link: '/products/a'
        - title: 'Product B'
          link: '/products/b'
    - title: 'Resources'
      items:
        - title: 'Documentation'
          link: '/docs'
        - title: 'Blog'
          link: '/blog'

  # Social media links
  social:
    - title: 'twitter' # Icon is inferred from the title (e.g., 'twitter', 'github')
      link: 'https://twitter.com/your-handle'
    - title: 'github'
      icon: 'mdi:github' # You can also specify an Iconify icon name
      link: 'https://github.com/your-org'

  # Bottom links, typically for legal and privacy information
  bottom:
    - title: 'Privacy Policy'
      link: '/privacy'
    - title: 'Terms of Service'
      link: '/terms'
```

### Data Structure

The `navigation` object in your metadata defines the links displayed in the footer. It is organized into three distinct sections: `footer`, `social`, and `bottom`.

<x-field-group>
  <x-field data-name="navigation" data-type="object">
    <x-field-desc markdown>
      Contains all navigation structures for the application.
    </x-field-desc>
    <x-field data-name="footer" data-type="array">
      <x-field-desc markdown>
        An array of link groups for the main footer navigation area. Supports a two-level hierarchy.
      </x-field-desc>
      <x-field data-name="[].title" data-type="string" data-required="true" data-desc="The title of the navigation group (e.g., 'Products')."></x-field>
      <x-field data-name="[].link" data-type="string" data-required="false" data-desc="An optional link for the group title itself."></x-field>
      <x-field data-name="[].items" data-type="array" data-required="false" data-desc="An array of child navigation links.">
        <x-field data-name="[].title" data-type="string" data-required="true" data-desc="The display text for the link."></x-field>
        <x-field data-name="[].link" data-type="string" data-required="true" data-desc="The URL for the navigation link."></x-field>
      </x-field>
    </x-field>
    <x-field data-name="social" data-type="array">
      <x-field-desc markdown>
        An array of links to social media profiles.
      </x-field-desc>
      <x-field data-name="[].title" data-type="string" data-required="true" data-desc="The name of the social media platform, used to infer the icon (e.g., 'twitter')."></x-field>
      <x-field data-name="[].icon" data-type="string" data-required="false" data-desc="Explicitly specify an icon using an Iconify string (e.g., `mdi:github`). Overrides the inferred icon."></x-field>
      <x-field data-name="[].link" data-type="string" data-required="true" data-desc="The URL to the social media profile."></x-field>
    </x-field>
    <x-field data-name="bottom" data-type="array">
      <x-field-desc markdown>
        An array of links displayed at the very bottom of the footer, typically for legal notices.
      </x-field-desc>
      <x-field data-name="[].title" data-type="string" data-required="true" data-desc="The display text for the link (e.g., 'Privacy Policy')."></x-field>
      <x-field data-name="[].link" data-type="string" data-required="true" data-desc="The URL for the link."></x-field>
    </x-field>
  </x-field>
</x-field-group>

## Layouts

The `Footer` component intelligently selects the most appropriate layout based on the provided data. This ensures a clean and functional presentation across different use cases.

-   **Standard Layout**: This layout is automatically activated when `footer` navigation links or `social` media links are defined in your metadata. It features a multi-section design that elegantly organizes the brand information, social icons, and navigation columns. On mobile devices, the navigation groups become collapsible accordions for a better user experience.

-   **Plain Layout**: If no `footer` or `social` links are provided, the component falls back to a simplified, single-row layout. This is ideal for applications that only require a copyright notice and a few essential links, such as "Terms of Service" or "Privacy Policy".

## Theming

You can customize the footer's appearance by passing a `theme` object. This object is deeply merged with the existing theme, allowing for targeted overrides.

```jsx Custom Theme Example icon=logos:react
import { Footer } from '@blocklet/ui-react';

const customTheme = {
  palette: {
    background: {
      default: '#2c3e50', // A darker background for the footer
    },
    text: {
      primary: '#ecf0f1',
      secondary: '#bdc3c7',
    },
    divider: '#34495e',
  },
};

// ... in your component's render method
<Footer theme={customTheme} bordered />;
```

## Behavior in Embedded Mode

The `Footer` component is wrapped in a higher-order component (`withHideWhenEmbed`) that automatically hides it when the application is rendered in an embedded context. This behavior is controlled by a session storage key, `EMBED_MODE_KEY`. If this key is set to `1`, the footer will not be rendered. This is useful for preventing redundant footers when your blocklet is displayed inside another application.

---

For information on the header component, which is also configured via blocklet metadata, please see the [Header documentation](./components-layout-header.md).