SWIUI Core

📖 Overview

A big hello to the amazing Siwbit team! 🫡

Ladies and gentlemen,@swiui/core is the foundational UI package providing reusable components, utilities, and styles for building consistent and scalable user interfaces. It is designed to work seamlessly with React Native and Expo, leveraging Tailwind (via NativeWind) for styling. Some of these components include more than one UI element, while others consist of just one (so far). We will explain each component in detail: what it does, how it looks, its required and optional props, and how to use it. So, let’s begin with the first and most essential one—the Button.

🗒️ Features

• Pre-built UI components such as Buttons, Cards, Tags, and Icons, and Typography.
• Utility functions for common UI logic.
• Consistent styling using Tailwind and NativeWind.
• Accessibility-focused components.
• Fully customizable with className props.

🧰 Installation and Configuration

To install @swiui/core in your project, run:

# Using yarn
yarn add @swiui/core

# Using npm
npm install @swiui/core

Wow, cool name, right? 😎

Add the following line to the content section inside tailwind.config.js file (if you’ve already configured Tailwind). If not, go ahead and install nativewind & tailwind and configure it.:

content: {
  ...
  "./node_modules/@swiui/core/**/*.{ts,tsx,js,jsx}",
  ...
}

This will allow your app to read the Tailwind classNames from the package.

🛠️ Usage

Import components from @swiui/core and use them in your project:

import {
  Button,
  CoverCard,
  ListItemCard,
  VectorTag,
  ChipTag,
} from "@swiui/core";

🚦 Buttons

Button Component

The Button is a clickable UI element (just kidding—it’s :) exactly what it sounds like). It’s a button component with various features, including different shapes, variants, sizes, icons, labels, loaders, disabled states, and optional classNames.

To use the Button component, import it as follows:

import { Button } from "@swiui/core";

Here are some of the visual features of this component:

• Primary: A rectangular button (default) with a label and an icon.

  Code Example:

const MyComponent = () => {
  return (
    <Button
      shape="rectangular"
      iconName="error"
      iconColor="white"
      label="Press me"
      labelClassName="text-white"
      className="transition-transform delay-200 hover:bg-gray-400"
      onPress={() => alert("Press me")}
    />
  );
};

• Indicator and Label: This is useful for buttons that need to display a loading icon beside a text or without it.

  Code Example:

const MyComponent = () => {
  return (
    <Button
      shape="rectangular"
      variant="outlined"
      label="Press me"
      onPress={() => alert("Press me")}
      isLoading
      loaderColor="black"
      className="flex-row"
    />
  );
};

• Circle Button: The Button component also supports a rounded variant, which gives it a circular or pill-shaped appearance. Code Example:

  const MyComponent = () => {
    return (
      <Button
        shape="rounded"
        iconFamily="Ionicons"
        iconName="happy"
        iconColor="black"
        variant="outlined"
        onPress={() => alert("Press me")}
      />
    );
  };

• Icon Button: The Icon Button is a button that only displays an icon, making it perfect for actions that don’t require text labels (e.g., a settings or delete button).

  Code Example:

  const MyComponent = () => {
    return (
      <View className="w-fit">
        <Button
          shape="none"
          iconName="error"
          iconColor="black"
          variant="transparent"
          onPress={() => alert("Press me")}
        />
      </View>
    );
  };

Optional Props vs. Required Props

