Back to Home

Documentation

React Beauty Flags is a simple React library that renders handmade flags for different topics as countries or cities. It provides an easy way to display flags in your React applications with minimal setup.

Goal

As a frontend developer, I faced many times the need to display flags in my applications. I found that most libraries available were either too complex or their designs were not visually appealing. I wanted to create a set based on beautiful designs that would allow me and any developer to display flags with ease.

As a Duolingo user, I was inspired by their flag designs and decided to create a similar feeling for React applications.

You will find +250 flags, including countries, regions, cities, and symbols. The flags are designed with a unique style that makes them visually appealing and easy to recognize.

If you develop a bank or financial application, this might not be the best choice for you. However, if you are building a beautiful with modern UX design, this library is perfect for you. šŸ˜€

Features

  • Beautiful Designs: The flags are handmade designed with a unique style that makes them visually appealing.
  • Easy to Use: The library is simple to use and requires minimal setup.
  • Customizable: You can customize the size of the flags by passing the width and height props, as well as other standard SVG props.
  • Utility Functions: The library includes utility functions to help you work with flags, such as getting flag data by code or name.
  • Typescript Support: The library is written in TypeScript, providing type safety and autocompletion in your IDE.

Installation

To install React Beauty Flags, use your package manager of choice:

pnpm install react-beauty-flags

You can also use npm or yarn:

yarn add react-beauty-flags

npm install react-beauty-flags

Usage

To use React Beauty Flags in your application, import theĀ FlagĀ component and pass theĀ codeĀ prop to specify the country:

import Flag from "react-beauty-flags"

const App = () => {
  return <Flag code="Es" />
}

export default App

If you want to enforce the flag code, you can use the FlagsCodesEnum:

import Flag, { FlagsCodesEnum } from "react-beauty-flags"

export const App = () => {
  return <Flag code={FlagsCodesEnum.ES} /> // Ts will enforce a correct code
}

Customizing the Size

The Flag is rendered by default with a width of 28px and a height of 20px (aspect ratio 1.4).

To customize the size, feel free to can pass both width and height props, even if you can pass any desired size, I heighly recommend keeping the aspect ratio (for possible shadows or bg colors) you can keep this relation using this formula (width = height * 1.4).

To use a scale factor, you can multiply the default size by the desired factor:

<Flag code="Es" width={28 * 1.3} height={20 * 1.3} />

Also you can pass only the width or height:

<Flag code="Es" width={50} /> // This is also valid but the aspect ratio will be different

The easier way to change the size is to pass the width and height props directly:

<Flag code="Es" width={200} height={140} />

Direct Flag Render

All flags are available as a direct render, an alternative to the Flag component. This is useful when you need to render the flag directly in your JSX without using a component.

import { ES } from "react-beauty-flags"
// Example in a component
const App = () => {
  return <ES />
}

// Example in a JSX
const App = () => {
  return <div>{ES}</div>
}

// Example in a styled component
const StyledFlag = styled.ES`
  width: 50px;
  height: 50px;
`


// Example in a static object
const flags = {
  es: ES,
  fr: FR,
  // ...
}

// Those examples are equivalent to <Flag code="Es" /> but with more control

Props

The Flag component and the direct imports accepts the following props:

code (required for the Flag component)

  • Type: FlagCode (string)
  • Description: The unique code for the flag you want to display. This should be one of the keys in FlagsCodesEnum.

Example:

<Flag code="Fr" /> // Displays the French flag

Additional SVG Props

Flag component or any direct component render also accepts all standard SVG props, allowing for further customization.

Example:

<Flag code="Jp" title="Japan Flag" role="img" id="japan-flag" />

Utility Functions

React Beauty Flags comes with several utility functions to help you work with flags.

getFlagByCode

  • Type: (code: FlagCode) => FlagData | undefined
  • Description: Retrieves flag data by its code.

Example:

import { getFlagByCode } from "react-beauty-flags"

const japanFlag = getFlagByCode("Jp")
console.log(japanFlag) // { code: "Jp", name: "Japan", type: "country" }

getFlagByName

  • Type: (name: string) => FlagData | undefined
  • Description: Retrieves flag data by its name.

Example:

import { getFlagByName } from "react-beauty-flags"

const franceFlag = getFlagByName("France")
console.log(franceFlag) // { code: "Fr", name: "France", type: "country" }

getFlagsByType

  • Type: (type: FlagType) => FlagData[]
  • Description: Retrieves all flags of a specific type.

Example:

import { getFlagsByType } from "react-beauty-flags"

const countryFlags = getFlagsByType("country")
console.log(countryFlags) // List of all country flags

Types

FlagType

All flags are categorized into different types, this is also useful when you want to filter flags with the getFlagsByType function.

The available flag types:

  • "country"
  • "region"
  • "world"
  • "historical"
  • "city"
  • "symbol"
  • "other"

FlagCode

A union type of all available flag codes. (e.g. "Us", "Fr", "Jp", ...)

FlagData

Represents the data structure of a flag:

type FlagData = {
  code: FlagCode
  name: string
  type: FlagType
}

Enum

FlagsCodesEnum

An enum of all valid flag codes:

enum FlagsCodesEnum {
  US = "US",
  FR = "FR",
  JP = "JP",
  // ...
}

Advanced Usage

Customizing the Flag Component

You can extend the functionality of the Flag component by using additional SVG attributes or wrapping it in your own custom components.

Example:

import Flag from "react-beauty-flags"

const CustomFlag = ({ code }) => (
  <div style={{ border: "1px solid black", display: "inline-block" }}>
    <Flag code={code} width={40} height={40} />
  </div>
)

const App = () => <CustomFlag code="BR" />
export default App

Made with ā¤ļø by Pol Gubau Amores