# @kekalma/language-selector

> Language selector component for React

Latest version **1.0.1** (published 2021-09-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install @kekalma/language-selector
pnpm add @kekalma/language-selector
yarn add @kekalma/language-selector
bun add @kekalma/language-selector
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2021-09-29 |
| First published | 2021-08-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=10 |
| Dependencies | 1 |
| Unpacked size | 433 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | kissato70 |
| Maintainers | kissato70 |
| Keywords | react, language, dropdown, selector, component, multi-language, context, typescript |

## Links

- npm: https://www.npmjs.com/package/@kekalma/language-selector
- Repository: https://github.com/kissato70/kekalma-language-selector
- Homepage: https://github.com/kissato70/kekalma-language-selector#readme
- Issues: https://github.com/kissato70/kekalma-language-selector/issues
- Funding: https://bit.ly/kissato70_paypal_donate
- npm.io page: https://npm.io/package/@kekalma/language-selector

## Dependencies (1)

- [national-flag-icons](https://npm.io/package/national-flag-icons.md) ^1.0.1

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.0.1 (latest) — 2021-09-29
- 1.0.0 — 2021-09-29
- 0.0.9 — 2021-09-13
- 0.0.8 — 2021-09-13
- 0.0.7 — 2021-09-13
- 0.0.6 — 2021-09-13
- 0.0.5 — 2021-09-03
- 0.0.4 — 2021-09-03
- 0.0.3 — 2021-09-03
- 0.0.2 — 2021-08-31
- 0.0.1 — 2021-08-31

## README

# Language selector menu for React

A flexible language selector component for React, where you can change the format and the look with many options. The actual state is stored in a context, whose value can be used in other parts of the project.  
Part of the [@kekalma](https://www.npmjs.com/search?q=%40kekalma) component family.

## Usage examples

The following simple code example demonstrates the use of the language selector, with separate (optional) context and an event handler function.  
You should use at least one of `context` or `onLanguageChange` properties.

![simple](./example_images/simple.jpg)

<br>  

__App.tsx__

_The `<LanguageSelector>` component can be placed into an `<ul>` element, as it produces a list item._

```tsx
import React,{useState} from 'react'
import {LanguageSelector as Language, emptyLanguage} from '@kekalma/language-selector'
import type { languageType } from '@kekalma/language-selector'
import { languageContext } from './context'
import Info from './Info'
import { languages } from './languageList'

export default function App() {
  const [selectedLanguage, setSelectedLanguage] = useState<languageType>(emptyLanguage);
  const changeHandler = (newLang: languageType, oldLang: languageType) => {
    console.log("The language has been changed: ", oldLang.name, " -> ", newLang.flag)
  }
  return (
    <languageContext.Provider value={{language: selectedLanguage, setLanguage: setSelectedLanguage}}>
    <Info context={languageContext}/>
    <ul>
      <Language
          languages={languages}
          selectedLanguageFlag="us"   
          context={languageContext}
          onLanguageChange={changeHandler}
      />
    </ul>
      <Info/>
    </languageContext.Provider>
  )
}
```

<br>

__languageList.ts__

```ts
import React from 'react'
import type { languageType } from '@kekalma/language-selector'

export const languages: languageType[] = [
  { "code": "hu","name": "Hungarian" },
  { "code": "de","name": "German" },
  { "code": "en","name": "US English","flag": "us" },
  { "code": "en","name": "British English","flag": "gb" },
  { "code": "fr","name": "French" }
]
```  

*Note the use of the 'flag' property. It is only necessary, if the same language may be used with a different flag from country to country. The `flag` is the ___key___, it should be unique!*

<br>

__context.ts__

```ts
import React, {createContext} from 'react'
import type {languageType, languageContextType } from '@kekalma/language-selector'
import {emptyLanguage } from '@kekalma/language-selector'

export const languageContext = createContext<languageContextType>({
  language: emptyLanguage,
  setLanguage: (value: languageType):void =>{}
})
```

<br>

__info.tsx__  

_In this component you get an example, how to use the value from the context._

```tsx
import React, {useContext} from 'react'
import { languageContext } from './context'
import {languageContextType} from '@kekalma/language-selector'

type myProps = { context: React.Context<languageContextType> }

export default function Info(props : myProps) {
  const { language : selectedLanguage } = useContext(props.context)
  return (
    <span style={{margin: "0 5px"}}>Selected language: {selectedLanguage.name} ({selectedLanguage.code}_{selectedLanguage.flag})</span>
  )
}
```

_The currently selected value is stored in the following format (`languageType`):_

```text
{
  code: string,   // ISO language code (2 chars)
  name: string,   // Language name
  flag: string    // Flag code (2 chars)
}
```

<br>

## Property parameters

_Only the ___bold___ properties are obligatory, all others are optional, but you should use one of `context` or `onLanguageChange`._

|property|format|Description|
|---|:---:|---|
|__languages__|languageType[ ]|__(Required)__ The JSON list of the languages, defined in the example file above.|
|selectedLanguageFlag|flagCodeType|The initialy selected language. Default: first item.<br>`flagCodeType`: The string literal values of useable flag codes.|
| context| React.Context<br>\<languageContextType> | Required. The context, to store the state and the handler. See the above example for the format. |
|onLanguageChange|Function<br>(newLanguage: languageType, oldLanguage: languageType)|The callback function for the change event. It is called with two parameters, holding the new and the old language objects. |
|titleFormat|string|A definition of the freely formatted label text, put together with `\|Flag\|` `\|Name\|` `\|Code\|` `\|FlagCode\|` placeholder, where `Flag` represents the flag icon.|
|menuFormat|string|- same as the above - |
|align||`left` - left aligned<br>`right` - right aligned<br>`center` - centered<br>`auto` - automaticaly aligned right if it is the last item in the list<br>`center auto` - center aligned, but automaticaly aligned right if it is the last item in the list|
|format||`dropdown` : classic dropdown menu<br>`dropdown-ordered` : dropdown, but the currently selected item is not listed <br>`flat` : the selectable items appear in a row, under the title <br>`flat-reverse` : same as the previous, but right aligned<br>`linear` : the items are shown permanently in a row<br>`linear-ordered` : same as before, but the selected item comes first in the list<br>`horizontal` : same as the previous, but the list is shown only upon hover<br>`horizontal-reverse` : same as the previous, but right aligned|
|titleFont|string|CSS font type, like `"1rem bold Verdana"`|
|titleFontColor|string|CSS font color, like `"#11F"`|
|titleFontColorHover|string|CSS font color during hover|
|titleBgColor|string|CSS background color|
|titleBgColorHover|string|CSS background color during hover|
|titleFlagSize|number|The size of the flag icon in pixels (without any dimension)|
|menuFont|string|CSS font type for the menu items|
|menuFontColor|string|CSS font color|
|menuFontColorHover|string|CSS font color during hover|
|menuFontColorSelected|string|CSS font color of the currently selected item|
|menuBgColor|string|CSS background color for the menu items|
|menuBgColorHover|string|CSS background color for the menu items during hover|
|menuBgColorSelected|string|CSS background color for the currently selected menu item|
|menuFlagSize|number|The size of the flag icon in pixels (without any dimension)|
|menuStyleSelected|CSSProperties|Inline CSS definition for the currently selected menu item|
|titleStyle|CSSProperties|Inline CSS definition for the title|
|menuStyle|CSSProperties|Inline CSS definition for the list items|
|style|CSSProperties|Global inline CSS definiton object|

<br>

## __`Exported items:`__

|exported item|type|description|
|---|---|---|
|languageProps|type|All the properties listed above.|
|languageContextType|type|Context type definition.|
|languageType|type|Type holding the language properties: code, name, flag.|
|flagCodeType|type|The string literal values of useable flag codes.|
|emptyLanguage|object|The type `languageType` with empty values.|
|getLanguageByCode|function|__Usage__: getLanguageByCode(languages: languageType[], code: flagCodeType): languageType<br>__Input__: Use the array from `props.languages` and the 2 character language or flag `ISO code` as `flagCodeType`.<br>__Return__: An object of type `languageType` or if the code is not found, the `emptyLanguage`.|


<br>

## __`Format examples with property code samples:`__

### __`dropdown:`__

![Dropdown](./example_images/dropdown.jpg)

```JSON
titleFormat="|Flag| |Name|"
menuFormat="|Flag| |Name| (|Code|_|FlagCode|)"
format="dropdown"
align="left"
```

<br>

### __`dropdown-ordered:`__

![dropdown-ordered](./example_images/dropdown-ordered.jpg)

```JSON
titleFormat="|Flag| |Name|"
menuFormat="|Flag| |Name|"
format="dropdown-ordered"
```

<br>

### __`flat:`__

![dropdown-ordered](./example_images/flat.jpg)

```JSON
titleFormat="|Flag| |Name|"
menuFormat="|Flag| |Name|"
format="flat"
```

![dropdown-ordered](./example_images/flat_right.jpg)

```JSON
titleFormat="|Flag| |Name|"
menuFormat="|Flag| |Name|"
format="flat-reverse"
align="right"
```

![dropdown-ordered](./example_images/flat_center.jpg)

```JSON
titleFormat="|Flag| |Name|"
menuFormat="|Flag| |Name|"
format="flat"
align="center"
```

<br>

### __`linear:`__

![dropdown-ordered](./example_images/linear.jpg)

```JSON
titleFormat="|Flag| |Name|"
menuFormat="|Flag| |Name|"
format="linear-ordered"
```

<br>

<hr>
## __`Changelog:`__

|Version|What's new, description|
|:---:|:---|
|1.0.0|First official, working release.|
|1.0.1|Exporting the function `getLanguageByCode` and the type `flagCodeType`|

<br>

## License

MIT © [kissato70](https://github.com/kissato70)

<br>  

### Support the project >>> [Donation](https://bit.ly/kissato70_paypal_donate)

---
_Source: https://npm.io/package/@kekalma/language-selector · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._