The Button component has both optional and required props. Below is a breakdown: | Prop Name | Type | Possible Values | Required | Description | |----------------|-------------------|---------------------|:--------:|----------------------------------------| | shape | string | "rounded", "rectangular", "none" | ❌ | Defines the button's shape. | | variant | string | "filled", "outlined", "transparent" | ❌ | | | width | DimensionValue | "100%", 100, "auto", "96" | ❌ | The width of the button (can be a percentage, pixel value, etc.). | | className | string | NativeWind ClassNames: "bg-blue-500 text-white" | ❌ | Custom Tailwind or CSS classes for the button container. | | labelClassName | string | NativeWind ClassNames: "bg-blue-500 text-white" | ❌ | Custom Tailwind or CSS classes for the button text. | | isDisabled | boolean | false, true | ❌ | Disables the button if set to true. | | isLoading | boolean | false, true | ❌ | Shows a loading spinner if set to true. | | loaderColor | string | hex, "color", rgb(87,172,139) | ❌ | The color of the loading spinner (if isLoading is true). | | label | string | Any text | ✅ | The test displayed on the button | | onPress | () => void | () => console.log("Clicked") | ✅ | The function to execute when the button is clicked/pressed. | | buttonRole | AccessibilityRole | "none", "button", "alert", etc. | ❌ | Defines the accessibility role of the button | | iconName | string | expo vectors icons: "error", "settings" | ❌ | Adds an icon to the button. | | iconSize | number | 20, 25 | ❌ | The size of the icon in pixels. | | iconColor | string | hex, "color", rgb(87,172,139) | ❌ | The color of the icon. | | iconFamily | string | "AndDesign", "MaterialCommunityIcons", "Fontisto", etc. | ❌ | The icon family to use (e.g., MaterialIcons, FontAwesome). |

🪪 Cards

Let’s move on to the Card component, which includes two types: Card Cover and List Item Card. Below is a detailed explanation of the Card Cover component, including its purpose, structure, and usage.

Card Cover Component

The Card Cover component is designed to display a card with a cover image and optional children (e.g., text, buttons, or other elements). It uses an ImageBackground from React Native to render the cover image and allows for customization of width, height, and styling.

To use the CoverCard component, import it as follows:

import { CoverCard } from "@swiui/core";

