Skip to main content

Extensibility

Pearl UI is designed with extensibility in mind. It allows developers to easily integrate third-party components into the Pearl UI ecosystem. This is achieved through the 'pearl' function, a powerful utility that transforms a third-party component into a Pearl UI-compatible component.

The benefits of this extensibility are numerous:

  1. Flexibility: Developers are not restricted to using only the components provided by Pearl UI. They can bring in components from other libraries and make them work seamlessly with Pearl UI.
  2. Consistency: By transforming third-party components into Pearl UI-compatible components, developers can ensure a consistent look and feel across the entire application. All components, whether they are originally from Pearl UI or not, will adhere to the same theming and style props.
  3. Efficiency: Developers can leverage the power of Pearl UI's theming and style props without having to rewrite third-party components from scratch. This saves time and effort, and reduces the risk of introducing bugs.
  4. Scalability: As the project grows, developers can easily add more components to the Pearl UI ecosystem. This makes Pearl UI a scalable solution for large projects.

Examples#

Converting a Basic React Native Component#

Pearl UI's pearl function can be used to convert a basic React Native component into a Pearl UI-compatible component. This allows the component to leverage Pearl UI's theming and style props. Here's an example of how you can convert a basic View component:

import { View } from "react-native";import { pearl } from "pearl-ui";
const PearlView = pearl(View, {  componentName: "MyView",  type: "basic",  animatable: true,});

In this example, View is the base component that we are converting into a Pearl UI-compatible component. The componentName is set to 'MyView', which is a unique identifier for the component within the theme. The type is set to 'basic', indicating that this is a standalone component. The animatable flag is set to true, indicating that this component can support animations.

Converting a Third-Party Component#

Pearl UI's pearl function can also be used to convert a third-party component into a Pearl UI-compatible component. This allows the component to leverage Pearl UI's theming and style props. Here's an example of how you can convert the ActionButton component from the react-native-action-button library:

import ActionButton from "react-native-action-button";import {  pearl,  ButtonProps,  MoleculeComponentProps,  MolecularComponentConfig,} from "pearl-ui";
type ActionButtonAtoms = {  button: ButtonProps;};
const CustomActionButton = ({  atoms,}: Omit<  MoleculeComponentProps<"MyActionButton", ButtonProps, ActionButtonAtoms>,  "atoms"> & {  atoms?: Partial<ActionButtonAtoms>;}) => {  return (    <ActionButton buttonColor={props.style.backgroundColor} {...atoms.button} />  );};
const molecularConfig: MolecularComponentConfig<ActionButtonAtoms> = {  parts: ["button"],  baseStyle: {    button: {      bgColor: "blue",    },  },  sizes: {    sm: {      button: {        size: 40,      },    },    md: {      button: {        size: 50,      },    },    lg: {      button: {        size: 60,      },    },  },  variants: {    primary: {      button: {        bgColor: "blue",      },    },    secondary: {      button: {        bgColor: "green",      },    },  },  defaults: {    size: "md",    variant: "primary",  },};
// Add the molecular configuration to the themetheme.components.MyActionButton = molecularConfig;
const PearlActionButton = pearl<BaseActionButtonProps, "molecule">(  CustomActionButton,  {    componentName: "MyActionButton",    type: "molecule",    animatable: true,  });
// The created component can then be used easily in your application<PearlActionButton size="sm" variant="secondary" bgColor="red" />;

In this example, ActionButton is the base component that we are converting into a Pearl UI-compatible component. The componentName is set to 'MyActionButton', which is a unique identifier for the component within the theme. The type is set to 'molecule', indicating that this is a more complex component composed of multiple atoms. The animatable flag is set to true, indicating that this component can support animations.

Further Reading#

For more information on how to use Pearl UI's extensibility features, you may find the following sections of the documentation helpful:

  1. Design Principles: This section provides an overview of the design principles that Pearl UI adheres to, including the Atomic Design methodology. Understanding these principles can help you make the most of Pearl UI's extensibility features.
  2. pearl: This section provides a detailed explanation of the pearl function, including its parameters and how it works. This is a key function for extending Pearl UI with third-party components.