tt_address for TYPO3

Employee directories, branch finders and contact lists have run on tt_address in TYPO3 for 20 years

Every company with multiple locations, departments or contact persons needs a structured display on the website. Who is responsible for which region? Where is the nearest branch? What contact details does the HR department have? Maintaining such information manually as text blocks in the CMS leads to inconsistencies: different formats, forgotten updates, no filtering capability.

tt_address is the oldest and most widely used address management extension for TYPO3. In use since TYPO3 v4 (2006), over 50,000 active installations (TER, 2026), actively maintained by the TYPO3 community. The extension stores contacts, persons and locations as structured records and outputs them via Fluid templates as lists, maps or detail pages.

Typical use cases

Employee directories for corporate websites. A company with 50 to 500 employees wants to show on the website who is responsible for which topic. tt_address stores per person: name, title, department, photo, email, phone, location. Output is rendered as a filterable list (by department, location) or as a detail page with vCard download. For companies with privacy concerns, visibility can be controlled per field.

Branch finders and location overviews. Companies with 10 to 500 locations (branches, offices, partners) use tt_address as the data foundation for a location finder. Each location has address, geocoordinates, opening hours and contact details. Map integration is handled through a separate extension (maps2 or Leaflet) that reads the geocoordinates from tt_address. Users search by postal code or city and see the nearest locations.

Contact lists for government agencies and associations. Municipalities, chambers and associations list contacts by responsibility: building authority, youth services, public order or chairman, treasurer, secretary. tt_address maps the organizational structure through categories or SysFolders. Output can be filtered by category and sorted alphabetically or by position.

Technical architecture

tt_address stores records in the tt_address table. Fields include: salutation, title, first name, last name, company, department, street, postal code, city, country, phone, fax, mobile, email, website, geocoordinates (latitude, longitude), image (FAL reference), categories and a description field (RichText).

Output runs through an Extbase plugin with list and detail actions. Fluid templates are fully customizable. By default, tt_address provides four layouts: simple list, grouped list (by category or location), detail view and vCard download (RFC 6350). Custom templates can be configured via TypoScript without PHP changes.

tt_address integrates with other extensions: maps2 and ext:leaflet for map integration, direct_mail and mail for newsletter sending (tt_address as recipient list), ke_search and indexed_search for full-text search across address data. Geocoordinates can be automatically determined from the postal address through a geocoding service (Google Maps API, Nominatim).

Categories (sys_category) are the primary mechanism for structuring. An employee can be assigned to multiple categories (e.g. “Sales” and “Munich Office”). The frontend output filters by category, enabling the display of department lists, location teams or thematic contact groups.

Common problems and solutions

Images not displaying. Since TYPO3 v10, tt_address uses FAL (File Abstraction Layer) for images. Older installations stored images as filenames in a field (not as FAL references). Solution: run the tt_address upgrade script that converts old image references to FAL references. For manual migration: place images in fileadmin/ and link them as sys_file_reference.

Geocoordinates missing for the branch finder. Addresses without latitude/longitude do not appear on the map. Manually entering coordinates for 200 locations is not practical. Solution: automate geocoding via scheduler task. tt_address itself does not offer geocoding, but Gosign deploys a cronjob that fills missing coordinates via the Nominatim API (OpenStreetMap, free, GDPR-compliant).

Data import from external systems. HR departments maintain employee data in SAP, Personio or another HR system. The data should appear automatically on the website. Solution: build a sync mechanism that imports CSV or JSON from the HR system and creates or updates tt_address records. Gosign implements this as a scheduler task with mapping configuration (which source field maps to which tt_address field).

Migration and version compatibility

tt_address actively supports TYPO3 v11, v12 and v13. The extension is co-maintained by Georg Ringer (the developer of the News extension) and follows a clear release cycle. Updates for new TYPO3 major versions typically appear within weeks of the LTS release.

For projects switching from a custom address management solution to tt_address, data migration is straightforward: import existing data via SQL or CSV into the tt_address table, create FAL references for images, assign categories. The effort for 200 records is half a day to one day, including template customization.

Those upgrading from an older TYPO3 (v8, v9) with tt_address v4 or v5 should include the extension upgrade in one step. The field structure changed slightly between major versions (v5 to v6: switch to FAL images, v7: new fields), but tt_address provides upgrade wizards that automate the transition.

For companies without an existing address management solution weighing their options, Gosign recommends tt_address as the starting point for all scenarios under 5,000 records. The extension is stable, well documented, has a large community and integrates seamlessly with other TYPO3 extensions. For larger data volumes or complex sync requirements (real-time synchronization with SAP HR, Active Directory or CRM systems), Gosign builds a custom synchronization layer that uses tt_address for frontend output but leaves data ownership with the source system.

The initial setup of a tt_address project (installation, template customization, category structure, geocoding setup) is 2 to 4 development days. A branch finder with map integration and postal code search comes to 5 to 8 days, including Leaflet or maps2 integration.