# @damian-buho/support-ukraine [](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md)     [](CONTRIBUTING.md)  [](https://github.com/damian-buho/support-ukraine/actions/workflows/pipeline.yaml) [](https://github.com/damian-buho/support-ukraine/actions/workflows/github-code-scanning/codeql) [](https://snyk.io/test/npm/%40damian-buho%2Fsupport-ukraine) [](https://api.reuse.software/info/github.com/damian-buho/support-ukraine) - Browser library that adds a Ukraine-support charity banner to any website. - Shows randomly selected Ukrainian charity localized to the visitor's language and respect RTL scripts. - You can choose kinds of charities. - Inspired by [hejny/Ukraine](https://github.com/hejny/Ukraine). ## Screenshots [Demo / Play with settings](https://damian-buho.github.io/support-ukraine/dev.html)    ## Install ### npm ```shell npm install @damian-buho/support-ukraine ``` ### CDN (no build step) ```html ``` ## Usage ```ts import {supportUkraineBlock} from '@damian-buho/support-ukraine' // Auto-detect locale from navigator.language await supportUkraineBlock() // Force a specific locale await supportUkraineBlock({locale: 'es'}) ``` The banner is prepended to `document.body` by default. It displays a randomly selected charity with the format: > 🇺🇦 Support Ukraine: Come Back Alive: Strengthening Ukraine's defense The entire block is a clickable link to the charity's donation page. ## Options | Option | Type | Default | Description | |---------------|-------------------------------------|-------------------|----------------------------------------------------------------------------------------------------------------------| | `element` | `HTMLElement` | `document.body` | Target mount element for the banner | | `mode` | `'shift' \| 'overlap' \| 'replace'` | `'shift'` | `'shift'` pushes page content down, `'overlap'` floats on top, `'replace'` swaps a same-class `

` placeholder | | `fontSize` | `string` | `'0.875rem'` | Banner font size | | `tags` | `CharityTag[]` | _(all)_ | Filter charities by category: `'military'`, `'humanitarian'`, `'animals'` | | `dontRepeat` | `boolean` | `true` | Avoid repeating charities across page loads using `localStorage` | | `isInConsole` | `boolean` | `true` | Log the selected charity to the dev console | | `locale` | `string` | _(auto-detected)_ | Override the auto-detected BCP 47 language tag | ### Filtering by category Show only military charities: ```ts await supportUkraineBlock({tags: ['military']}) ``` ### Replace mode (no layout shift) Use `replace` mode to swap a same-class `

` placeholder element so the banner takes its place without shifting page content: ```html

``` ```ts await supportUkraineBlock({mode: 'replace'}) ``` The banner finds the first `

` inside the mount element and replaces it in place. If no placeholder is found, it falls back to prepending. This eliminates cumulative layout shift (CLS) because the placeholder already reserves the exact space the banner needs. ### Disabling repeat prevention Allow the same charity to appear on every page load: ```ts await supportUkraineBlock({dontRepeat: false}) ``` ## Locale support The banner is translated to the visitor's language automatically. The following locales are supported: | Language | Code | RTL | |------------|------|--------------------| | Arabic | `ar` | Yes | | Chinese | `zh` | | | Dutch | `nl` | | | English | `en` | (default fallback) | | French | `fr` | | | German | `de` | | | Hindi | `hi` | | | Italian | `it` | | | Japanese | `ja` | | | Korean | `ko` | | | Polish | `pl` | | | Portuguese | `pt` | | | Spanish | `es` | | | Swedish | `sv` | | | Thai | `th` | | | Ukrainian | `uk` | | RTL scripts are detected automatically and the banner direction is set accordingly. ## Architecture ``` src/ ├── index.ts # Public API: supportUkraineBlock() ├── types.ts # Charity, SupportUkraineBlockOptions, etc. ├── i18n.ts # Locale detection, loading, merging ├── locales/ # Per-locale translation files ├── charities.yaml # Built-in charity database └── styles.scss # Banner CSS (compiled by tsup) ``` ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines. ## License MIT