> For the complete documentation index, see [llms.txt](https://docs.babelshark.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.babelshark.net/dev/api-reference/language-drop-down-specs.md).

# Language drop-down specs

To embed an automatic language drop-down to your page use the following HTML element:

```html
<span 
    class="bs-activator" 
    [data-drop="auto|right|left|right-top|left-top"]
    [data-theme="light|dark"]
    [data-css="https://...."]
    [data-dialog-style="...."]
    [data-flag-class="...."]
    [data-middle-text="...."]
    [data-middle-text-class="...."]
    [data-hide-chevron]
    ></span>
```

The minimal code snippet is `<span class="bs-activator"></span>`.

### Configuration attributes

<details>

<summary>class</summary>

"bs-activator"

Add your own CSS classes alongside bs-activator to style the generated button. These classes are preserved; bs-activator itself is replaced with bs-widget-wrapper.

</details>

<details>

<summary>data-drop</summary>

The direction to open the language drop-down:

* auto - automatically select the direction
* right - drop down to the right and below the language selector
* left - drop down to the left and below
* right-top - open to the right and over the language selector
* left-top - open to the left and over the language selector

</details>

<details>

<summary>data-theme</summary>

Overall coloring theme of the widget and its activator:

* light (default) - light background, dark text
* dark - dark background, light text

</details>

<details>

<summary>data-css</summary>

Embed the speficic CSS file in to the drop-down iframe.

</details>

<details>

<summary>data-dialog-style</summary>

CSS inline styles for widget dialog (iframe). Useful to set `z-index` and similar properties.

Note: `data-drop` attribute controls widget position.

</details>

<details>

<summary>data-flag-class</summary>

CSS classes to add to the flag image, separated by spaces. Use them to give the flag the same size and spacing as your menu icons. The built-in flag classes are preserved.

The flag has default inline styles. Use `!important` in your CSS to override its size, margins and shadow.

</details>

<details>

<summary>data-middle-text</summary>

Plain text to display after the flag and before the dropdown arrow. For example, `data-middle-text="Language"` adds a “Language” label.

This text is not translated by BabelShark. HTML is never interpreted.

</details>

<details>

<summary>data-middle-text-class</summary>

CSS classes to add to the text specified by `data-middle-text`, separated by spaces.

</details>

<details>

<summary>data-hide-chevron</summary>

Hides the dropdown arrow when this attribute is present. Omit it to keep the arrow.

Note: `data-hide-chevron="false"` still hides the arrow, because only the presence of the attribute is checked.

</details>

### Custom menu button

You can make the language selector look like a regular menu item: show a flag, add a “Language” label and hide the dropdown arrow:

```html
<button type="button"
        class="bs-activator language-menu-item"
        data-drop="auto"
        data-flag-class="language-menu-flag"
        data-middle-text="Language"
        data-middle-text-class="language-menu-text"
        data-hide-chevron></button>
```

The class names in this example are yours to define. BabelShark keeps the snippet’s classes on the generated button (except `bs-activator`), so you can use your existing menu styles. A `<button>` snippet remains a native button and can be activated with the keyboard.

For a square flag area, you can start with these styles:

```css
.language-menu-item {
  gap: 0.5rem;
}

.language-menu-flag {
  width: 1.25rem !important;
  height: 1.25rem !important;
  margin: 0 !important;
  box-shadow: none !important;
  object-fit: contain;
}

.language-menu-text {
  flex: 1;
  text-align: left;
}
```

`object-fit: contain` keeps the flag’s proportions inside the square area.

These optional attributes affect only the button’s appearance, not how languages are selected. Without them, the usual flag-and-arrow button stays unchanged.