Code Example:

 const MyComponent = () => {
    return (
      <View>
        <Text className="text-lg text-purple-900">Cover Card</Text>
        <CoverCard coverImage="https://picsum.photos/200" className="space-y-2">
          <View className="bg-[#00000083] absolute top-0 bottom-0 left-0 right-0 flex items-center justify-center">
        <Text className="text-white text-2xl">Hello there</Text>
    </View>
  </CoverCard>
</View>
    );

Desired Outcome:

Optional Props vs. Required Props

| Prop Name | Type | Possible Values | Required | Description | | ---------- | ---------------- | ------------------------------------------------------- | :------: | ------------------------------------------------------------------------------- | | coverImage | string | number | "https://example.com/image.jpg", require("./image.png") | ✅ | The source of the cover image. Can be a URL (string) or a local image (number). | | width | DimensionValue | "100%", 328, "200px" | ❌ | The width of the card. Defaults to 328. | | className | string | "bg-white shadow-lg" | ❌ | Custom Tailwind or CSS classes for the card container. | | children | React.ReactNode | <Text >, <Button >, <View > | ❌ | Optional children to render inside the card (e.g., text, buttons). |

Card Cover Component

The List Item Card is a versatile component designed to display a list item with a title, a list of entities (e.g., performers, tags, or categories), an optional thumbnail, and optional children (e.g., buttons or icons). It dynamically adjusts the number of visible entities based on the available container width and supports custom thumbnail shapes.

To use the List Item Card component, import it as follows:

import { ListItemCard } from "@swiui/core";

Example Code:

const instructors = ["Ezzidin", "Haider", "Hasan", "Sadiq", "Mehdi", "Ali", "Zainab", "Zahraa"]
const MyComponent = () => {
    return (
     <View className="w-74">
      <Text className="text-lg text-purple-900">List Item Card</Text>
      <ListItemCard
        title="Coding Lessons"
        entities={instructors}
        thumbnail="https://picsum.photos/200"
        onPress={() => alert("")}
      />
  </View>
    )

Desired Outcome:

Optional Props vs. Required Props

| Prop Name | Type | Possible Values | Required | Description | | -------------- | ------------------------ | ------------------------------------------------------- | :------: | ----------------------------------------------------------------------------------- | | title | string | "Product Name" | ✅ | The title of the list item. | | entities | string[] | ["John Doe", "Jane Smith"] | ❌ | An array of entities (e.g., performers, tags) to display. | | thumbnail | string | number | "https://example.com/image.jpg", require("./image.png") | ❌ | The source of the thumbnail image. Can be a URL (string) or a local image (number). | | thumbNailShape | "rounded", "rectangular" | "rounded", "rectangular" | ❌ | The shape of the thumbnail. Defaults to "rounded". | | children | React.ReactNode | <Text> Hello </Text>, <Button />, <View/> | ❌ | Optional children to render inside the card (e.g., text, buttons). | | onPress | () => void | () => console.log("Clicked") | ✅ | The function to execute when the list item is pressed. |

Playlist Card Component

The PlaylistCard is a component designed to display a playlist with a cover image, title, playlist info, and interactive controls. It includes buttons for play/pause, shuffle, add, menu, and a "show more" action. The component is ideal for showcasing playlists in a compact and interactive format.

To use the playlist Card component, import it as follows:

import { PlaylistCard } from "@swiui/core";

Example Code:

const instructors = [
    "Monica",
    "Joey",
    "Ross",
    "Chandler",
    "Rachel",
    "Ali",
    "Zainab",
    "Zahraa",
  ];

  const MyComponent = () => {
    return (
      <View className="w-96">
          <PlaylistCard
            coverCardImage="https://wallpapercave.com/wp/wp12012407.jpg"
            title="Why do Muslims Pray Five Times a Day?"
            entities={instructors}
            companyThumbnail="https://cdn.pixabay.com/photo/2015/10/05/22/37/blank-profile-picture-973460_1280.png"
            playlistInfo="Company Name. 58 Audio. 1hr"
          />
       </View>
    )

Desired Outcome:

Optional Props vs. Required Props

| Prop Name | Type | Possible Values | Required | Description | | :----------------------: | :-------------------------: | :----------------------------------------------------: | :----------: | :----------------------------------------------------------------------------------------------: | | coverCardImage | string | number | "https://example.com/cover.jpg" require("./cover.jpg") | ❌ | The source of the playlist cover image. Can be a URL (string) or a local image (number). | | title | string | "Summer Vibes" | ✅ | The title of the playlist. | | companyThumbnail | string | "https://example.com/logo.png" require("./logo.png") | ❌ | The source of the company or creator thumbnail. Can be a URL (string) or a local image (number). | | entities | string[] | ["Artist 1", "Artist 2"] | ✅ | An array of entities (e.g., artists or contributors) associated with the playlist. | | playlistInfo | string | "By Youtube, 50 songs" | ❌ | Additional information about the playlist (e.g., creator and song count). | | handleShowMore | () => void | () => console.log("Show More") | ❌ | Function to handle the "show more" action (triggered by clicking the title). | | handleShuffle | () => void | () => console.log("Shuffle") | ❌ | Function to handle the shuffle action. | | handleAdd | () => void | () => console.log("Add") | ❌ | Function to handle the add action. | | handleMenu | () => void | () => console.log("Menu") | ❌ | Function to handle the menu action. | | isPlaying | boolean | true, false | ❌ | The play/pause state (for controlled mode). If not provided, internal state is used. | | onPausePlay | (newState: boolean) => void | (newState) => console.log(newState) | ❌ | Callback triggered when the play/pause button is clicked. | | decelerationRate | number | 0.999 | ❌ | Deceleration rate for momentum scrolling. Defaults to 0.999. | | swipeSensitivity | number | 0.1 | ❌ | Sensitivity for swipe velocity detection. Defaults to 0.1. | | minDistance | number | 30 | ❌ | Minimum horizontal swipe distance required to disable vertical scrolling. Defaults to 30. | | style | StyleProp | { backgroundColor: 'red' } | ❌ | Style for the slider container. | | contentContainerStyle | StyleProp | { padding: 10 } | ❌ | Style for the slides container. | | paginationContainerStyle | StyleProp | { marginTop: 20 } | ❌ | Style for the pagination container. | | dotStyle | StyleProp | { backgroundColor: 'gray' } | ❌ | Style for inactive pagination dots. | | activeDotStyle | StyleProp | { backgroundColor: 'black' } | ❌ | Style for the active pagination dot. |

🏷️ Tags

Chip Tag Component

The ChipTag is a small, customizable UI component used to display labels or tags. It supports custom background colors, random background color generation, and additional Tailwind CSS classes for styling.

To use the Chip Tag component, import it as follows:

import { ChipTag } from "@swiui/core";

Code Example

const MyComponent = () => {
    return (
     <View className="w-74">
        <ChipTag label="Text" backgroundColor="#e7d5ff" textClassName="text-sm font-bold" />
  </View>
    )

Desired Outcome

Optional Props vs. Required Props

| Prop Name | Type | Possible Values | Required | Description | | --------------- | ---------- | ---------------------------- | :------: | -------------------------------------------------------------------------- | | label | string | "Tag", "Category" | ✅ | The text to display inside the chip. | | backgroundColor | string | "#e7d5ff", "#ffc7cb" | ❌ | The background color of the chip. If not provided, a random color is used. | | className | string | "bg-white border" | ❌ | Additional Tailwind CSS classes for custom container styling. | | TextClassName | string | "text-white" | ❌ | Additional Tailwind CSS classes for custom text styling. | | onPress | () => void | () => console.log("Clicked") | ✅ | The function to execute when the tag is clicked/pressed. | |

Vector Tag Component

The VectorTag is a visually rich component that displays a tag with a label, a background color, and customizable vector graphics (e.g., circles, rectangles, paths). It uses predefined designs (tagDesigns) to render the tag, ensuring consistency and flexibility.

To use the VectorTag component, import it as follows:

import { VectorTag } from "@swiui/core";

Example Code:

const MyComponent = () => {
    return (
     <View >
          <VectorTag label="Text" index={7} />
    </View>
    )

Desired Outcome

Optional Props vs. Required Props

| Prop Name | Type | Possible Values | Required | Description | | --------- | ------ | ----------------- | :------: | ---------------------------------------------- | | label | string | "Tag", "Category" | ✅ | The text to display inside the tag. | | index | number | 0, 1, 2, .. 7 | ❌ | The index of the design to use. Defaults to 0. |

Range of Available Indexes and Their Effects

The VectorTag component supports 8 unique designs, each with its own background color, text color, and vector graphics. The index prop is used to select a specific design. Below is a summary of the available designs:

| index | Background Color | Text color | Visual Theme | | :---: | ---------------------- | --------------- | ---------------------------------------------------------- | | 0 | #84D0AC (light green) | #FFFFFF (white) | Nature-inspired with geometric shapes. | | 1 | #C99961 (light brown) | #FFFFFF (white) | Earthy with concentric circles and a 3D cuboid. | | 2 | #E98D88 (light red) | #FFFFFF (white) | Bold and vibrant with overlapping rectangles. | | 3 | #5C71CC (light blue) | #FFFFFF (white) | Calming with a wavy pattern and geometric shapes. | | 4 | #9862B8 (light purple) | #FFFFFF (white) | Artistic with a cuboid, zigzag line, and patterned circle. | | 5 | #D86041 (light orange) | #FFFFFF (white) | Dynamic with a 3D cuboid and concentric circles. | | 6 | #61BCC9 (light teal) | #FFFFFF (white) | Modern and minimalist with fluid shapes. | | 7 | #5C97CC (light blue) | #FFFFFF (white) | Clean and geometric with balanced shapes. |

Notes:

• If no designIndex is provided, the component uses 0 (light green theme).
• Valid values for designIndex are 0 to 7. If designIndex exceeds the range, it wraps around using modulo (%). For example, 8 maps to 0.

Contributing

For internal use only. Please follow the project’s coding guidelines when making modifications.

License

This package is proprietary and intended for use within the company.