About

The Ribbon component is a versatile UI element that displays a ribbon with customizable text, position, and opinionanted variant colors. This component can be used to highlight new features, display error messages, or indicate success. You can use this ribbon component on a "trap" element (more on this in usage section). Only supports Tailwind projects.

Built With

Installation

Prerequisites

• npm

  npm install react-ribbon-ui@latest

• yarn

  yarn install react-ribbon-ui@latest

Usage

In order to use the Ribbon component and show it correctly on the UI, it is necessary to trap it within a relative-positioned element. Ribbon will always stick to the neareast relative-positioned element. This package provides a RibbonWrapper that you can import into your project and use it out of the box as shown in Example 1.

Example 1

<RibbonWrapper>
  <Ribbon text="NEW" position="top-right" variant="announcement" />
  <p>Your Content</p>
</RibbonWrapper>

However, because you may want to have Tailwind compute through your classes and get automatic suggestions (or you want to render an HTML element for accesibility/SEO reasons) , you can also create your custom element, but do remember to always apply a relative class name to it, otherwise the ribbon will stick to the closest positioned ancestor, which most certainly is not what you want.

Example 2

<div className="relative">
  <Ribbon text="NEW" position="top-right" variant="announcement" />
  <p>Your Content</p>
</div>

Important Note on Next.js Integration

There is a change you are using Next.js framework to build your project. If that is the case please add this configuration line to your next.config.mjs file:

/** @type {import('next').NextConfig} */
const nextConfig = { transpilePackages: ["react-ribbon-ui"] }; // add this line

export default nextConfig;

This will ensure Next.js transpiles and bundles dependencies from this package into your project out of the box.

For more information refer to: https://nextjs.org/docs/app/api-reference/next-config-js/transpilePackages

Important Note on TailwindCSS Integration

As of the date of publishing this package, TailwindCSS does not support native package resolution for styles. This means that any custom styling provided by this package using TailwindCSS will not automatically be included in your project. To ensure that the TailwindCSS styles from this package are applied correctly, you need to update your TailwindCSS configuration in your project.

Please follow these steps (assuming you've already installed TailwindCSS and created a configuration file):

1. Update your tailwind.config.js file to include the paths to the components of this package:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    ...
    "./node_modules/react-ribbon-ui/**/*.{js,ts,jsx,tsx}", // Add this line,
    ...
  ],
};

For more information refer to: https://tailwindcss.com/docs/content-configuration#working-with-third-party-libraries

API

Props

| Prop | Type | Description | Default | | ----------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -------------- | | text | string | The text to display inside the ribbon. This is a required prop. | - | | position | "top-left" \| "top-right" \| "bottom-right" \| "bottom-left" | The position of the ribbon. Possible values are "top-left", "top-right", "bottom-right", and "bottom-left". | "top-left" | | textColor | string | The text color. This should be a valid Tailwind color class. | "text-white" | | variant | "warning" \| "error" \| "success" \| "announcement" \| "default" | The variant of the ribbon. Possible values are "warning", "error", "success", "announcement", and "default". | "default" |

License

MIT

TODO

This is an ongoing development as it is a very basic component so there may be some features that you may think should have been added already and work out of the box. Here is some a few improvements that will be added soon:

• Add two more sizes to the ribbon (medium, big)
• Add stripes to the ribbon and let the consumer control it through props
• Add custom control over the background color from the consumer
• Add capability of having gradient colors