Setting up alternative texts for 1C-Bitrix images

Setting Up Alternative Text for Images in 1C-Bitrix

Empty alt is not just an accessibility issue. It's an SEO loss: Google uses alt-text as a text signal for image ranking in search. An online store with thousands of products where alt is either empty or equals "image.jpg" — that's thousands of missed entry points from Google Images. In Bitrix, alt-texts don't fill automatically anywhere in standard components.

Where Alt is Stored in Infoblock

Bitrix stores image alt-text in the b_file table — DESCRIPTION field. This field is filled in admin when uploading a file. Also for F-type properties, there's a DESCRIPTION field in b_iblock_element_property — this is the caption for a specific image use in an element, independent of the b_file caption.

Priority when displaying: if element property has DESCRIPTION — use it; if not — take DESCRIPTION from b_file; if empty there too — generate from product name.

In component template:

$fileId = $arResult['DETAIL_PICTURE']['ID'];
$fileData = \CFile::GetFileArray($fileId);

$alt = '';
// Priority 1: element property description
if (!empty($arResult['PROPERTIES']['DETAIL_PICTURE']['DESCRIPTION'])) {
    $alt = $arResult['PROPERTIES']['DETAIL_PICTURE']['DESCRIPTION'];
}
// Priority 2: file description
elseif (!empty($fileData['DESCRIPTION'])) {
    $alt = $fileData['DESCRIPTION'];
}
// Priority 3: product name
else {
    $alt = $arResult['NAME'];
}

$alt = htmlspecialcharsEx($alt);

Bulk Filling Alt for Existing Products

If store ran for years with thousands of images without alt — need a bulk fill script. Logic: go through all infoblock elements, take DETAIL_PICTURE and MORE_PHOTO, check DESCRIPTION in b_file, if empty — fill from element name.

Script runs via Bitrix agent or CLI:

$res = \CIBlockElement::GetList(
    ['ID' => 'ASC'],
    ['IBLOCK_ID' => CATALOG_IBLOCK_ID],
    false,
    ['nTopCount' => 100, 'iNumPage' => $page],
    ['ID', 'NAME', 'DETAIL_PICTURE']
);

while ($el = $res->GetNextElement()) {
    $fields = $el->GetFields();
    if (empty($fields['DETAIL_PICTURE'])) continue;

    $fileId = $fields['DETAIL_PICTURE'];
    $fileData = \CFile::GetFileArray($fileId);

    if (empty($fileData['DESCRIPTION'])) {
        $DB->Query("UPDATE b_file SET DESCRIPTION = '" .
            $DB->ForSql($fields['NAME']) .
            "' WHERE ID = " . (int)$fileId);
    }
}

Direct UPDATE to b_file is faster than CFile::Update() — it clears cache for each file separately.

Alt for Images in News and Article Infoblocks

For images inserted via TinyMCE in DETAIL_TEXT field, alt is filled directly in editor. Problem: if content managers ignore the alt field in insert dialog, images get empty alt="" or alt="image".

Solution at editor level: in TinyMCE settings (config file in template) add alt field requirement via custom plugin or form insertion validation. Another approach — post-process HTML on save via OnBeforeIBlockElementUpdate handler: parse DETAIL_TEXT with DOMDocument, find <img> without alt and substitute article title.

Decorative Images

Icons, dividers, and decorative background elements should have empty alt="" — an intentionally empty attribute signaling screen reader to ignore the image. Error — to not specify alt at all (WCAG 1.1.1 violation) or specify descriptive text for decoration (noise for assistive technology). In Bitrix templates, icons often render via <img> — should replace them with inline SVG with aria-hidden="true" or add explicit alt="".